@forwardimpact/libwiki 0.2.25 → 0.2.27

package/src/wiki-sync.js

@@ -1,4 +1,17 @@
 import path from "node:path";
+import { scanConflictMarkers } from "./conflict-markers.js";
+import { GITATTRIBUTES_FILE, SINGLETON_PATHS } from "./constants.js";
+import { ensureMetricsCsvMergeAttribute } from "./gitattributes.js";
+import { parseDiff, findAbsent, makeDetection, normLine } from "./integrity.js";
+import { scanPushWindow, appendOverrideRecord } from "./secret-gate.js";
+
+/** The branch the wiki clone publishes (hard-coded in fetch / rebase / push). */
+const BRANCH = "master";
+const REMOTE = "origin";
+const REMOTE_BRANCH = `${REMOTE}/${BRANCH}`;
+
+/** The commit range a wiki push introduces relative to the remote it reconciles against. */
+const PUSH_RANGE = "origin/master..HEAD";
 
 /** Error thrown when a wiki pull encounters a rebase conflict that cannot be resolved automatically. */
 export class WikiPullConflict extends Error {
@@ -10,6 +23,95 @@ export class WikiPullConflict extends Error {
   }
 }
 
+// A push rejected because the remote tip moved (non-fast-forward) is the
+// re-apply loop's retry signal; an auth or network failure is not contention.
+// git surfaces a rejection on stderr with these markers.
+const PUSH_REJECTION_RE =
+  /\b(rejected|non-fast-forward|fetch first|tip of your current branch is behind)\b/i;
+
+/** Whether a thrown push error is a non-fast-forward rejection (vs. auth/network). */
+function isPushRejection(err) {
+  const text = `${err?.stderr ?? ""}\n${err?.message ?? ""}`;
+  return PUSH_REJECTION_RE.test(text);
+}
+
+/**
+ * Error thrown when the ancestry guard refuses to commit or push because the
+ * relationship between the history that would be published and the remote
+ * branch cannot be positively confirmed. `kind` is `"unrelated"`
+ * (confirmed no shared history) or `"unverifiable"` (the relationship could be
+ * neither confirmed nor refuted). The two kinds carry distinct messages so the
+ * operator knows which state they are recovering from.
+ */
+export class AncestryRefusal extends Error {
+  /**
+   * @param {"unrelated"|"unverifiable"} kind
+   * @param {string} message - Recovery-naming message.
+   */
+  constructor(kind, message) {
+    super(message);
+    this.name = "AncestryRefusal";
+    this.kind = kind;
+  }
+}
+
+/**
+ * Error thrown when a registered-singleton operation cannot land within the
+ * bounded re-apply budget: contention recurred on each round, so the publish
+ * fails loud rather than resolving the contended hunk textually.
+ */
+export class WikiSyncConflict extends Error {
+  /** @param {string[]} paths @param {string} reason */
+  constructor(paths, reason) {
+    super(`wiki sync conflict on ${paths.join(", ")} (${reason})`);
+    this.name = "WikiSyncConflict";
+    this.paths = paths;
+    this.reason = reason;
+  }
+}
+
+/**
+ * The refusal reason taxonomy for {@link WikiSync.commitAndPush}. A refusal is
+ * surfaced in the result rather than thrown, so callers reading the result keep
+ * working; `WikiSyncRefusal.result(reason, details)` builds that result object.
+ * `reason` is one of `mid-merge`, `stranded-merge`, `would-publish-markers`,
+ * `introduced-scan-failed`; `workAt` (only for `stranded-merge`) names where
+ * retained work lives. The reason set is additive to the existing `clean` and
+ * `pushed` outcomes, so a future refusal taxonomy on this flow can union new
+ * reasons in without rewriting the existing ones.
+ */
+export class WikiSyncRefusal {
+  /** @type {readonly string[]} The recognized refusal reasons. */
+  static REASONS = Object.freeze([
+    "mid-merge",
+    "stranded-merge",
+    "would-publish-markers",
+    "introduced-scan-failed",
+  ]);
+
+  /**
+   * Build a `commitAndPush` refusal result.
+   * @param {string} reason - One of {@link WikiSyncRefusal.REASONS}.
+   * @param {{workAt?: string}} [details] - `workAt` names where retained work lives.
+   * @returns {{pushed: false, reason: string, workAt?: string}}
+   */
+  static result(reason, { workAt } = {}) {
+    const result = { pushed: false, reason };
+    if (workAt) result.workAt = workAt;
+    return result;
+  }
+}
+
+// Markers introduced into a prose markdown surface may be legitimately quoted
+// inside a fenced code block (the false-positive surface Layer 1 exempts).
+// STATUS.md is data, not prose — its fenced rows are never legitimately marked
+// — and non-markdown files (e.g. metrics CSVs) have no quoted-form idiom, so
+// neither is fence-exempt on the publish path.
+function pushFenceExempt(filePath) {
+  const base = path.basename(filePath);
+  return filePath.endsWith(".md") && base !== "STATUS.md";
+}
+
 /**
  * Consolidates the wiki repository's pull / rebase / conflict-resolve / push
  * flow over an injected {@link import('@forwardimpact/libutil').GitClient}.
@@ -134,33 +236,118 @@ export class WikiSync {
    * rebase and merge fallback then run with --autostash because that residue
    * stays uncommitted in the tree.
    *
+   * Ancestry guard: before the commit and again before the push,
+   * {@link AncestryRefusal} is thrown when the published history's relationship
+   * to `origin/master` cannot be positively confirmed — a detached HEAD, an
+   * unborn HEAD or unrelated history against an existing remote branch, or a
+   * remote that cannot be observed. A new wiki's first publication is allowed
+   * only on positive evidence the remote branch is absent (a non-swallowed
+   * `ls-remote`); mere absence of the local remote-tracking ref never grants
+   * it, and the allowance is re-derived from live git on every call so a failed
+   * first publication is re-judged rather than auto-re-granted. The guard
+   * creates no commit, attempts no push, and adds no working-tree changes.
+   *
+   * Before the gates, the metrics-CSV union merge declaration is ensured in
+   * `.gitattributes`. When the ensure writes the file, the commit must carry it
+   * regardless of the session's payload: on the pathspec-scoped path the
+   * declaration is outside `paths` and would otherwise be autostashed aside, and
+   * on a no-payload sync there would be no commit at all. So `.gitattributes` is
+   * appended to the effective commit pathspec only when the ensure changed it;
+   * when it is already present-and-correct, behavior is byte-identical to a
+   * commit-and-push that ensures nothing.
+   *
+   * **Singleton merge discipline.** The discipline applies when a
+   * rebase conflict arises for a *registered* row-structured singleton (the
+   * single committed path is in `SINGLETON_PATHS`) and the caller supplied a
+   * `reapply` operation. The contended hunk is then never resolved textually.
+   * The conflicting local commit is dropped with `resetSoft`, which preserves
+   * the working tree. Only the registered file is reset to the fresh tip with
+   * `checkoutPaths`. The operation is re-derived against that tip's content,
+   * re-committed, and pushed, bounded by `maxReapply`. A rejected push (the tip
+   * moved again) drives the retry; exhaustion fails loud with
+   * {@link WikiSyncConflict}. Foreign rows and untouched prose ride through from
+   * the tip. Without a `reapply` the conflict keeps the `-X ours` fallback, so
+   * prose surfaces and unregistered paths stay on the side-biased behavior.
+   *
+   * **Fail-closed secret gate.** After the reconcile and before the push, the
+   * content the push introduces (the commit range `origin/master..HEAD`) is
+   * secret-scanned fail-closed. A detected secret or an unavailable scanner
+   * refuses the push with a distinct reason and no remote contact, unless the
+   * matching off-by-default override is set in the environment —
+   * `FIT_WIKI_SECRET_OVERRIDE` permits a finding, `FIT_WIKI_SCANNER_ABSENT_OK`
+   * permits a scanner absence. Each override appends an audited line to the wiki
+   * tree's `secret-overrides.log` before the push. A *network/credential* push
+   * failure is distinct: it still degrades to "saved locally" (the preserved
+   * fire-and-forget behaviour).
+   *
    * @param {string} message - The commit message.
    * @param {string[]} [paths] - Pathspecs limiting what gets committed.
+   * @param {{reapply?: (freshText: string) => string | null, maxReapply?: number}} [options]
+   *   `reapply` re-derives the registered file's content from the operation's
+   *   own row edit against the fresh tip text; returns the new text or null when
+   *   the op is already satisfied on the tip.
+   * @returns {Promise<{pushed: boolean, reason: "pushed"|"clean"|"secret-detected"|"scanner-unavailable"|"mid-merge"|"stranded-merge"|"would-publish-markers"|"introduced-scan-failed", findings?: Array<{file: string, line: number, rule: string}>, detections?: object[], workAt?: string}>}
+   * @throws {AncestryRefusal} When the published history cannot be verified.
+   * @throws {WikiSyncConflict} When the re-apply budget is exhausted.
    */
-  async commitAndPush(message, paths) {
-    if (!(await this.isClean(paths))) {
-      if (paths?.length) {
-        await this.#git.commitPaths(message, paths, { cwd: this.#wikiDir });
+  async commitAndPush(message, paths, { reapply, maxReapply = 3 } = {}) {
+    // Guard 1 (hole 1): refuse mid-merge before staging. An abandoned merge
+    // leaves unmerged hunks or a pinned MERGE_HEAD; sweeping them would
+    // silently "complete" the merge and publish the markers. Decidable from
+    // the index/working tree alone, so it holds on a shallow clone.
+    if (await this.#git.isMidMerge({ cwd: this.#wikiDir })) {
+      return WikiSyncRefusal.result("mid-merge");
+    }
+    await this.#assertPublishable();
+    const gitattributesChanged = ensureMetricsCsvMergeAttribute(
+      this.#wikiDir,
+      this.#runtime.fsSync,
+    ).changed;
+    // The metrics-CSV declaration must be committed when it was just written,
+    // even on the pathspec-scoped path; fold it into the effective pathspec.
+    // On a no-payload sweep (`paths` absent), this becomes the sole pathspec
+    // [GITATTRIBUTES_FILE], so provisioning still produces exactly one commit
+    // rather than sweeping the whole tree via commitAll.
+    const commitPaths = gitattributesChanged
+      ? [...(paths ?? []), GITATTRIBUTES_FILE]
+      : paths;
+    if (!(await this.isClean(commitPaths))) {
+      if (commitPaths?.length) {
+        await this.#git.commitPaths(message, commitPaths, {
+          cwd: this.#wikiDir,
+        });
       } else {
         await this.#git.commitAll(message, { cwd: this.#wikiDir });
       }
     }
     if (!(await this.#hasCommitsAhead())) {
-      return { pushed: false, reason: "clean" };
+      return { pushed: false, reason: "clean", detections: [] };
     }
+    await this.#assertPublishable();
     await this.fetch();
     const rebase = await this.#git.rebase("origin/master", {
       cwd: this.#wikiDir,
       autostash: true,
     });
     if (rebase.exitCode !== 0) {
-      await this.#git.rebaseAbort({ cwd: this.#wikiDir });
-      await this.#git.mergeOursStrategy({
-        cwd: this.#wikiDir,
-        ref: "origin/master",
-        autostash: true,
+      const resolved = await this.#resolveRebaseConflict(message, paths, {
+        reapply,
+        maxReapply,
       });
+      if (resolved) return resolved;
     }
+    // Guard 3 (hole 3 / Layer 2): refuse to push commits that introduce an
+    // unresolved conflict block.
+    const markerRefusal = await this.#refuseIfIntroducedMarkers();
+    if (markerRefusal) return markerRefusal;
+    // Capture the pushed delta now: HEAD is the final (rebased/merged) local
+    // tip and origin/master is still the pre-push base.
+    const pushedDelta = await this.#capturePushedDelta();
+    // Fail-closed secret gate. Scan exactly the commits this push introduces
+    // (the reconcile above made the range correct) before any remote contact;
+    // a finding or missing scanner refuses unless its own override is set.
+    const refusal = await this.#gateOrRefuse();
+    if (refusal) return refusal;
     // Resolve auth first so a misconfigured `resolveToken` still surfaces; the
     // push itself is fire-and-forget like WikiRepo (which ignored the push
     // result and reported pushed:true regardless), so a network/credential
@@ -171,7 +358,233 @@ export class WikiSync {
     } catch {
       // Intentionally ignored — preserves WikiRepo's fire-and-forget push.
     }
-    return { pushed: true, reason: "pushed" };
+    const detections = await this.#tier1Probe(pushedDelta);
+    return { pushed: true, reason: "pushed", detections };
+  }
+
+  /**
+   * Capture the `origin/master..HEAD` delta for the post-push tier-1 probe. A
+   * two-tree range diff (not a single-commit show) is correct even when HEAD is
+   * a merge commit. Detection-only: a capture failure degrades to `null` so the
+   * probe never gates the push it follows.
+   * @returns {Promise<string|null>}
+   */
+  async #capturePushedDelta() {
+    try {
+      return await this.#git.diffRange("origin/master HEAD", {
+        cwd: this.#wikiDir,
+      });
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Resolve a failed rebase against the fresh tip. Aborts the rebase, then for a
+   * registered singleton with a `reapply` op re-derives the row against the tip
+   * via the bounded re-apply loop; otherwise falls back to the `-X ours` merge
+   * with failure allowance (Guard 2). A conflicting merge is aborted and refused
+   * rather than left mid-merge for the next sweep (hole 1) to publish.
+   * @param {string} message - The commit message.
+   * @param {string[]} [paths] - Pathspecs committed.
+   * @param {{reapply?: (freshText: string) => string | null, maxReapply: number}} options
+   * @returns {Promise<object|null>} A terminal result (re-apply outcome or a
+   *   stranded-merge refusal), or null when the conflict resolved and the push
+   *   should proceed.
+   */
+  async #resolveRebaseConflict(message, paths, { reapply, maxReapply }) {
+    await this.#git.rebaseAbort({ cwd: this.#wikiDir });
+    const registered =
+      typeof reapply === "function" &&
+      paths?.length === 1 &&
+      paths.every((p) => SINGLETON_PATHS.has(p));
+    if (registered) {
+      return this.#reapplyLoop(message, paths, reapply, maxReapply);
+    }
+    // Guard 2 (hole 2/3): the ours-strategy fallback runs with failure
+    // allowance. On a conflict it would otherwise throw and strand a mid-merge
+    // tree for the next sweep (hole 1) to publish; instead abort and refuse,
+    // reporting where retained work went (the autostash stash).
+    const merge = await this.#git.mergeOursStrategy({
+      cwd: this.#wikiDir,
+      ref: "origin/master",
+      autostash: true,
+      allowFailure: true,
+    });
+    if (merge.exitCode !== 0) {
+      await this.#git.mergeAbort({ cwd: this.#wikiDir });
+      return WikiSyncRefusal.result("stranded-merge", { workAt: "stash" });
+    }
+    return null;
+  }
+
+  /**
+   * Scan the content introduced by `origin/master..HEAD` for unresolved
+   * conflict-marker blocks (Guard 3). Runs after the fetch + rebase/merge
+   * resolve, so the diff is against the freshly-fetched origin tip; pre-existing
+   * origin corruption is on the base side, never the added side, so an unrelated
+   * writer's push is not blocked. A throw from the scan (unresolvable ref on a
+   * shallow clone) refuses with a reason — never a silent pass.
+   * @returns {Promise<{pushed: false, reason: string}|null>} A refusal result, or
+   *   null when nothing introduced would publish a marker.
+   */
+  async #refuseIfIntroducedMarkers() {
+    let introduced;
+    try {
+      introduced = await this.#git.introducedByFile("origin/master..HEAD", {
+        cwd: this.#wikiDir,
+      });
+    } catch {
+      return WikiSyncRefusal.result("introduced-scan-failed");
+    }
+    for (const [filePath, addedText] of introduced) {
+      const hits = scanConflictMarkers(addedText, {
+        fenceExempt: pushFenceExempt(filePath),
+      });
+      if (hits.length > 0) {
+        return WikiSyncRefusal.result("would-publish-markers");
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Tier-1 post-push integrity probe: re-fetch the origin tip and verify the
+   * just-pushed delta — the full delta including shared surfaces —
+   * is still content-present, returning detections for any absence. Reads only;
+   * any error degrades to no detections so the probe never gates the push.
+   * @param {string|null} pushedDelta - `diffRange` text of the pushed delta.
+   * @returns {Promise<object[]>}
+   */
+  async #tier1Probe(pushedDelta) {
+    try {
+      if (pushedDelta == null) return [];
+      const changes = parseDiff(pushedDelta);
+      if (changes.length === 0) return [];
+      // A new post-push fetch advances origin/master to the current tip.
+      await this.fetch();
+      const homes = [
+        ...new Set(changes.map((c) => c.home).filter((h) => h !== "/dev/null")),
+      ];
+      const tipText = (
+        await Promise.all(
+          homes.map((home) =>
+            this.#git.showFile("origin/master", home, { cwd: this.#wikiDir }),
+          ),
+        )
+      )
+        .filter((t) => t != null)
+        .join("\n");
+      const now = this.#runtime.clock.now();
+      return findAbsent(changes, tipText, normLine).map((a) =>
+        makeDetection({
+          tier: 1,
+          contentId: a.contentId,
+          pushHome: a.pushHome,
+          now,
+        }),
+      );
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Re-apply a registered singleton operation against the fresh remote tip,
+   * bounded by `maxReapply` rounds. The caller has already aborted the rebase.
+   * Each round: refresh the tip, drop the stale local commit (`resetSoft`,
+   * working tree untouched so foreign residue survives), reset only the
+   * registered file to the tip (`checkoutPaths`, tolerating a tip that lacks
+   * it), re-derive via `reapply`, and — when the op still changes the tip —
+   * re-commit and push. A rejected push (the tip moved again) loops; an
+   * unchanged op is already satisfied; bound exhaustion throws.
+   */
+  async #reapplyLoop(message, paths, reapply, maxReapply) {
+    const filePath = path.join(this.#wikiDir, paths[0]);
+    for (let round = 0; round < maxReapply; round++) {
+      await this.fetch();
+      await this.#git.resetSoft("origin/master", { cwd: this.#wikiDir });
+      // Reset only the registered file to the tip. `resetSoft` leaves the
+      // working tree (so the dropped commit's copy of the file may linger), so
+      // a non-zero checkout — the tip lacks the file (a founding write) — means
+      // the fresh base is empty, NOT the lingering local copy.
+      const checkout = await this.#git.checkoutPaths("origin/master", paths, {
+        cwd: this.#wikiDir,
+        allowMissing: true,
+      });
+      const tipHasFile = (checkout?.exitCode ?? 0) === 0;
+      const freshText =
+        tipHasFile && this.#runtime.fsSync.existsSync(filePath)
+          ? this.#runtime.fsSync.readFileSync(filePath, "utf-8")
+          : "";
+      const newText = reapply(freshText);
+      if (newText === null) {
+        // The op is already satisfied on the tip; HEAD now equals the tip.
+        return { pushed: false, reason: "already-satisfied" };
+      }
+      this.#runtime.fsSync.writeFileSync(filePath, newText);
+      await this.#git.commitPaths(message, paths, { cwd: this.#wikiDir });
+      try {
+        await this.#authed().push("origin", "master", { cwd: this.#wikiDir });
+        return { pushed: true, reason: "reapplied" };
+      } catch (err) {
+        // Only a rejected push (the tip moved again) is a retry signal. An auth
+        // or network failure is not contention: rethrow it so the caller
+        // degrades to "saved locally" rather than burning the budget and
+        // misreporting a conflict that never happened.
+        if (!isPushRejection(err)) throw err;
+      }
+    }
+    throw new WikiSyncConflict(paths, "reapply-bound");
+  }
+
+  /**
+   * Run the secret gate over the push window and decide whether to refuse.
+   * Returns a refusal envelope to short-circuit the push, or `null` to proceed
+   * (clean, or an override that wrote its audit record). An override appends a
+   * secret-free line to `secret-overrides.log` and commits it into the push
+   * range before returning `null`.
+   *
+   * @returns {Promise<{pushed: false, reason: "secret-detected"|"scanner-unavailable", findings?: Array<{file: string, line: number, rule: string}>}|null>}
+   */
+  async #gateOrRefuse() {
+    const env = this.#runtime.proc.env;
+    const verdict = await scanPushWindow({
+      runtime: this.#runtime,
+      wikiDir: this.#wikiDir,
+      range: PUSH_RANGE,
+    });
+    if (verdict.status === "finding") {
+      const reason = env.FIT_WIKI_SECRET_OVERRIDE;
+      if (!reason) {
+        return {
+          pushed: false,
+          reason: "secret-detected",
+          findings: verdict.findings,
+        };
+      }
+      await appendOverrideRecord({
+        runtime: this.#runtime,
+        gitClient: this.#git,
+        wikiDir: this.#wikiDir,
+        klass: "finding",
+        reason,
+        findings: verdict.findings,
+      });
+    } else if (verdict.status === "scanner-absent") {
+      const reason = env.FIT_WIKI_SCANNER_ABSENT_OK;
+      if (!reason) {
+        return { pushed: false, reason: "scanner-unavailable" };
+      }
+      await appendOverrideRecord({
+        runtime: this.#runtime,
+        gitClient: this.#git,
+        wikiDir: this.#wikiDir,
+        klass: "scanner-absent",
+        reason,
+      });
+    }
+    return null;
   }
 
   async #hasCommitsAhead() {
@@ -180,4 +593,108 @@ export class WikiSync {
     });
     return count > 0;
   }
+
+  /** Whether the wiki clone is shallow (has a `.git/shallow` file). */
+  #isShallow() {
+    return this.#runtime.fsSync.existsSync(
+      path.join(this.#wikiDir, ".git", "shallow"),
+    );
+  }
+
+  /**
+   * Refuse, before any commit or push, whenever the relationship between the
+   * history that would be published (the `master` branch ref, never bare HEAD)
+   * and the remote branch can be neither confirmed nor refuted. Implements the
+   * the ancestry decision table; throws {@link AncestryRefusal} on refusal and
+   * returns silently when publication is verified or the remote is positively
+   * empty. The emptiness probe runs only on the absent-tracking-ref path, so
+   * the healthy hot path adds no remote round-trip.
+   */
+  async #assertPublishable() {
+    const cwd = this.#wikiDir;
+
+    // 1. Detached HEAD: the push publishes the branch ref, not HEAD, so the
+    //    session's commits would be silently lost. Verify nothing — refuse.
+    if ((await this.#git.headBranch({ cwd })) !== BRANCH) {
+      throw new AncestryRefusal(
+        "unverifiable",
+        "fit-wiki: refusing to publish — HEAD is detached, so the configured " +
+          "branch would be pushed instead of your work. Re-clone the wiki.",
+      );
+    }
+
+    // 2. Establish whether the remote branch is present. A resolvable local
+    //    remote-tracking ref is sufficient; otherwise probe the remote (the
+    //    only added round-trip, and only here).
+    const branchPresent = await this.#git.refExists(REMOTE_BRANCH, { cwd });
+    if (!branchPresent) {
+      let observed;
+      try {
+        observed = await this.#git.remoteBranchExists(REMOTE, BRANCH, { cwd });
+      } catch {
+        throw new AncestryRefusal(
+          "unverifiable",
+          "fit-wiki: refusing to publish — could not observe the remote to " +
+            "verify ancestry; the local change is not published.",
+        );
+      }
+      // Positive evidence the remote branch is absent ⇒ empty-new-wiki.
+      if (!observed) return;
+      // Remote branch present but no local tracking ref: fetch it into the
+      // tracking ref so the unborn-HEAD and merge-base steps below judge
+      // against the probed branch tip rather than an unresolvable ref.
+      try {
+        await this.#git.fetch(
+          REMOTE,
+          `${BRANCH}:refs/remotes/${REMOTE_BRANCH}`,
+          {
+            cwd,
+          },
+        );
+      } catch {
+        throw new AncestryRefusal(
+          "unverifiable",
+          "fit-wiki: refusing to publish — could not fetch the remote branch " +
+            "to verify ancestry; the local change is not published.",
+        );
+      }
+    }
+
+    // 3. Branch present + unborn HEAD ⇒ confirmed unrelated.
+    if (!(await this.#git.refExists("HEAD", { cwd }))) {
+      throw new AncestryRefusal(
+        "unrelated",
+        "fit-wiki: refusing to publish — HEAD is unborn but the remote " +
+          "branch exists. Re-clone the wiki.",
+      );
+    }
+
+    // 4. Shared ancestry within the fetched window ⇒ allow.
+    if (await this.#git.mergeBaseExists(REMOTE_BRANCH, "HEAD", { cwd })) return;
+
+    // 5. No merge-base on a complete clone ⇒ confirmed unrelated.
+    if (!this.#isShallow()) {
+      throw new AncestryRefusal(
+        "unrelated",
+        "fit-wiki: refusing to publish — local history is unrelated to the " +
+          "remote branch. Re-clone the wiki.",
+      );
+    }
+
+    // 6. Shallow clone: deepen to full history, then re-judge.
+    const deepen = await this.#git.fetchDeepen(REMOTE, BRANCH, { cwd });
+    if (deepen.exitCode !== 0) {
+      throw new AncestryRefusal(
+        "unverifiable",
+        "fit-wiki: refusing to publish — could not deepen history to verify " +
+          "ancestry; the local change is not published.",
+      );
+    }
+    if (await this.#git.mergeBaseExists(REMOTE_BRANCH, "HEAD", { cwd })) return;
+    throw new AncestryRefusal(
+      "unrelated",
+      "fit-wiki: refusing to publish — local history is unrelated to the " +
+        "remote branch (confirmed against full history). Re-clone the wiki.",
+    );
+  }
 }