/**
 * The three CROSS-REPO sources this repo's drift guards read — and the switch
 * that decides whether their ABSENCE is allowed to be silent.
 *
 * WHY THIS FILE EXISTS
 * --------------------
 * Six of this suite's tests compare something this CLI emits against the
 * canonical text it claims to mirror. All three canonical texts live in OTHER
 * private repos, so until 2026-09-13 every one of those tests was written as
 * `it.skipIf(!existsSync(pathOnKerrysLaptop))`.
 *
 * That was correct when nothing else could reach them, and it became the
 * problem the moment CI existed: the coordination-pointer conformance byte-diff
 * — built in v0.30.0 *after* the emitted pointer had drifted to a 62%-similar
 * paraphrase that four fingerprint bumps missed — ran on exactly one machine,
 * and it was the machine CI exists to stop trusting.
 *
 * THE PART THAT IS NOT ABOUT CREDENTIALS
 * --------------------------------------
 * Granting CI read access to those repos is necessary and not sufficient. A
 * skip reads as green, so if the token lapses, the checkout silently fails, or
 * a file is renamed upstream, the guards return to not running and NOTHING GOES
 * RED. We would be paying for a credential with no guarantee it is still in
 * use — which is [[zero-is-not-a-pass]] wearing a purchase order.
 *
 * So absence is configurable, and the two audiences get opposite defaults:
 *
 *   - a contributor's laptop (no env var): missing source => SKIP, as before.
 *   - CI (`Z2W_REQUIRE_DRIFT_SOURCES=1`):  missing source => HARD FAILURE.
 *
 * RESOLUTION IS REPORTED, NOT JUST PERFORMED
 * ------------------------------------------
 * Each source is found by walking a list of candidate paths, and taking the
 * first that exists is selection by POSITION, not by evidence — a named trap in
 * [[zero-is-not-a-pass]]. The stale bulletin clone that sat 215 commits behind
 * while a guard reported a shrinking gap was exactly this. So every resolution
 * carries WHICH candidate won and WHY, and the suite prints it.
 */
export type DriftSourceName = "coordination" | "templates" | "skill";
/** Where CI drops the sibling checkouts. Overridable so the layout is not magic. */
export declare const driftSourcesDir: () => string;
/**
 * `1` means a missing source is a FAILURE, not a skip. CI sets it; laptops
 * don't. Deliberately an opt-IN to strictness rather than an opt-out: a
 * contributor who has none of these repos must still be able to run the suite.
 */
export declare const driftSourcesRequired: () => boolean;
export interface ResolvedDriftSource {
    readonly name: DriftSourceName;
    readonly repo: string;
    readonly guards: string;
    /** The file, if it was found anywhere. */
    readonly path?: string;
    /** WHICH candidate won. Never infer this from `path` — say it. */
    readonly origin: "ci-checkout" | "local" | "absent";
    /** Everything looked at, in order, so a wrong answer is diagnosable. */
    readonly candidatesTried: readonly string[];
}
/** Find one source. Never throws — callers decide what absence means. */
export declare const resolveDriftSource: (name: DriftSourceName) => ResolvedDriftSource;
/**
 * The `skipIf` condition. Skip ONLY when the source is missing AND nobody has
 * declared it mandatory. Under `Z2W_REQUIRE_DRIFT_SOURCES=1` this returns false
 * even with no file, so the test RUNS and `demandDriftSource` fails it loudly.
 */
export declare const skipUnlessRequired: (source: ResolvedDriftSource) => boolean;
/** The path, or a failure that says exactly what is missing and how to supply it. */
export declare const demandDriftSource: (source: ResolvedDriftSource) => string;
/**
 * A one-line, always-visible statement of what was (or was not) measured.
 * A silent skip is how a blind guard hides, so every source prints either way.
 */
export declare const describeDriftSource: (source: ResolvedDriftSource) => string;
/**
 * The ref to compare a source checkout against when asking "is this copy
 * current?".
 *
 * Three shapes have to work: a laptop clone (has `origin/main`), an
 * `actions/checkout` of another repo (has a remote-tracking ref, but the branch
 * name is the repo's default and not necessarily `main`), and anything else.
 * Returns undefined rather than guessing — the caller must treat "cannot
 * determine" as a failure, never as a clean result.
 */
export declare const upstreamRefFor: (repoDir: string) => string | undefined;
/**
 * The canonical text of a file, READ FROM THE UPSTREAM REF rather than from a
 * working tree.
 *
 * 🔴 WHY THIS EXISTS (2026-09-18). The conformance guards used to read
 * `AGENT_PROTOCOL.md` off the working tree of the shared bulletin clone, and
 * fail when that tree differed from `origin/main` with the remedy
 * `git -C <repo> pull --ff-only`. Both halves are wrong, and they are wrong in
 * a way that compounds:
 *
 *   1. **Nothing ever pulls that clone, by design.** Since 2026-08-29 every
 *      session takes a linked WORKTREE from it and works there; the shared tree
 *      itself carries a `pre-commit` guard that REFUSES commits and is left
 *      alone on purpose. Measured today it was **79 commits behind origin/main**
 *      and dirty with three other sessions' in-flight files.
 *   2. **So the guard's remedy instructs an action the coordination protocol
 *      forbids** — `agent-workspace.sh` prints "do not pull it, do not commit
 *      it" about that exact directory. A guard whose only fix is a prohibited
 *      command is a guard that will be muted, and muting it restores the blind
 *      spot it was built to close.
 *
 * Reading the ref removes the dependency on any checkout's currency: the
 * baseline is whatever `origin/main` holds, fetched at the moment we ask. That
 * is strictly stronger than "the working tree happens to match", which is all
 * the old test could assert.
 *
 * It THROWS rather than falling back to the working file. A fallback here would
 * silently restore the stale-canon comparison this replaces, and the whole
 * point of the drift-sources rework is that an unverifiable baseline must never
 * render as a clean one ([[zero-is-not-a-pass]]).
 */
export interface CanonicalRead {
    /** The file's contents at `ref`. */
    readonly text: string;
    /** Which ref was treated as upstream — say it, never infer it. */
    readonly ref: string;
    /** The commit the text was read from, short form. */
    readonly sha: string;
    /**
     * How the ref we read got to be the ref we read. Three states, not a boolean:
     * a fetch we CHOSE not to run and a fetch that FAILED are different facts, and
     * collapsing them into `false` would report a CI run — where skipping is
     * correct and deliberate — as "the remote was unreachable". That is the
     * [[zero-is-not-a-pass]] shape applied to our own telemetry.
     */
    readonly refreshed: "fetched" | "skipped" | "unreachable";
}
export interface ReadCanonicalOptions {
    /**
     * Refresh the ref from the remote before reading it. Default true.
     *
     * 🔴 Pass `false` for a CI checkout. `actions/checkout` provisions the repo at
     * run start, so its ref is current by construction and a fetch buys nothing —
     * but it COSTS, and on 2026-09-18 that cost was a red build: the fetch ran
     * past vitest's 5 s per-test budget on the runner while finishing instantly on
     * the laptop. Local green, CI red, for a network call that was pure overhead.
     */
    readonly fetch?: boolean;
}
export declare const readCanonicalFile: (repoDir: string, relPath: string, options?: ReadCanonicalOptions) => CanonicalRead;