/**
 * Protected source-of-truth policy.
 *
 * Background — issue #6 (private):
 *   OwlCoda kept silently rewriting "source of truth" markdown files —
 *   `NEXT_THREAD_HANDOFF.md`, `GOAL_CONTRACT.md`, `SOURCE_OF_TRUTH.md`,
 *   `docs/handoff/**`, `CHANGELOG.md` — every time the model felt like
 *   "tightening" the doc. Sections like "Suggested Commands",
 *   "Runtime", "Deployment" disappeared mid-turn. Operators reported
 *   re-explaining the same context 5 turns later because the handoff
 *   had been compressed into a 200-byte summary.
 *
 *   This module is the dual of `fs-policy.ts`:
 *   - fs-policy says "this PATH must not be written, period."
 *   - protected-source-policy says "this PATH should be append-only.
 *     A destructive overwrite needs an explicit `replaceProtected` flag."
 *
 * What counts as "destructive"?
 *   1. >30% of existing lines removed in the new content.
 *   2. ≥2 top-level `## ` markdown headers disappear.
 *   3. Specific named sections disappear (Suggested Commands, Runtime,
 *      Deployment, Source of Truth — these are the ones we've actually
 *      seen lost in the wild).
 *
 *   Any one of those flips the verdict to destructive. Append-only
 *   writes (new content includes the old verbatim, plus extra at the
 *   end) never trip.
 *
 * What this is NOT:
 *   - Not a write blocker. The fix is opt-in via `replaceProtected: true`,
 *     because real rewrites do happen (releasing 0.13.x means rewriting
 *     CHANGELOG.md's top entry, etc.). The flag forces the model to
 *     name the destruction out loud.
 *   - Not a content-correctness check. We can't tell whether the
 *     replacement is good or bad — only whether it lost material.
 */
export interface ProtectedSourceOptions {
    /** Workspace root used for matching `docs/handoff/**` style globs. */
    workspaceRoot?: string;
    /** Override the env-var lookup (test seam). */
    envProtectedPaths?: string | undefined;
    /** Override homedir lookup (test seam). */
    homeDir?: string;
}
export interface ProtectedSourceVerdict {
    /** Is this path on the protected list at all? */
    protected: boolean;
    /** When protected: is the proposed change destructive? */
    destructive: boolean;
    /** Human-readable reason when destructive (for the refusal message). */
    reason?: string;
    /** Specific sections that disappear in the new content. */
    removedSections?: string[];
    /** Old line count (informational). */
    oldLineCount?: number;
    /** New line count (informational). */
    newLineCount?: number;
    /** Lines removed (informational). */
    removedLineCount?: number;
}
/**
 * Decide whether `targetPath` is a protected source-of-truth file and,
 * if so, whether the proposed `newContent` would destroy material from
 * the existing file. Pure: no fs reads, no mutations.
 *
 * `oldContent === null` means the file is new (creation), which is
 * never destructive even on a protected path.
 */
export declare function checkProtectedWrite(targetPath: string, newContent: string, oldContent: string | null, opts?: ProtectedSourceOptions): ProtectedSourceVerdict;
/**
 * Format the refusal message a write/edit tool should surface when
 * `checkProtectedWrite` returns `{protected: true, destructive: true}`
 * and the operator did not pass `replaceProtected: true`.
 */
export declare function formatProtectedRefusal(targetPath: string, verdict: ProtectedSourceVerdict): string;
