agentwrangler 0.1.0

package/dist/oauth/judge-g2-client.js

@@ -0,0 +1,154 @@
+/**
+ * src/oauth/judge-g2-client.ts — Claude client for blinded G2 adjudication.
+ *
+ * Calls Anthropic Messages using the local Claude Code OAuth credential. The
+ * displayed evidence is sent only for the adjudication request and is never
+ * logged (SEC-101).
+ */
+import { fileCredentialSource } from "./credentials.js";
+const MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+// Pilot-review artifact: a human reviews this fixed rubric before any live run.
+export const G2_JUDGE_RUBRIC = `You adjudicate one blinded G2 DEFERRAL finding. Given only the displayed evidence object and its evidenceKind, decide whether that displayed evidence supports that the item is a genuine deferral.
+
+Return CONFIRMED only when the displayed evidence supports the finding. Return REJECTED when it does not support the finding, is insufficient, or is unrelated. Do not infer facts that are not displayed. Use a confidence number from 0 through 1 inclusive. Choose a short, lowercase snake_case rationale_tag that identifies the main reason.
+
+Respond with strict JSON only, with exactly these fields and no markdown or additional text:
+{"verdict":"CONFIRMED"|"REJECTED","confidence":<number 0..1>,"rationale_tag":"<short snake_case tag>"}`;
+function parseJudgeResult(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return { ok: false, reason: "Judge returned an invalid response shape." };
+    }
+    // Require the three rubric fields to be present and valid; ignore any extra
+    // keys the model volunteers (e.g. a spontaneous "reasoning") rather than
+    // discarding the whole verdict.
+    const candidate = raw;
+    if ((candidate.verdict !== "CONFIRMED" && candidate.verdict !== "REJECTED") ||
+        typeof candidate.confidence !== "number" ||
+        !Number.isFinite(candidate.confidence) ||
+        candidate.confidence < 0 ||
+        candidate.confidence > 1 ||
+        typeof candidate.rationale_tag !== "string" ||
+        candidate.rationale_tag.length === 0) {
+        return { ok: false, reason: "Judge response did not match the G2 rubric." };
+    }
+    return {
+        ok: true,
+        verdict: candidate.verdict,
+        confidence: candidate.confidence,
+        rationaleTag: candidate.rationale_tag,
+    };
+}
+/**
+ * Anthropic marks a 429/overload as retryable via `x-should-retry: true` and,
+ * for hard quota walls, an `anthropic-ratelimit-*`/`retry-after` header. Retry
+ * transient throttles with bounded exponential backoff + full jitter so a
+ * single blip among the sequential judge calls does not abort the whole run.
+ */
+function isRetryableStatus(status, headers) {
+    if (headers?.get("x-should-retry") === "true")
+        return true;
+    return status === 429 || status === 529 || status >= 500;
+}
+/** Delay before the next attempt: honor `retry-after` (seconds) else exp backoff. */
+function backoffDelayMs(attempt, baseDelayMs, headers) {
+    const retryAfter = headers?.get("retry-after");
+    if (retryAfter !== undefined && retryAfter !== null) {
+        const secs = Number(retryAfter);
+        if (Number.isFinite(secs) && secs >= 0)
+            return Math.min(secs * 1000, 30_000);
+    }
+    const ceiling = Math.min(baseDelayMs * 2 ** attempt, 30_000);
+    return Math.round(Math.random() * ceiling);
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function claudeJudgeClient(opts = {}) {
+    const credSource = opts.credSource ?? fileCredentialSource;
+    const fetchFn = opts.fetchFn ?? fetch;
+    const model = opts.model ?? "claude-opus-4-8";
+    const apiKey = opts.apiKey;
+    const maxRetries = opts.maxRetries ?? 5;
+    const baseDelayMs = opts.baseDelayMs ?? 1000;
+    const sleepFn = opts.sleepFn ?? defaultSleep;
+    return async ({ evidenceKind, evidence }) => {
+        // API-key auth uses `x-api-key`; OAuth (subscription) auth uses a Bearer
+        // token + the oauth beta header. Resolve one set of auth headers up front.
+        let authHeaders;
+        if (apiKey !== undefined) {
+            authHeaders = {
+                "x-api-key": apiKey,
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+            };
+        }
+        else {
+            const credResult = credSource.read();
+            if (!credResult.ok) {
+                return { ok: false, reason: credResult.reason };
+            }
+            authHeaders = {
+                Authorization: `Bearer ${credResult.credential.accessToken}`,
+                "anthropic-beta": "oauth-2025-04-20",
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+            };
+        }
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await fetchFn(MESSAGES_URL, {
+                    method: "POST",
+                    headers: authHeaders,
+                    body: JSON.stringify({
+                        model,
+                        max_tokens: 512,
+                        system: G2_JUDGE_RUBRIC,
+                        messages: [{ role: "user", content: JSON.stringify({ evidenceKind, evidence }) }],
+                    }),
+                });
+            }
+            catch (error) {
+                // Network-level failure — retry with backoff, then give up.
+                if (attempt < maxRetries) {
+                    await sleepFn(backoffDelayMs(attempt, baseDelayMs));
+                    continue;
+                }
+                return {
+                    ok: false,
+                    reason: `Could not reach ${MESSAGES_URL}: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+            if (!response.ok) {
+                if (attempt < maxRetries && isRetryableStatus(response.status, response.headers)) {
+                    await sleepFn(backoffDelayMs(attempt, baseDelayMs, response.headers));
+                    continue;
+                }
+                return {
+                    ok: false,
+                    reason: `HTTP ${response.status} from Messages API`,
+                    status: response.status,
+                };
+            }
+            const raw = await response.json();
+            if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+                return { ok: false, reason: "Messages API returned an invalid response shape." };
+            }
+            const content = raw.content;
+            if (!Array.isArray(content)) {
+                return { ok: false, reason: "Messages API response is missing content." };
+            }
+            const textBlock = content.find((block) => typeof block === "object" &&
+                block !== null &&
+                block.type === "text" &&
+                typeof block.text === "string");
+            if (textBlock === undefined) {
+                return { ok: false, reason: "Messages API response is missing a text block." };
+            }
+            try {
+                return parseJudgeResult(JSON.parse(textBlock.text));
+            }
+            catch {
+                return { ok: false, reason: "Judge response was not valid JSON." };
+            }
+        }
+    };
+}

package/dist/oauth/usage.js

@@ -0,0 +1,167 @@
+/**
+ * src/oauth/usage.ts — reader for the Anthropic oauth/usage endpoint.
+ *
+ * Reads the current user's weekly utilization from their local OAuth session.
+ * No data leaves the machine — this queries the same session Claude Code uses.
+ *
+ * Requires a valid credential (read from ~/.claude/.credentials.json by default).
+ * Returns ok:false without calling fetch if credentials are missing or expired.
+ *
+ * Degrades gracefully on ANY non-200. Never throws uncaught; always returns a
+ * typed result.
+ */
+import { fileCredentialSource } from "./credentials.js";
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+/**
+ * Validate one raw period from the API (utilization as PERCENT 0–100) and
+ * return it normalized to the fraction-0–1 contract, or null if malformed.
+ */
+function parseUsagePeriod(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const candidate = value;
+    const pct = candidate.utilization;
+    if (typeof pct !== "number" ||
+        !Number.isFinite(pct) ||
+        pct < 0 ||
+        pct > 100 ||
+        typeof candidate.resets_at !== "string" ||
+        candidate.resets_at.length === 0 ||
+        !Number.isFinite(new Date(candidate.resets_at).getTime())) {
+        return null;
+    }
+    return { utilization: pct / 100, resets_at: candidate.resets_at };
+}
+/**
+ * Parse the unverified per-model utilization response shape. Invalid entries
+ * are ignored so optional model detail can never invalidate the core periods.
+ */
+function parsePerModel(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    try {
+        const parseEntry = (modelValue, entryValue) => {
+            if (typeof modelValue !== "string" || modelValue.trim().length === 0)
+                return null;
+            if (typeof entryValue !== "object" || entryValue === null)
+                return null;
+            const pct = entryValue.utilization;
+            if (typeof pct !== "number" || !Number.isFinite(pct) || pct < 0 || pct > 100) {
+                return null;
+            }
+            return { model: modelValue.trim(), utilization: pct / 100 };
+        };
+        const entries = [];
+        if (Array.isArray(value)) {
+            for (const entry of value) {
+                if (typeof entry !== "object" || entry === null)
+                    continue;
+                const candidate = entry;
+                const model = [candidate.model, candidate.model_key, candidate.tier].find((candidateModel) => typeof candidateModel === "string" && candidateModel.trim().length > 0);
+                const parsed = parseEntry(model, entry);
+                if (parsed !== null)
+                    entries.push(parsed);
+            }
+        }
+        else {
+            for (const [model, entry] of Object.entries(value)) {
+                const parsed = parseEntry(model, entry);
+                if (parsed !== null)
+                    entries.push(parsed);
+            }
+        }
+        return entries.length > 0 ? entries : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Validate value contains valid five_hour and seven_day periods and return the
+ * normalized (fraction 0–1) usage data, or null if malformed.
+ * Extra unknown keys (per-model breakdowns, extra_usage, limits, spend, …) are
+ * tolerated — we only require the two bounded fields.
+ */
+function parseUsageData(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const candidate = value;
+    const fiveHour = parseUsagePeriod(candidate.five_hour);
+    const sevenDay = parseUsagePeriod(candidate.seven_day);
+    if (fiveHour === null || sevenDay === null)
+        return null;
+    let perModel;
+    try {
+        perModel = parsePerModel(candidate.per_model === undefined ? candidate.per_model_utilization : candidate.per_model);
+    }
+    catch {
+        perModel = undefined;
+    }
+    if (perModel !== undefined) {
+        return { five_hour: fiveHour, seven_day: sevenDay, per_model: perModel };
+    }
+    return { five_hour: fiveHour, seven_day: sevenDay };
+}
+/**
+ * Fetch the oauth/usage endpoint, authenticated with the local OAuth credential.
+ *
+ * @param credSource - Credential source to read the token from (default: file source).
+ *   Injectable for tests via a stub that returns a known credential or ok:false.
+ *
+ * Returns ok:false (no fetch) when credentials are missing or expired.
+ * Distinguishes 401 (auth failure — re-login) from 429 (rate limited).
+ */
+export async function fetchOAuthUsage(credSource = fileCredentialSource) {
+    // 1. Read credential; fail closed if unavailable.
+    const credResult = credSource.read();
+    if (!credResult.ok) {
+        return { ok: false, reason: credResult.reason };
+    }
+    const { accessToken } = credResult.credential;
+    // 2. Fetch with auth headers.
+    try {
+        const res = await fetch(USAGE_URL, {
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "anthropic-beta": "oauth-2025-04-20",
+                // Honest, self-identifying UA. Verified 2026-09-01 against the real
+                // endpoint: this UA returns 200 — the endpoint does not require Claude
+                // Code's own UA, so we do not impersonate it.
+                "User-Agent": "claude-code/AgentWrangler-oauth-usage-reader",
+            },
+        });
+        if (!res.ok) {
+            if (res.status === 401) {
+                return {
+                    ok: false,
+                    reason: "OAuth token rejected (401) — re-login to Claude Code.",
+                    status: 401,
+                };
+            }
+            if (res.status === 429) {
+                return {
+                    ok: false,
+                    reason: "Rate limited (429) — try again later.",
+                    status: 429,
+                };
+            }
+            return {
+                ok: false,
+                reason: `HTTP ${res.status} from oauth/usage`,
+                status: res.status,
+            };
+        }
+        const raw = await res.json();
+        const data = parseUsageData(raw);
+        if (data === null) {
+            return { ok: false, reason: "oauth/usage returned an invalid response shape." };
+        }
+        return { ok: true, data };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            reason: `Could not reach ${USAGE_URL}: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+}

package/dist/outcomes/branch-key.js

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+const NORMALIZATION_VERSION = "branch-v1";
+const LOCAL_HEAD_PREFIX = "refs/heads/";
+const FULL_COMMIT_SHA = /^[0-9a-f]{40}$/i;
+const FORBIDDEN_CHARACTERS = /[\\~^:?*\[]/u;
+const WHITESPACE_OR_CONTROL = /[\s\p{Cc}]/u;
+function isDetachedHeadMarker(ref) {
+    const lower = ref.toLowerCase();
+    return (lower === "detached" ||
+        lower === "detached head" ||
+        lower === "(detached)" ||
+        lower === "(no branch)" ||
+        lower.startsWith("(head detached ") ||
+        lower.startsWith("head detached "));
+}
+/**
+ * Convert a valid Git branch ref directly to its privacy-safe equality key.
+ *
+ * The normalized ref never leaves this function. Invalid or absent values
+ * abstain with null rather than producing a key.
+ */
+export function fingerprintBranchRef(value) {
+    if (typeof value !== "string")
+        return null;
+    const byteLength = Buffer.byteLength(value, "utf8");
+    if (byteLength < 1 || byteLength > 255)
+        return null;
+    if (value.trim() !== value || WHITESPACE_OR_CONTROL.test(value))
+        return null;
+    const ref = value.startsWith(LOCAL_HEAD_PREFIX) ? value.slice(LOCAL_HEAD_PREFIX.length) : value;
+    if (ref.length === 0)
+        return null;
+    if (ref === "HEAD" || ref === "@" || FULL_COMMIT_SHA.test(ref) || isDetachedHeadMarker(ref)) {
+        return null;
+    }
+    if (ref.includes("..") || ref.includes("@{") || FORBIDDEN_CHARACTERS.test(ref))
+        return null;
+    const components = ref.split("/");
+    if (components.some((component) => component.length === 0 ||
+        component.startsWith(".") ||
+        component.endsWith(".") ||
+        component.endsWith(".lock"))) {
+        return null;
+    }
+    return createHash("sha256")
+        .update(`${NORMALIZATION_VERSION}\0`, "utf8")
+        .update(ref, "utf8")
+        .digest("hex");
+}

package/dist/outcomes/conclusions.js

@@ -0,0 +1,45 @@
+/**
+ * src/outcomes/conclusions.ts — shared PURE post-processing for GitHub reads.
+ *
+ * M-03 dedup: both GitHub transports (fetch-based client.ts and gh-CLI
+ * gh-cli-client.ts) aggregated check-run conclusions and normalized PR bodies
+ * with copy-pasted logic. Only the transport differs (HTTP fetch vs `gh api`
+ * subprocess); this module owns the transport-independent post-processing so
+ * the two can never drift. NO wire calls, pagination, retry, or timeout logic
+ * lives here.
+ */
+/** Conclusions that do NOT block a SUCCESS verdict. */
+const BENIGN_CONCLUSIONS = new Set(["SUCCESS", "SKIPPED", "NEUTRAL"]);
+/**
+ * Aggregate a fetched check-runs body into the single conclusion string
+ * consumed by work_items.checks_conclusion:
+ *   truncated body → {ok:false, reason:"github-checks-truncated:n/m"} (honest
+ *   refusal rather than a conclusion from partial data; warns on stderr),
+ *   zero runs → "NONE",
+ *   any FAILURE → "FAILURE",
+ *   anything not SUCCESS/SKIPPED/NEUTRAL → "PENDING",
+ *   otherwise → "SUCCESS".
+ */
+export function aggregateCheckConclusion(body) {
+    const runs = body.check_runs;
+    if (body.total_count > runs.length) {
+        console.warn(`Outcomes: check-runs truncated (${runs.length}/${body.total_count}) — conclusion may be incomplete`);
+        return { ok: false, reason: `github-checks-truncated:${runs.length}/${body.total_count}` };
+    }
+    if (runs.length === 0)
+        return { ok: true, data: "NONE" };
+    const conclusions = runs.map((r) => r.conclusion?.toUpperCase() ?? "PENDING");
+    if (conclusions.includes("FAILURE"))
+        return { ok: true, data: "FAILURE" };
+    if (conclusions.some((c) => !BENIGN_CONCLUSIONS.has(c))) {
+        return { ok: true, data: "PENDING" };
+    }
+    return { ok: true, data: "SUCCESS" };
+}
+/**
+ * Normalize a fetched PR JSON object to the PR-body string: null/missing body
+ * → "" (both transports previously duplicated the `?? ""`).
+ */
+export function normalizePRBody(data) {
+    return data.body ?? "";
+}

package/dist/outcomes/derive.js

@@ -0,0 +1,94 @@
+/**
+ * src/outcomes/derive.ts — Outcome derivation.
+ *
+ * Pure versioned deriveOutcome() per plan §3.4 + Spec §3.
+ * 5 branches:
+ *   1. state=OPEN              → IN_PROGRESS
+ *   2. state=CLOSED (abandoned) → OBSERVED_FAILURE  (no merge)
+ *   3. state=MERGED, deferral findings → OBSERVED_SUCCESS_WITH_DEFERRALS
+ *   4. state=MERGED, checks=FAILURE   → OBSERVED_FAILURE
+ *   5. state=MERGED, otherwise        → OBSERVED_SUCCESS
+ *   checks=NONE: MERGED + no CI → treat as OBSERVED_SUCCESS (checks_conclusion='NONE' annotation only)
+ *
+ * writeObservedOutcomes(): upserts derived outcomes for all linked terminal PRs.
+ */
+export const METHODOLOGY_VERSION = "outcome-v1";
+// COND-1: per-extractor precision map. All three extractors are EXPERIMENTAL
+// and excluded from gated/deferral denominators.
+const EXPERIMENTAL_SOURCES = new Set(["UNRESOLVED_THREAD", "DEFERRAL_SECTION", "DIFF_MARKER"]);
+/**
+ * A finding counts toward deferral denominators only when:
+ *  - source is deterministic (not LLM, not EXPERIMENTAL source)
+ *  - OR (source=LLM AND human_state='CONFIRMED')
+ * Since all three current extractors are EXPERIMENTAL, this effectively means
+ * only LLM+CONFIRMED findings count in gated denominators (conservative COND-1).
+ */
+function isGatedFinding(f) {
+    if (EXPERIMENTAL_SOURCES.has(f.source))
+        return false; // COND-1 exclusion
+    if (f.source === "LLM" && f.human_state !== "CONFIRMED")
+        return false;
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Core derivation (pure — no DB access)
+// ---------------------------------------------------------------------------
+/**
+ * Derive the outcome for a single work item.
+ * Findings passed in may be empty ([]) if no findings exist.
+ *
+ * The COND-1 gate applies only to the deferral branch:
+ *   OBSERVED_SUCCESS_WITH_DEFERRALS requires ≥1 gated DEFERRED finding.
+ *   Experimental findings are written and displayed but not counted toward
+ *   this determination (conservative).
+ */
+export function deriveOutcome(workItem, findings) {
+    // Branch 1: still open
+    if (workItem.state === "OPEN")
+        return "IN_PROGRESS";
+    // Branch 2: closed without merge (abandoned)
+    if (workItem.state === "CLOSED")
+        return "OBSERVED_FAILURE";
+    // state === "MERGED" beyond here
+    // Branch 4: CI failure
+    if (workItem.checks_conclusion === "FAILURE")
+        return "OBSERVED_FAILURE";
+    // Branch 3: gated deferred findings → success with deferrals
+    const hasDeferral = findings.some((f) => f.status === "DEFERRED" && isGatedFinding(f));
+    if (hasDeferral)
+        return "OBSERVED_SUCCESS_WITH_DEFERRALS";
+    // Branch 5 (incl. checks=NONE + checks=SUCCESS): clean success
+    return "OBSERVED_SUCCESS";
+}
+// ---------------------------------------------------------------------------
+// DB write pass
+// ---------------------------------------------------------------------------
+/**
+ * Derive and write observed_outcomes for all linked terminal PRs.
+ * "Terminal" = state in (MERGED, CLOSED) with ≥1 session_work_links row.
+ * Idempotent — ON CONFLICT DO UPDATE.
+ */
+export function writeObservedOutcomes(db, methodologyVersion = METHODOLOGY_VERSION) {
+    const workItems = db
+        .prepare(`SELECT wi.work_item_id, wi.state, wi.checks_conclusion
+       FROM work_items wi
+       WHERE wi.state IN ('MERGED', 'CLOSED')
+         AND EXISTS (SELECT 1 FROM session_work_links l WHERE l.work_item_id = wi.work_item_id)`)
+        .all();
+    const getFindingsStmt = db.prepare(`SELECT status, source, human_state, extractor_version
+     FROM review_findings WHERE work_item_id = ?`);
+    const upsert = db.prepare(`
+    INSERT INTO observed_outcomes (work_item_id, outcome, derived_at, methodology_version)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(work_item_id) DO UPDATE SET
+      outcome             = excluded.outcome,
+      derived_at          = excluded.derived_at,
+      methodology_version = excluded.methodology_version
+  `);
+    const now = new Date().toISOString();
+    for (const wi of workItems) {
+        const findings = getFindingsStmt.all(wi.work_item_id);
+        const outcome = deriveOutcome(wi, findings);
+        upsert.run(wi.work_item_id, outcome, now, methodologyVersion);
+    }
+}

package/dist/outcomes/finding-extractors.js

@@ -0,0 +1,131 @@
+/**
+ * Pure, deterministic projections for the experimental E1/E2/E3 finding
+ * extractors. These functions never read or write the operator database.
+ * Callers must keep the returned evidence text in memory or approved ephemeral
+ * evidence state; production persists only the structural identifiers.
+ */
+export const EXTRACTOR_VERSIONS = {
+    E1: "unresolved-thread-v1",
+    E2: "deferral-section-v1",
+    E3: "diff-marker-v1",
+};
+/**
+ * Project current GitHub review-thread state. Current `isResolved` is never
+ * represented as proof of state at merge.
+ */
+export function projectReviewThreadFindings(workItemId, threads) {
+    return threads.map((thread) => ({
+        sourceFindingId: `e1:${workItemId}:${thread.id}`,
+        evidenceRef: thread.id,
+        status: thread.isResolved ? "ADDRESSED" : "DEFERRED",
+        evidence: {
+            stateAtRelevantTime: thread.isResolved ? "RESOLVED" : "UNRESOLVED",
+            temporalBasis: "CURRENT_STATE_ONLY",
+        },
+    }));
+}
+const DEFERRAL_HEADING_RE = /^#{1,4}\s*(deferred|follow[- ]?ups?|known issues|out of scope)\b/im;
+function deferralKeywordClass(headingLine) {
+    const keyword = (/(deferred|follow[- ]?ups?|known issues|out of scope)/i.exec(headingLine)?.[1] ?? "").toLowerCase();
+    if (keyword.startsWith("defer"))
+        return "deferred";
+    if (keyword.startsWith("follow"))
+        return "follow-ups";
+    if (keyword.startsWith("known"))
+        return "known-issues";
+    if (keyword.startsWith("out"))
+        return "out-of-scope";
+    return "section";
+}
+export function extractDeferralFindings(body, workItemId) {
+    const results = [];
+    let inSection = false;
+    let sectionClass = "section";
+    let itemIndex = 0;
+    for (const line of body.split("\n")) {
+        if (DEFERRAL_HEADING_RE.test(line)) {
+            inSection = true;
+            sectionClass = deferralKeywordClass(line);
+            itemIndex = 0;
+            continue;
+        }
+        if (!inSection)
+            continue;
+        if (/^#{1,4}\s/.test(line)) {
+            inSection = false;
+            continue;
+        }
+        if (!/^\s*[-*]\s+\S/.test(line))
+            continue;
+        results.push({
+            sourceFindingId: `e2:${workItemId}:${results.length}`,
+            evidenceRef: `${workItemId}:e2:${sectionClass}:${itemIndex}`,
+            status: "DEFERRED",
+            evidenceText: line,
+        });
+        itemIndex++;
+    }
+    return results;
+}
+const EXCLUDED_GLOBS = [
+    /package-lock\.json$/,
+    /yarn\.lock$/,
+    /pnpm-lock\.yaml$/,
+    /composer\.lock$/,
+    /Gemfile\.lock$/,
+    /poetry\.lock$/,
+    /go\.sum$/,
+    /node_modules\//,
+    /vendor\//,
+    /dist\//,
+    /build\//,
+    /\.min\.js$/,
+    /\.min\.css$/,
+];
+const TODO_FIXME_RE = /\b(TODO|FIXME)\b/;
+const DIFF_FILE_RE = /^\+\+\+\s+b\/(.+)$/;
+const DIFF_HUNK_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+const DIFF_ADD_RE = /^\+(?!\+\+)/;
+function isExcludedFile(filePath) {
+    return EXCLUDED_GLOBS.some((pattern) => pattern.test(filePath));
+}
+/** Pure E3 detection seam. It deliberately has no commit or work-item identity. */
+export function projectDiffMarkerCandidates(diff) {
+    const results = [];
+    let currentFile = "";
+    let lineNumber = 0;
+    for (const line of diff.split("\n")) {
+        const fileMatch = DIFF_FILE_RE.exec(line);
+        if (fileMatch !== null) {
+            currentFile = fileMatch[1] ?? "";
+            continue;
+        }
+        const hunkMatch = DIFF_HUNK_RE.exec(line);
+        if (hunkMatch !== null) {
+            lineNumber = Number.parseInt(hunkMatch[1] ?? "0", 10) - 1;
+            continue;
+        }
+        if (DIFF_ADD_RE.test(line)) {
+            lineNumber++;
+            if (!isExcludedFile(currentFile) && TODO_FIXME_RE.test(line)) {
+                results.push({
+                    evidenceText: line.slice(1),
+                    filePath: currentFile,
+                    lineNumber,
+                });
+            }
+        }
+        else if (line.startsWith(" ")) {
+            lineNumber++;
+        }
+    }
+    return results;
+}
+export function extractDiffMarkerFindings(diff, commitSha, workItemId) {
+    return projectDiffMarkerCandidates(diff).map((candidate, index) => ({
+        sourceFindingId: `e3:${workItemId}:${index}`,
+        evidenceRef: `${candidate.filePath}:${candidate.lineNumber}@${commitSha.slice(0, 7)}`,
+        status: "UNKNOWN",
+        ...candidate,
+    }));
+}