@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/_lib/loop_guards.ts

@@ -0,0 +1,299 @@
+/**
+ * Guards for a harness-enforced bounded loop.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 5, Steps 2-4. Three
+ * primitives the stop-event loop needs and did not have, each closing a failure
+ * that is invisible while it happens.
+ *
+ * Extracted rather than added to `run_continuation_hook.ts`: that file is 1,504
+ * lines and `check_source_size_budget` charges every line above 1,500, so the
+ * same code there would cost a budget it does not cost here. The seam also makes
+ * all three testable without a host payload.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Write JSON atomically: temp file in the same directory, then rename.
+ *
+ * WHY THIS IS NOT A STYLE CHOICE. The file being written is the loop's
+ * ITERATION BUDGET. A direct `writeFileSync` that is interrupted — a crash, a
+ * full disk, a killed process — leaves a truncated file, the parser rejects it,
+ * and the loop reads "no state": the counter restarts at zero and **the cap
+ * stops bounding anything**. The failure mode of a non-atomic budget write is an
+ * unbounded loop, which is the exact thing the budget exists to prevent.
+ *
+ * Same directory for the temp file because `rename` is only atomic within a
+ * filesystem; a temp in `/tmp` can land on another one and degrade to copy+unlink.
+ *
+ * Never throws — a budget writer that throws turns an observability concern into
+ * a turn-end failure. Returns whether the write landed, and that return is
+ * load-bearing: a loop that could not persist its counter must not BLOCK,
+ * because there the ladder cannot bound it.
+ */
+export function atomicWriteJson(file: string, value: unknown): boolean {
+    const tmp = `${file}.${String(process.pid)}.tmp`;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(tmp, `${JSON.stringify(value)}\n`, 'utf8');
+        fs.renameSync(tmp, file);
+        return true;
+    } catch {
+        try {
+            fs.unlinkSync(tmp);
+        } catch {
+            /* the temp may never have been created; nothing to clean */
+        }
+        return false;
+    }
+}
+
+/**
+ * Whole-LINE match against a marker — never a substring.
+ *
+ * The hazard is specific and cheap to hit: a transcript contains everything the
+ * agent said, INCLUDING quoted examples of the marker. A substring match lets a
+ * sentence like *"exit when you print RUN-COMPLETE"* terminate the run, and — the
+ * worse direction — lets a quoted marker inside a code fence extend one.
+ *
+ * Trailing whitespace is trimmed because a terminal or a JSON round-trip adds it;
+ * leading whitespace is trimmed for the same reason. Nothing ELSE on the line is
+ * tolerated: `RUN-COMPLETE (probably)` is not the marker.
+ */
+export function matchesWholeLine(text: string, marker: string): boolean {
+    if (marker === '') return false;
+    for (const line of text.split('\n')) {
+        if (line.trim() === marker) return true;
+    }
+    return false;
+}
+
+/** A dependency the loop cannot obtain, and therefore cannot iterate toward. */
+export interface UnavailableDependency {
+    kind: 'credential' | 'binary' | 'permission' | 'quota' | 'service';
+    evidence: string;
+}
+
+/**
+ * Patterns that name a dependency the loop CANNOT close by trying again.
+ *
+ * Every entry corresponds to a hard-blocker class the rules already name
+ * (`context-hygiene` § hard-blocker classes). The list is deliberately short and
+ * literal: a general "looks like an error" heuristic would end runs on ordinary
+ * test failures, which is the opposite of the intent — those are exactly what a
+ * loop SHOULD iterate on.
+ */
+const DEPENDENCY_PATTERNS: readonly { kind: UnavailableDependency['kind']; re: RegExp }[] = [
+    { kind: 'binary', re: /\b(?:command not found|is not recognized as an internal or external command)\b/i },
+    { kind: 'credential', re: /\b(?:not (?:authenticated|logged in)|authentication (?:failed|required)|no credentials found)\b/i },
+    { kind: 'credential', re: /\b(?:missing|unset|not set)\b[^\n]{0,40}\b(?:credential|token|api[_ -]?key|secret)\b/i },
+    { kind: 'permission', re: /\b(?:permission denied|forbidden|403 forbidden)\b/i },
+    { kind: 'quota', re: /\b(?:rate limit(?:ed| exceeded| reached)?|quota exceeded|429 too many requests|spend (?:cap|limit) reached)\b/i },
+    { kind: 'service', re: /\b(?:5\d\d (?:internal )?server error|service unavailable|connection refused)\b/i },
+];
+
+/**
+ * How much of the transcript tail a caller should read before scanning it.
+ *
+ * The detector takes text, not a file, so the BYTE bound belongs to the read
+ * and the LINE bound (`tailLines`) belongs to the scan. Both exist and they
+ * bound different things: 64 KiB keeps an arbitrarily long transcript from
+ * being loaded whole, and the line count then keeps a stale failure from
+ * halting a run that already recovered.
+ *
+ * Exported rather than inlined at the one call site so the bound is visible
+ * beside the detector it feeds. A caller that reads the whole file and then
+ * passes it here is not wrong, only wasteful — the line bound still applies.
+ */
+export const DEPENDENCY_SCAN_BYTES = 64 * 1024;
+
+/**
+ * Find a dependency the run cannot obtain, from recent transcript text.
+ *
+ * Returns the FIRST match with the line that produced it, so a halt event can
+ * name what is missing instead of saying "blocked". A halt with no named
+ * dependency is a report the reader has to reconstruct.
+ *
+ * Scans the LAST `tailLines` lines only: an authentication failure from an hour
+ * ago that was then fixed must not halt the run now, and a transcript is
+ * append-only so recency is the whole signal.
+ */
+export function detectUnavailableDependency(
+    transcriptTail: string,
+    tailLines = 200,
+): UnavailableDependency | null {
+    const lines = transcriptTail.split('\n');
+    const window = lines.slice(Math.max(0, lines.length - tailLines));
+    for (const line of window) {
+        for (const { kind, re } of DEPENDENCY_PATTERNS) {
+            if (re.test(line)) {
+                return { kind, evidence: line.trim().slice(0, 200) };
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * The machine-readable stall signal, derived from a run's open-step history.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 6 Step 6, and it is what
+ * makes Phase 4's progress-primary ordering usable rather than aspirational: a
+ * consumer asking "is this run still making progress" had to re-derive the
+ * answer from a history array and a window constant, so every reader could
+ * derive it differently.
+ *
+ * Three levels rather than a boolean, because the ordering they enable is
+ * different:
+ *
+ *   `progressing` — the newest reading is a NEW MINIMUM. This is the primary
+ *     signal Phase 4 names: the budget may keep running.
+ *   `flat`        — no new minimum, but the window is not yet full or not yet
+ *     uniform. Not stalled; simply not evidence of progress either.
+ *   `stalled`     — a full window of IDENTICAL readings. More of the same will
+ *     not help, and raising the budget is the WRONG response — which is exactly
+ *     what separates `stagnated` from `exhausted` in the terminal-state
+ *     vocabulary.
+ *
+ * Pure over the history array, so a reader and the ladder cannot disagree.
+ */
+export type StallLevel = 'progressing' | 'flat' | 'stalled';
+
+export interface StallSignal {
+    level: StallLevel;
+    /** How many of the most recent readings are identical. */
+    flatRun: number;
+    /** The lowest reading seen, i.e. the best progress this run has made. */
+    minimum: number | null;
+    /** True when the LAST reading equals the minimum and is strictly below the one before it. */
+    newMinimum: boolean;
+}
+
+export function stallSignal(history: readonly number[], window = 3): StallSignal {
+    if (history.length === 0) {
+        return { level: 'flat', flatRun: 0, minimum: null, newMinimum: false };
+    }
+    const last = history[history.length - 1] as number;
+    const minimum = Math.min(...history);
+    // Strictly below every EARLIER reading — not merely below the one before it.
+    // The weaker form calls a return to an already-reached minimum progress, so an
+    // oscillating run (5, 9, 5, 9, …) would look like it was advancing forever
+    // while closing nothing.
+    const earlier = history.slice(0, -1);
+    const newMinimum = earlier.length > 0 && last < Math.min(...earlier);
+
+    let flatRun = 1;
+    for (let i = history.length - 2; i >= 0; i -= 1) {
+        if (history[i] !== last) break;
+        flatRun += 1;
+    }
+    if (newMinimum) return { level: 'progressing', flatRun, minimum, newMinimum };
+    if (flatRun >= window) return { level: 'stalled', flatRun, minimum, newMinimum };
+    return { level: 'flat', flatRun, minimum, newMinimum };
+}
+
+/**
+ * Read the transcript tail and name a dependency the run cannot obtain.
+ *
+ * Lives here rather than at the call site, beside the detector and the byte
+ * bound it uses. EXPORTED so the wiring is testable,
+ * which is the half that was actually broken: the inline version referenced a
+ * constant that did not exist, and because the read sits inside a `catch`
+ * that fail-opens to `null`, the ReferenceError was swallowed on every fire.
+ * The rung was dead and every pure `ladder()` test stayed green — a test over
+ * the decision function cannot see a caller that never computes the input.
+ *
+ * Fail-open is deliberate and unchanged: a detector that cannot read must not
+ * manufacture a halt. What changed is that "cannot read" is now the only way
+ * to reach `null` by accident.
+ */
+export function readUnavailableDependency(transcriptPath: string): UnavailableDependency | null {
+    try {
+        const raw = fs.readFileSync(transcriptPath, 'utf8');
+        return detectUnavailableDependency(raw.slice(-DEPENDENCY_SCAN_BYTES));
+    } catch {
+        return null;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Rejected-tactic repetition
+// ---------------------------------------------------------------------------
+
+/**
+ * Window and threshold for the repetition guard.
+ *
+ * Named constants, NOT a settings block. A configurable strategy preset is the
+ * shape this roadmap kills by name: presets multiply the states a reader has to
+ * reason about while the underlying question — "is this run going in circles?" —
+ * has one answer. Two numbers with a stated meaning are auditable; a tuning
+ * surface is not.
+ */
+export const SUPPRESSION_WINDOW = 8;
+export const SUPPRESSION_REPEATS = 3;
+
+/**
+ * One attempt the run has already made, reduced to what a detector may see.
+ *
+ * `tactic_id` is ID-SHAPED and that is the load-bearing property. `stallSignal`
+ * above keys on a NUMBER (the open-step count); this keys on an identity. The
+ * failure it catches is one the numeric detector cannot see at all: an agent
+ * that retries the same rejected approach while the surrounding prose changes
+ * every time. The open-step count moves, the wording moves, and the tactic is
+ * identical.
+ */
+export interface TacticAttempt {
+    /** Stable id for the approach tried. Lowercase alnum + hyphens; never prose. */
+    tactic_id: string;
+    /** Whether this attempt was rejected (by a gate, a test, a review, a human). */
+    rejected: boolean;
+}
+
+export interface RepetitionSignal {
+    /** True when a rejected tactic has recurred at or above the threshold in-window. */
+    suppress: boolean;
+    /** The tactic that tripped it, or `null`. */
+    tactic_id: string | null;
+    /** How many rejected attempts of that tactic are in the window. */
+    repeats: number;
+}
+
+/**
+ * Has the run repeated a tactic that was already rejected?
+ *
+ * Counts only REJECTED attempts. A tactic tried three times and accepted twice
+ * is not a loop, it is a tactic that works — counting every attempt would fire
+ * on productive repetition, which is the false positive that gets a guard
+ * switched off.
+ *
+ * Deliberately blind to any signal string. The verify line this satisfies asks
+ * for suppression "even when the signal string differs", which is only
+ * achievable by keying on something else — so this function is given no text to
+ * read, rather than being trusted to ignore it.
+ */
+export function rejectedTacticRepeat(
+    history: readonly TacticAttempt[],
+    window: number = SUPPRESSION_WINDOW,
+    threshold: number = SUPPRESSION_REPEATS,
+): RepetitionSignal {
+    const recent = history.slice(-window);
+    const counts = new Map<string, number>();
+    for (const a of recent) {
+        if (!a.rejected) continue;
+        counts.set(a.tactic_id, (counts.get(a.tactic_id) ?? 0) + 1);
+    }
+
+    let worst: string | null = null;
+    let worstCount = 0;
+    for (const [id, n] of counts) {
+        if (n > worstCount) {
+            worst = id;
+            worstCount = n;
+        }
+    }
+
+    if (worst !== null && worstCount >= threshold) {
+        return { suppress: true, tactic_id: worst, repeats: worstCount };
+    }
+    return { suppress: false, tactic_id: null, repeats: worstCount };
+}

package/src/scripts/_lib/loss_class.ts

@@ -0,0 +1,129 @@
+/**
+ * Loss classes — names for what the tree already does, before they constrain
+ * what comes next (`road-to-runtime-context-floors` Phase 3).
+ *
+ * The tree already practises loss classes implicitly and has for a while:
+ * `fold_intake` folds intake batches into an ADDITIVE archive page with
+ * per-child link-backs and never mutates the children, and `hot_context_hook`
+ * deliberately DROPS lines the low-impact redactor refuses, unrecoverably, for
+ * privacy. Those are two different guarantees wearing the same word
+ * "compression", and nothing distinguished them.
+ *
+ * So the vocabulary is written AGAINST those two first, and checked against
+ * their own source docblocks, before any lint exists to fail on anything.
+ *
+ * THE FIVE CLASSES, each defined by the recovery it guarantees:
+ *
+ *   exact              output is byte-identical to input; nothing is lost
+ *   lossless           output differs but the input is fully reconstructible
+ *                      from the output alone
+ *   recoverable-lossy  output is smaller and the original is retrievable via a
+ *                      declared RECOVERY LOCATOR (a path, a range, an id)
+ *   ephemeral-lossy    output is smaller and the dropped content is gone —
+ *                      deliberately, and the deliberateness is the point
+ *   forbidden          this transform must not run on this path at all
+ *
+ * `recoverable-lossy` is the only class that owes a locator, and it owes one
+ * because without it the class is indistinguishable from `ephemeral-lossy` by
+ * anything except its author's intention.
+ */
+
+export const LOSS_CLASSES = ['exact', 'lossless', 'recoverable-lossy', 'ephemeral-lossy', 'forbidden'] as const;
+export type LossClass = (typeof LOSS_CLASSES)[number];
+
+export function isLossClass(v: unknown): v is LossClass {
+    return typeof v === 'string' && (LOSS_CLASSES as readonly string[]).includes(v);
+}
+
+export interface LossDeclaration {
+    lossClass: LossClass;
+    /** Where the original is retrievable. Required for `recoverable-lossy`. */
+    recovery: string | null;
+}
+
+export type DeclarationProblem =
+    | { kind: 'missing' }
+    | { kind: 'unknown-class'; value: string }
+    | { kind: 'missing-recovery' };
+
+/**
+ * Read a declaration out of a module's own source.
+ *
+ * The declaration lives in a docblock, not in a sidecar registry, deliberately:
+ * a class describes what THIS code does to its input, and a registry entry
+ * beside it is a second statement that can drift from the first. Shape:
+ *
+ *     loss_class: recoverable-lossy
+ *     loss_recovery: agents/knowledge/intake/<file>:<first-line>-<last-line>
+ */
+export function parseLossDeclaration(source: string): LossDeclaration | DeclarationProblem {
+    // `[A-Za-z_-]+`, not `[A-Za-z-]+`: an underscore misspelling
+    // (`recoverable_lossy`) must be reported as `unknown-class`, not fall
+    // through to `missing`. Both reject, so the exit code is the same — but
+    // "declares no loss_class" sends an author who declared one hunting the
+    // wrong defect, which is the failure a diagnostic exists to prevent.
+    const cls = /^[\s*/]*loss_class:\s*([A-Za-z_-]+)\s*$/m.exec(source);
+    if (cls === null) return { kind: 'missing' };
+    const value = (cls[1] ?? '').trim();
+    if (!isLossClass(value)) return { kind: 'unknown-class', value };
+
+    const rec = /^[\s*/]*loss_recovery:\s*(\S.*?)\s*$/m.exec(source);
+    const recovery = rec === null ? null : (rec[1] ?? '').trim();
+    if (value === 'recoverable-lossy' && (recovery === null || recovery.length === 0)) {
+        return { kind: 'missing-recovery' };
+    }
+    return { lossClass: value, recovery };
+}
+
+export function isProblem(v: LossDeclaration | DeclarationProblem): v is DeclarationProblem {
+    return 'kind' in v;
+}
+
+// -------------------------------------------------------- passthrough (3.3)
+
+/** Why a transform declined to transform. Never `null` on a passthrough. */
+export type PassthroughReason = 'unparseable-input' | 'recovery-unavailable' | 'not-smaller';
+
+export interface TransformOutcome {
+    output: string;
+    /** `null` when the transform actually ran. */
+    passthrough: PassthroughReason | null;
+}
+
+export interface TransformHooks {
+    /** Returns the shortened form, or `null` when the input cannot be parsed. */
+    transform: (input: string) => string | null;
+    /**
+     * Persist the recovery for `recoverable-lossy`. Returns `false` when the
+     * recovery cannot be stored. Omit for classes that owe no recovery.
+     */
+    storeRecovery?: (input: string) => boolean;
+}
+
+/**
+ * The passthrough invariant.
+ *
+ * > A transform that cannot parse its input, cannot store the recovery, or does
+ * > not make the input smaller returns the input unchanged.
+ *
+ * Degradation is never silent and never lossy. The two halves matter equally and
+ * are easy to get half-right: returning a partial parse is lossy degradation;
+ * returning the input while reporting success is silent degradation. This helper
+ * returns the input bytes AND the reason, so a caller cannot have one without the
+ * other.
+ *
+ * The `not-smaller` branch is the one that looks pedantic and is not. A
+ * "compression" that grew the input has paid the cost of the transform, lost
+ * whatever the transform dropped, and bought nothing — keeping the original is
+ * strictly better on every axis, so there is no case in which emitting the
+ * larger output is right.
+ */
+export function applyTransform(input: string, hooks: TransformHooks): TransformOutcome {
+    const out = hooks.transform(input);
+    if (out === null) return { output: input, passthrough: 'unparseable-input' };
+    if (hooks.storeRecovery !== undefined && !hooks.storeRecovery(input)) {
+        return { output: input, passthrough: 'recovery-unavailable' };
+    }
+    if (out.length >= input.length) return { output: input, passthrough: 'not-smaller' };
+    return { output: out, passthrough: null };
+}

package/src/scripts/_lib/machine_wake.ts

@@ -0,0 +1,51 @@
+/**
+ * Did a human type this turn?
+ *
+ * ```
+ * UNKNOWN ANSWERS YES. AN UNRECOGNISED PAYLOAD FALLS BACK TO TREATING THE TURN
+ * AS HUMAN — NEVER TO TREATING IT AS MACHINE. EVERY CONSUMER OF THIS PREDICATE
+ * GUARDS A PER-TURN RECORD, AND A RECORD WRONGLY RETAINED OUTLIVES THE TURN
+ * THAT AUTHORISED IT.
+ * ```
+ *
+ * **Why this lives in `_lib` rather than in one hook.** The misclassification is
+ * a property of the `user_prompt_submit` SLOT, not of any one concern: the host
+ * delivers a background task notification on the same slot as a typed prompt,
+ * so every concern that consumes or replaces per-turn state has the same defect.
+ * Two are known — the git-authorization ledger with its pending-refusal record,
+ * and the suggestion-capture latch. A predicate private to one of them would
+ * have repaired one and left the other, which is risk 4 of
+ * `road-to-turn-bound-authorization-integrity`.
+ *
+ * **The discriminator, quoted from a captured payload rather than from
+ * documentation.** `agents/runtime/.agent-chat-history` records prompts tagged
+ * `"source": "hook:claude:UserPromptSubmit"` — what the hook RECEIVED, not what
+ * the host stored in its transcript, and those are not guaranteed to be the same
+ * text. Measured 2026-08-27 in this project's capture: **9 of 16** hook-sourced
+ * user records begin with the literal `<task-notification>`, carrying
+ * `<task-id>`, `<tool-use-id>`, `<status>` and `<summary>` children. A typed
+ * turn carries none of them.
+ *
+ * **Prefix, not substring, and that is the whole care in this file.** A
+ * notification is a synthetic turn the host constructs, so the element opens it.
+ * Matching anywhere in the text would make the question "why did this
+ * `<task-notification>` clear my authorization?" clear it again — the user would
+ * lose the very turn they were asking about.
+ */
+
+/** Wake shapes the host delivers on `user_prompt_submit` that no human typed. */
+export const MACHINE_WAKE_PREFIXES: readonly string[] = [
+    '<task-notification>',
+    '<system-reminder>',
+];
+
+/** @see MACHINE_WAKE_PREFIXES — unknown shapes answer `true`, deliberately. */
+export function humanTypedThisTurn(prompt: string): boolean {
+    const head = prompt.trimStart();
+    for (const prefix of MACHINE_WAKE_PREFIXES) {
+        if (head.startsWith(prefix)) {
+            return false;
+        }
+    }
+    return true;
+}

package/src/scripts/_lib/md_prose_lines.ts

@@ -0,0 +1,177 @@
+/**
+ * Shared markdown line classifier — the frontmatter / fence / indented-code /
+ * marker skip machinery that decides which lines of a `.md` file are PROSE.
+ *
+ * ## Why this exists
+ *
+ * `check_md_language.ts` has carried this machinery since it was ported from
+ * Python (ADR-200), and its CLI contract is pinned byte-for-byte. When
+ * `road-to-canonical-terms` 2.2 called for a second prose-scanning gate it said
+ * explicitly: reuse that machinery "rather than a second copy of it". A second
+ * copy is how two gates end up disagreeing about what a fence is — one of them
+ * flags a word inside a code block and the other does not, and nobody can say
+ * which is right because there is no single definition to consult.
+ *
+ * So the classifier moved here verbatim and both callers read it. The
+ * behaviour is unchanged on purpose: `check_md_language`'s test suite pins the
+ * exact finding list, and this extraction is a refactor that must not move it.
+ *
+ * ## What counts as a skip, and what does not
+ *
+ * - **frontmatter** — a `---` fence opening on line 1 and everything to its close.
+ * - **fence** — ``` or ~~~ toggles, and every line between them. The fence
+ *   markers themselves are skipped too.
+ * - **indented-code** — four leading spaces on a line that does not start a
+ *   list item. Markdown's indented-code rule, with the list carve-out this
+ *   tree's own deeply-nested bullets need.
+ * - **marker** — a caller-supplied per-line opt-out (`<!-- x: ignore -->`) or a
+ *   labelled bilingual anchor. Callers pass their own patterns; the module has
+ *   no opinion about which markers exist.
+ *
+ * Everything else is prose, and prose carries `text` with inline code spans
+ * blanked out — because a word named inside backticks is being QUOTED, not used.
+ */
+
+/** What a classifier pass decided about one line. */
+export type MarkdownLineKind =
+    | 'frontmatter'
+    | 'fence'
+    | 'indented-code'
+    | 'marker'
+    | 'prose';
+
+export interface MarkdownLine {
+    /** 1-based line number, matching every editor and every gate message. */
+    lineno: number;
+    /** The line exactly as it appears in the file. */
+    raw: string;
+    kind: MarkdownLineKind;
+    /**
+     * Scannable text — the raw line with inline code spans removed. Only
+     * meaningful when `kind === 'prose'`; empty string otherwise.
+     */
+    text: string;
+}
+
+export interface MarkdownScanOptions {
+    /**
+     * Per-line skip patterns tested against the RAW line. A match classifies
+     * the line `marker`. Callers own their own markers; this module ships none.
+     */
+    markers?: readonly RegExp[];
+}
+
+/** Inline code spans — a term inside backticks is named, not used. */
+const INLINE_CODE_RE = /`[^`]*`/g;
+
+/**
+ * Python `str.splitlines()` — universal-newline split with no trailing empty
+ * element. Kept identical to the version `check_md_language` was ported with,
+ * because its line numbers are part of that gate's pinned output.
+ */
+export function splitlines(text: string): string[] {
+    if (text === '') return [];
+    const lines: string[] = [];
+    let current = '';
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i] as string;
+        const code = text.charCodeAt(i);
+        if (ch === '\r') {
+            lines.push(current);
+            current = '';
+            if (text[i + 1] === '\n') i += 1; // \r\n consumed as one
+            continue;
+        }
+        if (
+            ch === '\n' ||
+            code === 0x0b ||
+            code === 0x0c ||
+            code === 0x1c ||
+            code === 0x1d ||
+            code === 0x1e ||
+            code === 0x85 ||
+            code === 0x2028 ||
+            code === 0x2029
+        ) {
+            lines.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    if (current !== '') lines.push(current);
+    return lines;
+}
+
+/** Blank out inline code spans so a quoted term is not read as a used one. */
+export function stripInlineCode(text: string): string {
+    return text.replace(INLINE_CODE_RE, '');
+}
+
+function lstrip(s: string): string {
+    return s.replace(/^\s+/, '');
+}
+
+/**
+ * Classify every line of a markdown document.
+ *
+ * Pure over the content string — no filesystem access — so a caller can test
+ * the classification from a literal without a repo.
+ */
+export function classifyMarkdownLines(
+    content: string,
+    opts: MarkdownScanOptions = {},
+): MarkdownLine[] {
+    const markers = opts.markers ?? [];
+    const out: MarkdownLine[] = [];
+    const lines = splitlines(content);
+
+    let inFence = false;
+    let inFrontmatter = false;
+
+    for (let idx = 0; idx < lines.length; idx++) {
+        const raw = lines[idx] as string;
+        const lineno = idx + 1;
+        const stripped = lstrip(raw);
+
+        // YAML frontmatter at the top of the file.
+        if (lineno === 1 && stripped === '---') {
+            inFrontmatter = true;
+            out.push({ lineno, raw, kind: 'frontmatter', text: '' });
+            continue;
+        }
+        if (inFrontmatter) {
+            if (stripped === '---') inFrontmatter = false;
+            out.push({ lineno, raw, kind: 'frontmatter', text: '' });
+            continue;
+        }
+
+        // Fenced code blocks — the markers themselves are skipped too.
+        if (stripped.startsWith('```') || stripped.startsWith('~~~')) {
+            inFence = !inFence;
+            out.push({ lineno, raw, kind: 'fence', text: '' });
+            continue;
+        }
+        if (inFence) {
+            out.push({ lineno, raw, kind: 'fence', text: '' });
+            continue;
+        }
+
+        // Indented code blocks (4+ leading spaces, non-list).
+        const listStarts = ['-', '*', '+', '1', '2', '3', '4', '5', '6', '7', '8', '9'];
+        if (raw.startsWith('    ') && !listStarts.some((c) => stripped.startsWith(c))) {
+            out.push({ lineno, raw, kind: 'indented-code', text: '' });
+            continue;
+        }
+
+        // Caller-supplied per-line markers.
+        if (markers.some((re) => { re.lastIndex = 0; return re.test(raw); })) {
+            out.push({ lineno, raw, kind: 'marker', text: '' });
+            continue;
+        }
+
+        out.push({ lineno, raw, kind: 'prose', text: stripInlineCode(raw) });
+    }
+
+    return out;
+}