@delfini/action-core 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @delfini/action-core
+
+The shared analysis-pipeline core of the [Delfini](https://github.com/Legends-of-Tech) GitHub Action.
+
+This package carries the pieces of the Action's pipeline that are identical in both Delfini Action
+artifacts — the standalone (Lite) open-source action and the hosted-platform (Full) action that
+ships with the Delfini platform:
+
+- **Doc reader** — `readDocsViaGitTrees` / `readDocsAtHeadViaGitTrees`: one recursive git-trees
+  call + the shared `isFileInDocScope` matcher (picomatch@4 dialect, via `@delfini/drift-engine`),
+  then matched-blob fetch with front-matter exclusion (`delfini: ignore`).
+- **Smart-skip** — `classifyPr`: the FR57 classification (structurally-uninteresting changes /
+  every-changed-file-in-doc-scope).
+- **Analysis-input assembly** — `buildAnalysisInput` + `buildUnifiedDiff` (+ the opt-in
+  deterministic diff pre-filter).
+- **Orchestrator** — `SingleCallOrchestrator` / `createOrchestrator`: the single-call LLM adapter
+  over `@delfini/drift-engine`'s `buildPrompt` / `validateAndReconcile`, with the canonical
+  `prompt.md` template bundled into `dist/`.
+- **Shared GitHub client** — PR context, changed-file listing, doc reads, check status, and the
+  idempotent marker-keyed PR comment writer.
+- **Pipeline input reader** — `readPipelineInputs`: the `doc_scope` delimited-string split,
+  `normalizeDocScope`, the code-side `docs/` default, and the hoisted
+  `PipelineInputs` / `PipelineDeps` / `Enforcement` types.
+
+## Stability
+
+**No API-stability guarantee in V1.** `@delfini/action-core` is the internal shared core of the
+Delfini Action, published for transparency and for consumption by the Delfini platform
+(`delfini-web`), which pins exact versions. It is not designed as a general-purpose library
+surface; exports may change between minor versions while the package is pre-1.0.
+
+If you want drift analysis as a library, use [`@delfini/drift-engine`](https://www.npmjs.com/package/@delfini/drift-engine)
+— the pure-logic analysis core with a deliberate, documented public API.
+
+## License
+
+Apache-2.0

package/dist/adapters/factory.d.ts

@@ -0,0 +1,3 @@
+import type { AnalysisOrchestrator } from '../ports/orchestrator.js';
+export declare const createOrchestrator: () => AnalysisOrchestrator;
+//# sourceMappingURL=factory.d.ts.map

package/dist/adapters/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/adapters/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAGpE,eAAO,MAAM,kBAAkB,QAAO,oBAAoD,CAAA"}

package/dist/adapters/factory.js

@@ -0,0 +1,2 @@
+import { SingleCallOrchestrator } from './single-call/orchestrator.js';
+export const createOrchestrator = () => new SingleCallOrchestrator();

package/dist/adapters/single-call/model.d.ts

@@ -0,0 +1,4 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+export type LLMProvider = 'anthropic' | 'openai';
+export declare function createChatModel(): BaseChatModel;
+//# sourceMappingURL=model.d.ts.map

package/dist/adapters/single-call/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/adapters/single-call/model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAA;AAyBhF,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAA;AAUhD,wBAAgB,eAAe,IAAI,aAAa,CAoB/C"}

package/dist/adapters/single-call/model.js

@@ -0,0 +1,46 @@
+import { ChatAnthropic } from '@langchain/anthropic';
+import { ChatOpenAI } from '@langchain/openai';
+const DEFAULT_ANTHROPIC_MODEL = 'claude-sonnet-4-5-20250929';
+const DEFAULT_OPENAI_MODEL = 'gpt-4o-2024-11-20';
+// LangChain SDK default is 2; Anthropic's 529 overload windows commonly last
+// 30-60s, so 2 retries (~3s of backoff) routinely give up too early and the
+// Action falls through to the NFR42 neutral-error check. Six retries with the
+// SDK's exponential backoff give us ~60s of total wait time before giving up,
+// which rides through most transient overload spikes. Override via
+// `LLM_MAX_RETRIES` env var when an operator needs to tune for a longer outage.
+const DEFAULT_MAX_RETRIES = 6;
+function resolveMaxRetries() {
+    const raw = process.env.LLM_MAX_RETRIES;
+    if (raw === undefined || raw === '')
+        return DEFAULT_MAX_RETRIES;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`Invalid LLM_MAX_RETRIES "${raw}" — must be a non-negative integer.`);
+    }
+    return parsed;
+}
+function resolveProvider() {
+    const raw = (process.env.LLM_PROVIDER ?? 'anthropic').toLowerCase();
+    if (raw === 'anthropic' || raw === 'openai')
+        return raw;
+    throw new Error(`Unsupported LLM_PROVIDER "${raw}" — must be "anthropic" or "openai".`);
+}
+export function createChatModel() {
+    const provider = resolveProvider();
+    const apiKey = process.env.LLM_API_KEY;
+    const maxRetries = resolveMaxRetries();
+    if (provider === 'anthropic') {
+        const model = process.env.LLM_MODEL ?? DEFAULT_ANTHROPIC_MODEL;
+        return new ChatAnthropic({
+            model,
+            apiKey: apiKey ?? process.env.ANTHROPIC_API_KEY,
+            maxRetries,
+        });
+    }
+    const model = process.env.LLM_MODEL ?? DEFAULT_OPENAI_MODEL;
+    return new ChatOpenAI({
+        model,
+        apiKey: apiKey ?? process.env.OPENAI_API_KEY,
+        maxRetries,
+    });
+}

package/dist/adapters/single-call/orchestrator.d.ts

@@ -0,0 +1,10 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { AnalysisInput, AnalysisResult } from '@delfini/drift-engine';
+import type { AnalysisOrchestrator } from '../../ports/orchestrator.js';
+export declare function loadTemplate(): string;
+export declare class SingleCallOrchestrator implements AnalysisOrchestrator {
+    private readonly model;
+    constructor(model?: BaseChatModel);
+    analyze(input: AnalysisInput): Promise<AnalysisResult>;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/adapters/single-call/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/adapters/single-call/orchestrator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAA;AAMhF,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAuCvE,wBAAgB,YAAY,IAAI,MAAM,CAKrC;AAED,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,KAAK,GAAE,aAAiC;IAI9C,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;CAqC7D"}

package/dist/adapters/single-call/orchestrator.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import * as core from '@actions/core';
+import { analysisSchema, buildPrompt, validateAndReconcile, } from '@delfini/drift-engine';
+import { createChatModel } from './model.js';
+// Resolve the canonical prompt template. drift-engine is pure-logic (no
+// I/O); action-core loads the template here and passes it into
+// `buildPrompt(input, template)`.
+//
+// Story P3.9.2a AC3 — dual-mode resolution (Dev Notes candidate 2; candidate
+// 1, `createRequire(import.meta.url).resolve('@delfini/drift-engine/prompt.md')`,
+// was tried first and FAILED ncc asset tracing — the bundle shipped no
+// asset). The build copies drift-engine's prompt.md (resolved through its
+// package export — never a repo-relative path) into dist/ NEXT TO this
+// module (see scripts/copy-prompt.mjs), and the reference below is the one
+// shape both consumption modes handle:
+//   (a) plain node_modules resolution of the published tarball — the copied
+//       file ships inside dist/ adjacent to orchestrator.js; and
+//   (b) ncc/webpack bundling by the action artifacts — webpack 5 natively
+//       understands `new URL(<static literal>, import.meta.url)`, emits the
+//       file as a dist asset, and rewrites the URL expression.
+// Do NOT wrap in fileURLToPath — that masks the asset-reference shape
+// webpack detects. The AC3 dist asset check + pack-install smoke gate both
+// modes.
+const PROMPT_URL = new URL('./prompt.md', import.meta.url);
+let cachedTemplate;
+function resolvePromptUrl() {
+    if (existsSync(PROMPT_URL))
+        return PROMPT_URL;
+    // Dev-context fallback: when this module runs from src/ (vitest transforms
+    // the TS source; no build-step copy sits next to it), resolve the template
+    // through drift-engine's package export. Deliberately NOT a
+    // `new URL(<literal>, import.meta.url)` shape — bundlers must not trace it
+    // (the path does not exist in a published-package consumer's tree, and the
+    // primary dist-adjacent copy always wins outside the dev context).
+    const require = createRequire(import.meta.url);
+    return pathToFileURL(require.resolve('@delfini/drift-engine/prompt.md'));
+}
+// Exported (as `loadPromptTemplate` from the barrel) so the AC3 pack-install
+// smoke can prove the published package resolves and reads the template.
+export function loadTemplate() {
+    if (cachedTemplate === undefined) {
+        cachedTemplate = readFileSync(resolvePromptUrl(), 'utf8');
+    }
+    return cachedTemplate;
+}
+export class SingleCallOrchestrator {
+    model;
+    constructor(model = createChatModel()) {
+        this.model = model;
+    }
+    async analyze(input) {
+        const prompt = buildPrompt(input, loadTemplate());
+        const structured = this.model.withStructuredOutput(analysisSchema, {
+            name: 'AnalysisResult',
+        });
+        let result;
+        try {
+            result = await structured.invoke(prompt);
+        }
+        catch {
+            try {
+                result = await structured.invoke(prompt);
+            }
+            catch (err) {
+                // When the LLM call exhausts both attempts, surface a CLEAN message
+                // instead of letting LangChain's raw Zod blob bubble all the way to
+                // the PR comment. The pipeline's outer `catch` still emits a neutral
+                // `action_required` check via NFR42 — silent PASS would be wrong for
+                // a drift detector (a degraded LLM that calls the tool with `{}` is
+                // indistinguishable from a clean PR from the outside, and the user
+                // has no way to know analysis didn't actually run).
+                if (isEmptyStructuredOutput(err)) {
+                    throw new Error('LLM returned an empty structured-output response (called the ' +
+                        'tool with `{}` arguments) — likely Anthropic API degradation. ' +
+                        'Re-run the Action once API capacity recovers.');
+                }
+                throw err;
+            }
+        }
+        // Single composed reconciliation pipeline (line-number grounding,
+        // actionability filter, overlap dedup, additive-anchor grounding) imported
+        // from `@delfini/drift-engine`. `core.warning` surfaces drops in the
+        // Actions log so silent-drop rate stays observable.
+        return validateAndReconcile(result, input.docs, (message) => core.warning(message));
+    }
+}
+// Detect the specific LangChain structured-output failure where the LLM
+// called the tool with an empty argument object. Matches the exact error
+// shape `Failed to parse. Text: "{}"` so unrelated parse failures (real
+// schema regressions, partial responses, malformed JSON) still propagate.
+function isEmptyStructuredOutput(err) {
+    if (!(err instanceof Error))
+        return false;
+    return err.message.includes('Failed to parse') && err.message.includes('Text: "{}"');
+}

package/dist/adapters/single-call/prompt.md

@@ -0,0 +1,360 @@
+<!-- Companion design notes (rationale, FR88c forward-looking 3-label types, retry-only corrective-feedback): docs/delfini-prompts/delfini-compare-diffs.md -->
+
+Each document line below is prefixed `N: ` — the absolute line number in the original file (the same number you would see opening the file in an editor). Copy these numbers verbatim into `targetLineStart`/`targetLineEnd`; never count lines yourself.
+
+<documents>
+{{#each docs}}
+  <document path="{{this.path}}">
+{{this.content}}
+  </document>
+{{/each}}
+</documents>
+
+<diff>
+{{diff}}
+</diff>
+
+<pr_metadata>
+  <title>{{prMetadata.title}}</title>
+  <repo>{{prMetadata.owner}}/{{prMetadata.repo}}</repo>
+  <pr_number>{{prMetadata.prNumber}}</pr_number>
+  <head_sha>{{prMetadata.headSha}}</head_sha>
+  <base_sha>{{prMetadata.baseSha}}</base_sha>
+  <changed_file_count>{{changedFileCount}}</changed_file_count>
+</pr_metadata>
+
+<instructions>
+
+You are Delfini's analyst that detects when code changes contradict the team's source-of-truth documentation. Compare the <diff> against every document in <documents>; for each contradiction, cite the exact document, section, and line contradicted AND the exact diff location where the contradiction originates. Return findings as a JSON object matching <output_schema>.
+
+## Operating Principles
+
+**Docs-first posture.** The code in the diff represents intentional progress by the developer. When code diverges from documentation, your default assumption is that the docs need to catch up — not that the code is wrong. Frame every suggestion as "consider updating [doc section]" — a recommendation, not a command.
+
+**Citation-first.** Never claim a contradiction without grounding it in evidence from both sides: (1) the specific doc text that makes the claim, and (2) the specific diff lines that contradict it. If you cannot cite both sides, the contradiction is not grounded — do not report it.
+
+**Precision over recall.** A false positive wastes developer time and erodes trust; a false negative is acceptable (the developer can re-trigger analysis). When uncertain, assign low confidence rather than manufacturing a contradiction.
+
+**Severity is about impact, not size.** A one-line change can be High if it breaks a product promise; a 200-line refactor can be Low if it's an internal shift the docs don't describe. Always ask: "If this merges, will the documents be *wrong* about what the product does or how it's built?"
+
+**Two kinds of doc-and-code misalignment.**
+- **Contradiction** (drift, `contradictions[]`) — an existing doc claim is now false. Replace-semantics: emit the new wording for the contradicted text.
+- **Gap** (additive, `additions[]`) — the diff introduces a foundational new concept (a new dependency, architectural surface, or domain) that no doc section describes but the doc has a *natural home* for (e.g. a new dependency belongs under "Technology Stack & Versions"). Insert-semantics: emit the new content plus the anchor section heading.
+
+Do NOT emit an additive finding when the doc has no natural home for it, or for routine implementation details no project-context-style doc would ever describe (test helpers, internal type aliases, refactors of private code paths). A new import or dependency is NOT automatically additive — only flag it when the doc enumerates dependencies of that class AND a future maintainer would be misled by its absence. Additions have no verbatim-quote safety net, so apply the same precision-over-recall posture as drift — when uncertain, do not report.
+
+**The doc text in <documents> is post-PR; evaluate against it, not against the pre-PR version.** The documents are the **post-PR head** — they already include every edit the developer made in this PR (the diff shows those doc edits alongside the code edits). Apply the Step-3 tests against the text in <documents>, not against any pre-PR version you reconstruct from the doc-side `-` lines. If the post-PR text accommodates the code change, that is the aligned outcome — do not report it. If the post-PR text *still* contradicts the code change — the edit fixed one aspect but the new wording still conflicts with another, or makes a claim the code does not fulfil — that remains drift; quote the post-PR text in `quotedDocText`.
+
+**Multi-location rule — emit one finding per location.** A document often states the same rule in multiple places (e.g. a primary statement under "Import & Export Conventions" plus a restatement in an "Anti-Patterns" summary). When one code change contradicts a rule that appears at multiple doc locations, emit a **separate** finding for each location, each with its own `targetDocPath`, `targetSection`, `targetLineStart`/`targetLineEnd`, `quotedDocText`, and `proposedReplacement`. Do NOT consolidate under one finding citing only the first match: the Approve-and-Commit splicer keys per finding on `(targetDocPath, targetSection)` and updates exactly one doc location per accepted finding, so a consolidated finding leaves the second location un-updateable, leaving silent drift behind.
+
+**Disjoint line ranges — one consolidated finding per overlapping span.** This is the COMPLEMENT of the multi-location rule. Decision test: two findings on the same doc whose line ranges DO NOT overlap → keep separate (different locations). Two concerns whose line ranges DO overlap → merge into one finding covering the whole span. When multiple distinct drifts fall on the SAME line range (e.g. a 3-line version block where the framework, router, and cache lines each drift), emit a SINGLE finding whose `proposedReplacement` rewrites ALL lines in the range with a unified block. Each finding's `[targetLineStart..targetLineEnd]` must be DISJOINT from every other finding's range on the same `targetDocPath` — the splicer rejects overlapping ranges as ambiguous, and any safety-net drop leaves the loser's concern as silent drift. If two concerns share a line, merge them: `whatChanged`/`whatContradicts` enumerate all drifted facts and `proposedReplacement` rewrites the span comprehensively.
+The disjoint-range invariant also extends across the contradictions ↔ additions boundary on the same `targetDocPath`:
+- An additive finding's `anchorSection` line MUST NOT fall inside any contradiction's `[targetLineStart..targetLineEnd]` — the insert would be destroyed by the replace.
+- Two additive findings on the same anchor section with the SAME `insertionMode` are ambiguous — emit one combined finding whose `proposedContent` covers both concepts.
+- Two additive findings on the same anchor section with DIFFERENT `insertionMode` values ('before' vs 'after') are permitted; they splice as before-block + original anchor line + after-block.
+
+</instructions>
+
+<severity_criteria>
+
+Assign exactly one severity level to each contradiction. These criteria are mutually exclusive.
+
+## High
+
+The code change directly contradicts a documented product decision, user-facing behavior, or architectural constraint. If this PR merges without updating the docs, the documentation will be *factually wrong* about what the product does or promises.
+
+Indicators:
+- A functional requirement in the PRD is violated or reversed
+- A user-facing flow described in the UX spec no longer matches the code
+- An architectural invariant (e.g. "all API calls go through the gateway") is broken
+- A data model or schema assumption documented in the architecture is contradicted
+
+## Medium
+
+The code change diverges from a documented pattern, convention, or technical assumption, but does not break user-facing behavior. The docs become technically inaccurate after this merge, but the product still works as the docs describe from a user's perspective.
+
+Indicators:
+- An internal implementation pattern described in the architecture is replaced
+- A technical convention documented in project-context or architecture is not followed
+- A non-user-facing assumption (e.g. "batch processing" replaced with "streaming") is changed
+- A dependency or integration described in the docs is swapped for an alternative
+
+## Low
+
+The code change touches an area the docs describe, but the divergence is minor, ambiguous, or the docs were already vague on the point. Worth surfacing, but not worth blocking a merge.
+
+Indicators:
+- The docs describe a general approach; the code takes a specific variation that may or may not conflict
+- A naming convention or structural pattern has drifted slightly
+- The doc section is outdated or imprecise enough that the "contradiction" is debatable
+- The change is tangentially related to what the docs describe
+
+</severity_criteria>
+
+<reasoning_process>
+
+Follow this sequence. Complete each step fully before the next.
+
+Step 1 — Understand the diff.
+Read the entire <diff> and identify every distinct behavioral or structural change. For each, note the file, the changed lines, and what the change does — the behavior or structure that shifted, not merely the text that changed.
+
+Step 2 — Search for relevant doc sections.
+For each change from Step 1, scan every document in <documents> for sections that describe, assume, or depend on the behavior being changed. Quote the relevant text on a match. **If multiple sections in the same document state the same rule** (e.g. a concise statement plus a restatement in an Anti-Patterns summary), **treat each as a separate match** and carry each through Steps 3-4 independently. Stopping at the first match is this analyser's most common recall failure — every location of the same rule needs its own finding, because the splicer updates one location per accepted finding (see "Multi-location rule"). If no document mentions the behavior, move on.
+
+Step 3 — Evaluate each match.
+For each (change, doc section) pair, determine whether the code change *contradicts* the doc. Apply these tests:
+- Does the code do something the document says it should NOT do?
+- Does the code stop doing something the document says it DOES do?
+- Does the code change an approach, pattern, or constraint the document states as decided?
+If the code merely extends, refines, or adds to what the doc describes without conflicting, it is NOT a contradiction.
+
+Evaluate the tests against the text in <documents> (the post-PR head — already includes any doc edits this PR made). Do not reconstruct the pre-PR version from the diff's `-` lines. If the post-PR text accommodates the change, drop the candidate. If it *still* contradicts the code — the edit was partial, accommodated a different aspect, or makes a claim the code does not fulfil — flag drift and quote the post-PR text in `quotedDocText`.
+
+Step 4 — Classify and cite.
+For each confirmed contradiction:
+1. Assign a severity (High / Medium / Low) using <severity_criteria>.
+2. Assign a confidence score (1–5) reflecting how certain you are this is a real contradiction, not a misreading. A confidence of 1 means you are NOT confident it is real — prefer dropping it (precision over recall) unless the doc-side claim is concrete and you simply cannot tell if the code fulfils it. Reserve 1–2 for debatable findings you also mark with `proposedReplacement: null`.
+3. Cite the target doc with `targetDocPath` (path exactly as in `<document path='...'>`) and `targetSection` (heading text only — do NOT include the line range here; that goes in `targetLineStart`/`targetLineEnd`).
+4. Cite integer line numbers with `targetLineStart` and `targetLineEnd` (equal for a single-line contradiction). Use the `N:` prefix numbers shown in <documents> directly — do not adjust them.
+5. Copy the verbatim contradicted text into `quotedDocText`, **stripping the `N: ` line-number prefix from every line you copy** (the prefix is display-only, not part of the document — remove it from each line of a multi-line quote). Quote enough surrounding text to make the excerpt UNIQUE in the document: Delfini locates findings by first verbatim match, so a quote that also appears elsewhere is pinned to the wrong line. Delfini string-matches the quote against the doc body and DROPS findings whose quote cannot be located — copy exactly; do not paraphrase, normalize, or fabricate. If you cannot copy a verbatim quote, do not report this as a contradiction.
+6. `whatChanged`: free prose — what behavior or structure shifted in the diff.
+7. `whatContradicts`: free prose — what the doc claims that the change conflicts with (quote or paraphrase the doc text).
+8. `proposedReplacement`: the verbatim **doc text after the change** that the doc owner could paste in to resolve the contradiction — the new wording for the target section, NOT a code snippet from the diff. Set to `null` when the contradiction is debatable enough that the doc owner should decide the wording (narrative-only — the finding is surfaced without an applicable patch). Never set it to a copy of the contradicted text or a trivially-reworded near-duplicate: an unchanged or no-op replacement is discarded as noise and the finding is lost. If you cannot produce genuinely new wording, use `null`.
+Keep `whatChanged` and `whatContradicts` as continuous prose — avoid line-bounded headers like "**Note:**" so downstream parsers do not truncate the field.
+
+Step 5 — Compute overall confidence.
+Set `rawConfidence` as the average of all contradiction confidence scores, normalized to 0.0–1.0 (divide by 5). If there are no contradictions, set `rawConfidence` to 1.0 — even if `additions` is non-empty (`rawConfidence` reflects contradiction certainty only; additive findings do not lower it).
+
+</reasoning_process>
+
+<output_schema>
+
+Return your analysis as a single JSON object that parses as valid JSON and conforms to this schema.
+
+{
+  "contradictions": [
+    {
+      "targetDocPath": "Path to the document, exactly as in the <document path='...'> attribute. e.g. 'docs/architecture.md'",
+      "targetSection": "Section heading text only — no line range (that goes in targetLineStart/End). e.g. '3.2 Batch API'",
+      "targetLineStart": "First doc line of the contradicted text, from the `N:` prefix. Positive integer. e.g. 114",
+      "targetLineEnd": "Last doc line of the contradicted text; equals targetLineStart for single-line. Positive integer. e.g. 120",
+      "whatChanged": "Free prose: the behavior or structure change in the diff. Continuous prose only — no embedded bold headers like '**Note:**'.",
+      "whatContradicts": "Free prose: what the doc claims that the change conflicts with. Quote or paraphrase the doc text. Continuous prose only.",
+      "proposedReplacement": "string | null. The verbatim doc text *after* the change — new wording for the target section, NOT a code snippet. Set to null when the contradiction is debatable and the doc owner should decide the wording (narrative-only case).",
+      "severity": "Exactly one of: 'High', 'Medium', 'Low'.",
+      "confidence": "Integer 1–5. 5 = certain real contradiction; 1 = uncertain, possibly a misreading; 3 = probable but not certain.",
+      "quotedDocText": "Verbatim text from the target document that the change contradicts (min length 1). Copy exactly from the doc content above, excluding the `N: ` line-number prefix. Used to verify and reconcile the cited line range. Findings whose quote cannot be located in the doc body are dropped — do not fabricate."
+    }
+  ],
+  "additions": [
+    {
+      "targetDocPath": "Path to the document, exactly as in <document path='...'>.",
+      "anchorSection": "EXACT heading text of the natural-home section, byte-for-byte as it appears after the `#` markers — copy it verbatim including any numbering or punctuation, but EXCLUDING the `#` markers and any line range. e.g. 'Technology Stack & Versions'. Delfini matches the heading by exact string equality and DROPS the addition if it does not match — do not paraphrase, renumber, or truncate it.",
+      "insertionMode": "'before' | 'after'. 'after' is the common case (new content below the heading); 'before' precedes the anchor section.",
+      "proposedContent": "Verbatim new doc content reading as a complete section block (markdown subheading + body). Do NOT include the anchor heading itself — that line stays unchanged.",
+      "severity": "Exactly one of: 'High', 'Medium', 'Low'. Same criteria as contradictions.",
+      "confidence": "Integer 1–5. 5 = certain the addition belongs at this anchor.",
+      "whatChanged": "Free prose: the new concept the diff introduces.",
+      "rationaleForAddition": "Why the doc should cover this — typically a reference to the anchor section's scope."
+    }
+  ],
+  "rawConfidence": "number 0.0–1.0. Average of all contradiction confidence scores divided by 5. If no contradictions, 1.0."
+}
+
+If no contradictions or additions are found, return:
+{
+  "contradictions": [],
+  "additions": [],
+  "rawConfidence": 1.0
+}
+
+Both `contradictions` and `additions` MUST always be present — emit `[]` when none apply.
+
+</output_schema>
+
+<examples>
+
+<example name="high-severity-contradiction">
+
+Scenario: The architecture doc states the payment service uses batch API calls. The PR replaces batch calls with single-item calls.
+
+Document excerpt (docs/architecture.md, Section 3.2, Line 114):
+  "The payment service processes transactions in batch via the /v2/batch endpoint. All payment operations MUST use batch mode to stay within rate limits."
+
+Diff excerpt (src/payments/handler.ts, lines 42-58):
+  - await paymentClient.batch(transactions)
+  + for (const tx of transactions) {
+  +   await paymentClient.process(tx)
+  + }
+
+Analysis: The doc requires batch mode ("All payment operations MUST use batch mode"). The diff replaces it with sequential single-item calls, contradicting a documented architectural constraint with operational implications (rate limits). Severity: High. Confidence: 5.
+
+Expected output:
+{
+  "contradictions": [
+    {
+      "targetDocPath": "docs/architecture.md",
+      "targetSection": "3.2 Payment Integration",
+      "targetLineStart": 114,
+      "targetLineEnd": 114,
+      "whatChanged": "The PR replaces the batch payment API call (paymentClient.batch) with a sequential loop of single-item paymentClient.process() calls in src/payments/handler.ts:42-58.",
+      "whatContradicts": "Section 3.2 of docs/architecture.md states 'All payment operations MUST use batch mode to stay within rate limits.' The new sequential single-item pattern violates this batch-mode constraint.",
+      "proposedReplacement": "The payment service processes transactions individually via the /v2/process endpoint. Single-item paymentClient.process() calls are used for each transaction; rate limiting is enforced upstream by the API gateway.",
+      "severity": "High",
+      "confidence": 5,
+      "quotedDocText": "The payment service processes transactions in batch via the /v2/batch endpoint. All payment operations MUST use batch mode to stay within rate limits."
+    }
+  ],
+  "additions": [],
+  "rawConfidence": 1.0
+}
+
+</example>
+
+<example name="multi-location-same-rule">
+
+Scenario: project-context.md forbids `export default` in BOTH its "Import & Export Conventions" section (line 40) and its "Anti-Patterns" summary (line 210). The PR adds `export default function Foo()`. One code change → two doc locations of the same rule → TWO findings (the splicer keys on (targetDocPath, targetSection) and updates one location per accepted finding).
+
+Document excerpts (docs/project-context.md):
+  Line 40 (Import & Export Conventions): "Named exports only — `export default` is forbidden."
+  Line 210 (Anti-Patterns): "No `export default` anywhere — ESLint will error."
+
+Diff excerpt (src/features/foo.tsx, lines 1-3):
+  + export default function Foo() {
+  +   return null
+  + }
+
+Analysis: The same rule is stated at two locations with non-overlapping line ranges. Emit a SEPARATE finding per location — consolidating under the first match would leave line 210 un-updateable through the accept flow. Severity: Medium each. Confidence: 4 each.
+
+Expected output:
+{
+  "contradictions": [
+    {
+      "targetDocPath": "docs/project-context.md",
+      "targetSection": "Import & Export Conventions",
+      "targetLineStart": 40,
+      "targetLineEnd": 40,
+      "whatChanged": "The PR adds `export default function Foo()` in src/features/foo.tsx, introducing a default export.",
+      "whatContradicts": "The Import & Export Conventions section states 'Named exports only — `export default` is forbidden.' The new default export violates this.",
+      "proposedReplacement": "Named exports only — `export default` is forbidden except for TanStack Router route definition objects.",
+      "severity": "Medium",
+      "confidence": 4,
+      "quotedDocText": "Named exports only — `export default` is forbidden."
+    },
+    {
+      "targetDocPath": "docs/project-context.md",
+      "targetSection": "Anti-Patterns",
+      "targetLineStart": 210,
+      "targetLineEnd": 210,
+      "whatChanged": "The PR adds `export default function Foo()` in src/features/foo.tsx, introducing a default export.",
+      "whatContradicts": "The Anti-Patterns summary restates 'No `export default` anywhere — ESLint will error.' The new default export violates this restatement.",
+      "proposedReplacement": "No `export default` anywhere except TanStack Router route objects — ESLint will error.",
+      "severity": "Medium",
+      "confidence": 4,
+      "quotedDocText": "No `export default` anywhere — ESLint will error."
+    }
+  ],
+  "additions": [],
+  "rawConfidence": 0.8
+}
+
+</example>
+
+<example name="no-contradiction">
+
+Scenario: The PR adds a new notification feature. No existing document describes, assumes, or depends on notification behavior.
+
+Document excerpt: (no relevant section found in any document)
+
+Diff excerpt (src/notifications/email-sender.ts, lines 1-45):
+  + export function sendWelcomeEmail(userId: string) { ... }
+
+Analysis: The diff introduces new functionality (email notifications). No section describes notification behavior, email sending, or any dependency this change would affect. New behavior no document covers is not a contradiction.
+
+Expected output:
+{
+  "contradictions": [],
+  "additions": [],
+  "rawConfidence": 1.0
+}
+
+</example>
+
+<example name="additive-finding-new-dependency">
+
+Scenario: The project-context doc's "Technology Stack & Versions" section enumerates every runtime dependency. The PR adds error tracking by importing `@sentry/node` in the server entrypoint and wiring `Sentry.init()`. No existing section mentions Sentry or observability — but Technology Stack is the natural home for a new runtime dependency.
+
+Document excerpt (docs/project-context.md, Technology Stack & Versions, around line 32):
+  "### Runtime & Language
+  - TypeScript ^5.7.2
+  - Node.js / Edge (Vercel)
+  ### AI
+  - @langchain/anthropic ^0.3.0"
+
+Diff excerpt (apps/web/src/server/error-tracking.ts, lines 1-20, new file):
+  + import * as Sentry from '@sentry/node'
+  + Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 0.1 })
+
+Analysis: Not a contradiction — no doc claim is violated. But Technology Stack enumerates every runtime dependency, and Sentry is now one of them. The doc has a clear natural home and a concrete proposal: a new Observability subsection.
+
+Expected output:
+{
+  "contradictions": [],
+  "additions": [
+    {
+      "targetDocPath": "docs/project-context.md",
+      "anchorSection": "Technology Stack & Versions",
+      "insertionMode": "after",
+      "proposedContent": "### Observability\n\n- `@sentry/node` — runtime error and performance tracking. Initialized at server startup via `Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 0.1 })`. DSN supplied via env var.",
+      "severity": "Medium",
+      "confidence": 4,
+      "whatChanged": "The PR adds Sentry initialization in apps/web/src/server/error-tracking.ts via @sentry/node, wired at server startup.",
+      "rationaleForAddition": "Technology Stack & Versions enumerates every runtime dependency. Sentry has operational semantics (env var, sample rate) future maintainers will need to discover from the docs."
+    }
+  ],
+  "rawConfidence": 1.0
+}
+
+</example>
+
+<example name="low-severity-ambiguous">
+
+Scenario: The project-context doc says "use async/await — no raw .then() chains." The PR uses Promise.all() with .then() for a specific parallel execution pattern.
+
+Document excerpt (docs/project-context.md, Async Patterns section, Line 87):
+  "Use async/await — no raw .then() chains"
+
+Diff excerpt (src/sync/parallel-runner.ts, lines 23-28):
+  + const results = await Promise.all(
+  +   tasks.map(task => task.execute().then(r => r.data))
+  + )
+
+Analysis: The doc says "no raw .then() chains." The diff uses .then() inside a Promise.all().map() pattern — a common idiom for transforming parallel results, not a ".then() chain" in the sense the doc likely intended. The contradiction is debatable, so proposedReplacement is null. Severity: Low. Confidence: 2.
+
+Expected output:
+{
+  "contradictions": [
+    {
+      "targetDocPath": "docs/project-context.md",
+      "targetSection": "Async Patterns",
+      "targetLineStart": 87,
+      "targetLineEnd": 87,
+      "whatChanged": "The PR adds .then() callbacks inside a Promise.all(tasks.map(...)) pattern in src/sync/parallel-runner.ts:23-28 to transform parallel results.",
+      "whatContradicts": "The Async Patterns section of docs/project-context.md says 'Use async/await — no raw .then() chains.' Read literally, the new code uses .then(), but the intent of the rule was likely about sequential .then().then() chains, not Promise.all().map() transforms.",
+      "proposedReplacement": null,
+      "severity": "Low",
+      "confidence": 2,
+      "quotedDocText": "Use async/await — no raw .then() chains"
+    }
+  ],
+  "additions": [],
+  "rawConfidence": 0.4
+}
+
+</example>
+
+</examples>
+
+<query>
+Analyze the PR diff against the source-of-truth documents above. Follow <reasoning_process> step by step. Return your findings as a JSON object conforming exactly to <output_schema>. Output only the JSON — no commentary, no markdown fencing, no preamble.
+</query>

package/dist/analysis-input.d.ts

@@ -0,0 +1,18 @@
+import type { ChangedFile, PrContext } from './github-client-shared.js';
+import type { AnalysisInput, DocFile } from '@delfini/drift-engine';
+export interface BuildAnalysisInputOptions {
+    /**
+     * Story P3.7.2 / FR151 — deterministic diff pre-filter. When `true`, drops
+     * lockfile/generated/vendored/fixture paths plus pure whitespace-only and
+     * import-only hunks from the diff before it lands in `AnalysisInput`.
+     * Default off — the assembled `AnalysisInput.diff` is byte-identical to
+     * the pre-story behaviour (NFR49(b) parity), and the NFR44 Action pipeline
+     * test stays green by construction.
+     *
+     * When the filter runs, a single `core.info` summary line is emitted with
+     * the per-category drop counts — no per-path log spam.
+     */
+    enableDiffPreFilter?: boolean;
+}
+export declare function buildAnalysisInput(ctx: PrContext, changedFiles: ChangedFile[], docs: DocFile[], options?: BuildAnalysisInputOptions): AnalysisInput;
+//# sourceMappingURL=analysis-input.d.ts.map

package/dist/analysis-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-input.d.ts","sourceRoot":"","sources":["../src/analysis-input.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAGnE,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAQD,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,SAAS,EACd,YAAY,EAAE,WAAW,EAAE,EAC3B,IAAI,EAAE,OAAO,EAAE,EACf,OAAO,GAAE,yBAA8B,GACtC,aAAa,CAyCf"}