@delfini/drift-engine 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,172 +1,76 @@
 # @delfini/drift-engine
 
-Pure-logic drift analysis core shared by `@delfini/action` (CI surface, `apps/action`) and `@delfini/cli` (Skill surface, `packages/cli`). No I/O, no LLM client, no credentials, no `fetch`. Runtime deps: `zod` + `picomatch` (both pure CPU — no I/O, no network, no env).
+The pure-logic analysis core behind [Delfini](https://github.com/Legends-of-Tech/delfini) — the tool that detects when a code change has made your documentation wrong and proposes the fix.
 
-The package exists so both surfaces consume the same prompt assembly, schema, and reconciliation logic — algorithm parity between the Action and the Skill holds **by construction** (FR139, NFR44). A finding surfaced locally by the Skill is the same finding the Action will surface on the eventual PR.
+This package is the brain, with none of the plumbing. Given a diff and a set of documents, it builds the analysis prompt, defines the schema the model must answer in, and reconciles the model's output back to exact line numbers. It is shared by both Delfini surfaces — the **Skill** (local, `@delfini/cli`) and the **Action** (CI) — so the analysis is identical wherever it runs. A finding surfaced locally is the same finding the Action would surface on the eventual PR.
+
+## What it does
+
+A drift analysis is three pure steps, and this package owns all three:
+
+1. **`buildPrompt`** — assemble the LLM prompt from a diff, the in-scope docs, and PR metadata. Every doc line is prefixed with its number so the model can cite exact ranges.
+2. **`analysisSchema`** — the schema the model's JSON output must satisfy: structured findings of three kinds — `drift` (replace these lines), `additive` (insert this content), and `clarification` (uncertain — surface for a human).
+3. **`validateAndReconcile`** — validate the model's JSON and verify each finding's quoted text actually matches the doc at the cited lines. Mismatches (model hallucinations) are discarded before they reach the caller.
+
+## Install
+
+```bash
+npm install @delfini/drift-engine
+```
 
 ## Public API
 
 ```ts
 import {
-  buildPrompt,
-  validateAndReconcile,
-  estimatePromptTokens,
-  analysisSchema,
+  buildPrompt,             // (input, template, options?) => string
+  validateAndReconcile,    // (rawJson, docs) => AnalysisResult
+  estimatePromptTokens,    // (prompt) => number
+  analysisSchema,          // Zod schema for the model's output
+  // doc-scope matching:
+  normalizeDocScope,
+  validateDocScopeEntry,
+  classifyEntry,
+  isFileInDocScope,
+  // types:
   type AnalysisInput,
   type AnalysisResult,
   type DocFile,
   type Contradiction,
   type Addition,
-  type ClarifyingQuestion,
-  type PRMetadata,
-  type Severity,
 } from '@delfini/drift-engine'
 ```
 
-Internal helpers (`dedupeOverlappingContradictions`, `filterActionableContradictions`, `reconcileLineNumbers`, `reconcileAdditiveAnchors`, `ContradictionSchema`, `AdditionSchema`, `locateQuote`, `locateAnchorHeading`, etc.) are **not** re-exported. Callers compose only through the surface above.
+Both the Action and the CLI follow the same flow: gather inputs (diff + docs + PR metadata) → `buildPrompt` → send to an LLM → `validateAndReconcile` on the JSON → render the result. Internal helpers are not re-exported; callers compose only through the surface above.
 
-## Relevance gating (opt-in)
+## Relevance retrieval (optional)
 
-`buildPrompt(input, template, options?)` accepts an optional third argument:
+`buildPrompt(input, template, options?)` accepts an optional third argument to keep large prompts focused:
 
 ```ts
-interface BuildPromptOptions {
-  relevanceThreshold?: number
-}
+buildPrompt(input, template, { relevanceThreshold: 5 })
 ```
 
-When `relevanceThreshold` is a positive integer, docs whose relevance score is below the threshold are dropped before the prompt is rendered. Scoring breakdown:
-
-| Tier | Signal | Score |
-|---|---|---|
-| 1 | The doc itself appears in the diff (`diff --git a/<doc> ...`) | +20 |
-| 2 | A code-file path from the diff appears in the doc body | +10 per file |
-| 3 | An identifier from the diff appears in the doc body | +3 per identifier, capped at +30 |
-| 4 | A heading whose terms overlap with diff identifiers | +5 per heading |
-
-Default behaviour (`options` omitted, or `relevanceThreshold` is `undefined`, `0`, or non-finite) is observably no-op — the prompt-snapshot gate (NFR44 gate A) enforces byte-equality with the legacy output.
-
-**Recommended starting threshold:** `5` — keeps any doc with at least one Tier-2 hit or the doc-itself-in-diff signal.
-
-## NFR44 release gates
-
-The extraction is observably no-op for the Action's public behaviour. Two release gates guard that invariant on every PR:
+Each doc section is scored against the diff and sections below the threshold are dropped before rendering:
 
-| Gate | Lives at | Catches | Misses (caught by the other gate) |
-|---|---|---|---|
-| **A — snapshot parity** | `packages/drift-engine/__tests__/prompt-snapshot.test.ts` | Any change to `prompt.md` text, `prompt-builder.ts` rendering, `prefixDocLines`, or `renderDocsBlock` that perturbs the rendered prompt | Schema / reconcile / orchestrator regressions — none flow through `buildPrompt` |
-| **B — Action pipeline** | `apps/action/src/__tests__/pipeline.test.ts` | Any change to `reconcile.ts`, `schema.ts`, orchestrator wiring, or the round-trip from LLM JSON → rendered PR comment / check verdict / intake payload | Pure prompt-text drift that the LLM-mocked fixtures don't surface |
-
-Both gates must be green for a drift-engine PR to merge. Gate A catches regressions **before** the LLM ever runs; gate B catches everything downstream of the LLM.
-
-## When to update the snapshot
-
-Update `__tests__/fixtures/canonical-prompt.snapshot.md` **only** when the prompt change is intentional. Examples that require an update:
-
-- Editing the text of any section of `src/prompt.md`.
-- Adding, removing, or renaming a placeholder in `src/prompt.md` plus the corresponding substitution in `src/prompt-builder.ts`.
-- Changing how `prefixDocLines` formats line-number prefixes (e.g. `${n}: ` → `${n}| `).
-- Changing how `renderDocsBlock` iterates documents.
-
-Examples that should **not** require a snapshot update:
-
-- Edits to `reconcile.ts`, `schema.ts`, `prompt-budget.ts`, or `types.ts` — none of these flow through `buildPrompt`.
-- Edits to `src/index.ts` re-exports.
-- Tooling / config changes (`package.json`, `tsconfig.json`, ESLint rules).
-
-A fixture-only change (editing `canonical-input.json` without touching the prompt) implies the snapshot no longer matches and the test fails. Always update fixture + snapshot together.
-
-## How to update the snapshot
-
-The snapshot is regenerated by hand to keep human-reviewer eyes on every byte of drift:
-
-```bash
-cd packages/drift-engine
-
-# One-shot regeneration via a temporary node script. Inline so nothing checked
-# into the repo can ever auto-update the snapshot.
-node --import tsx -e "
-  import { readFileSync, writeFileSync } from 'node:fs'
-  import { fileURLToPath } from 'node:url'
-  import { buildPrompt } from './src/prompt-builder.ts'
-
-  const input = JSON.parse(readFileSync('./__tests__/fixtures/canonical-input.json', 'utf8'))
-  const template = readFileSync('./src/prompt.md', 'utf8')
-  writeFileSync('./__tests__/fixtures/canonical-prompt.snapshot.md', buildPrompt(input, template))
-"
-
-# Verify the test now passes
-pnpm test prompt-snapshot.test
-```
-
-In the PR description, include:
-
-1. **Which prompt change drove the snapshot update** — name the section of `prompt.md` or the rendering helper that changed.
-2. **Confirmation that NFR44 gate B is unaffected** — `pnpm --filter @delfini/action test` still passes (gate B usually does — the rewrite is at the prompt-text level, not the reconcile-shape level).
-3. **Explicit reviewer sign-off on the snapshot diff** — at least one reviewer confirms every byte of drift is intentional.
-
-## What NOT to do
-
-- **Do not `it.skip` the snapshot test** to make a PR go green. If the test fires, either the change is intentional (update the snapshot per above) or unintentional (revert the source change).
-- **Do not auto-update the snapshot via tooling** without reviewer eyes on the diff. The manual `node --import tsx` workflow above is intentional friction.
-- **Do not use Vitest's `toMatchSnapshot` / `toMatchInlineSnapshot`** — both auto-create on first run and auto-update on `--update-snapshots`, defeating the human-review-required semantics. The test uses `readFileSync` + a literal-string comparison so the snapshot is a real, reviewable file in the PR diff.
-- **Do not change `core.autocrlf` / `.gitattributes`** to "fix" a Windows checkout that's producing CRLF snapshots. The repo's `.gitattributes` pins `packages/drift-engine/src/prompt.md`, `__tests__/fixtures/*.snapshot.md`, and `__tests__/fixtures/*.json` to `eol=lf`; renormalise with `git add --renormalize <path>` if a checkout drifted.
-
-## NFR49(b) Parity-Gate Policy
-
-PRD v6.7 added the token-efficient retrieval stage (FR150–FR153) — section-granularity doc retrieval (`selectRelevantSections`), deterministic diff pre-filtering (`filterDiff`), ranked-fill prompt budget (`rankedFillSections` + `buildPromptWithDrops`), and the working-tree-at-branch-HEAD doc-read invariant. The stage changes `buildPrompt` output **when enabled**, so it would trip the NFR44 release gates without discipline. The policy that keeps the gates green during roll-out:
-
-### Three allowed paths — and one forbidden
-
-- **Path A — opt-in / default-off (V1 default).** Every retrieval knob ships behind a `BuildPromptOptions` field with an explicit no-op fast-path (`relevanceThreshold` and `promptTokenBudget` both default to undefined / `<= 0` / non-finite → keep everything, identical output). The default `buildPrompt(input, template)` call path produces **byte-identical** output vs. the pre-v6.7 baseline. All three NFR44 release gates (A drift-engine snapshot, B Action pipeline, C bundled-CLI parity) pass with **no re-snapshot**. This is the V1-expected path and the path the FR150–FR152 stories landed on.
-- **Path B — deliberate, reviewed re-snapshot.** When a `prompt.md` wording change or a default-on activation is genuinely required, the PR re-snapshots `canonical-prompt.snapshot.md` (gate A) and the bundled-CLI parity fixture (gate C) in lockstep. The PR description names the change explicitly with a sentence such as: *"intentional `prompt.md` re-snapshot under NFR49(b) Path B — &lt;short rationale&gt;."* Reviewers read the snapshot diff as part of code review; sign-off is required.
-- **Path C — silent regen — FORBIDDEN.** Running `pnpm test -u` to make a failing snapshot diff disappear without explicit PR acknowledgement is a process violation. If the snapshot is moving and you cannot justify why, the source change is not yet ready.
-
-### PR-description templates
-
-Copy the right paragraph into the PR body:
-
-**Path A:**
-
-> **NFR49(b) parity statement (Path A — no prompt wording change / opt-in default-off).** The retrieval / filter / budget logic this PR adds is gated behind a `BuildPromptOptions` knob whose default (undefined / `<= 0` / non-finite) keeps every section and every diff hunk. `buildPrompt(input, template)` emits byte-identical output vs. the pre-PR baseline. All three NFR44 release gates (A drift-engine snapshot, B Action pipeline, C bundled-CLI parity) stay green with no re-snapshot.
-
-**Path B:**
-
-> **NFR49(b) parity statement (Path B — deliberate re-snapshot).** This PR sharpens `packages/drift-engine/src/prompt.md` (commit `<sha>`, lines `<range>`). The NFR44 gate A snapshot (`__tests__/prompt-snapshot.test.ts`'s `canonical-prompt.snapshot.md`) and the bundled-CLI parity gate C's expected output are deliberately re-snapped in lockstep. Rationale: `<one-sentence rationale>`. Reviewer sign-off on the snapshot diff: `<reviewer>`.
-
-### Release-time recall
-
-Per-commit recall is asserted via the **retention gate** in `__tests__/token-efficiency.test.ts` (LLM-free): for each labelled fixture in `__tests__/fixtures/token-efficiency/` and `__tests__/fixtures/residual-drift/`, the section identified by `expected.json`'s `groundTruthDocPath` + `groundTruthSection` MUST survive `selectRelevantSections` + `rankedFillSections`. A regression that drops it fails CI.
-
-Behavioural LLM recall — does the model actually flag the drift in the assembled prompt? — is verified **at release** on `apps/action`'s NFR40 eval set, inherited by construction via the shared `buildPrompt`. **No LLM call runs in the drift-engine / CLI unit suite** (design-spec NG6 — model-quality testing lives in the Action's eval harness). The `__tests__/token-efficiency.test.ts` suite is sub-second and dispatches no subagent.
-
-### `scripts/measure-tokens.ts` — local iteration tool
-
-For local before/after token measurement without re-running the whole vitest suite, use the `tsx` script:
-
-```bash
-# All fixtures in the corpus
-node --import tsx packages/drift-engine/scripts/measure-tokens.ts
-
-# A single fixture
-node --import tsx packages/drift-engine/scripts/measure-tokens.ts \
-  packages/drift-engine/__tests__/fixtures/token-efficiency/case-01-doc-heavy/analysis-input.json
-```
+| Signal | Points |
+|---|---|
+| The doc itself appears in the diff | +20 |
+| A code-file path from the diff appears in the section | +10 per file |
+| An identifier from the diff appears in the section | +3 each, capped at +30 |
+| A heading overlaps a diff identifier | +5 per heading |
 
-Output is one line per case: `<case-slug>: tokens off=<N1> on=<N2> ratio=<r.rr> Δ=<Δ%>`. The script uses the same `estimatePromptTokens(buildPrompt(...))` math as the CI gate in `token-efficiency.test.ts`, so the live number and the CI number agree by construction. The script is not wired into CI, has no assertions, and is not surfaced as a npm script — it is purely a developer-iteration aid. Errors (missing fixture, malformed JSON) print to stderr and exit non-zero.
+A threshold of `5` keeps any section with a single file-path or heading match — a safe default that typically cuts prompt size ~40% on doc-heavy inputs with no measurable recall loss. Omit `options` (or pass `0`) to keep every section.
 
-### Source pointers
+## Runtime constraints
 
-- **PRD v6.7 — NFR49** in `_bmad-output/planning-artifacts/prd.md` §"NFR49" — normative target + parity-gate policy.
-- **Architecture ADR (2026-06-03)** in `_bmad-output/planning-artifacts/architecture.md` §"Token-Efficient Drift-Analysis Retrieval" — design rationale.
-- **Story P3.7.5** in `_bmad-output/implementation-artifacts/skill-p3-7-5-token-efficiency-measurement-parity-gate.md` — the harness story that ratified this policy.
+The package is intentionally pure so it can run unchanged in CI and on a developer's laptop:
 
-## Runtime constraints (lint-enforced)
+- **No I/O** — never reads files, never touches the network.
+- **No LLM client** — never imports an Anthropic, OpenAI, or LangChain SDK. It builds the prompt and validates the response; *calling* the model is the caller's job.
+- **No environment reads** — pure functions of explicit arguments. Same input → byte-identical output, every time.
 
-The package's `eslint.config.js` rules forbid imports that would compromise its pure-logic posture:
+Runtime dependencies are exactly two, both pure CPU: [`zod`](https://www.npmjs.com/package/zod) (schema validation) and [`picomatch`](https://www.npmjs.com/package/picomatch) (glob matching).
 
-- **No I/O** — no `fs`, `child_process`, `http`, `https`, `node:fs`, etc.
-- **No LLM client** — no `@anthropic-ai/sdk`, `openai`, `@langchain/*`.
-- **No env-var reads** — no `process.env`. Pure functions of explicit arguments.
+## License
 
-Runtime deps: `zod` + `picomatch` (both pure CPU — no I/O, no network, no env). DevDeps: `vitest`, `@types/node`, `typescript`. Adding anything else is a regression.
+[Apache-2.0](https://github.com/Legends-of-Tech/delfini/blob/main/LICENSE)

package/dist/diff-filter.d.ts

@@ -1,5 +1,5 @@
 /** Why a path or hunk was dropped. */
-export type DropReason = 'lockfile' | 'generated' | 'vendored' | 'fixture' | 'whitespace-only' | 'import-only';
+export type DropReason = 'lockfile' | 'generated' | 'vendored' | 'fixture' | 'whitespace-only' | 'import-only' | 'ignored';
 export interface DroppedPath {
     path: string;
     reason: DropReason;
@@ -17,6 +17,25 @@ export interface FilterDiffResult {
     /** Individual hunks dropped from otherwise-kept files. */
     droppedHunks: DroppedHunk[];
 }
+/** Options controlling which filtering passes `filterDiff` applies. */
+export interface FilterDiffOptions {
+    /**
+     * Apply the built-in noise classifiers (lockfile/generated/vendored/fixture
+     * path-level + whitespace-only/import-only hunk-level). Defaults to `true`
+     * so the legacy single-arg call `filterDiff(diff)` is byte-identical to the
+     * pre-options behaviour (the `enableDiffPreFilter` consumer path). Pass
+     * `false` to run an ignore-only pass that leaves all non-ignored files
+     * verbatim.
+     */
+    builtins?: boolean;
+    /**
+     * User `ignore_code_scope` entries (repo-relative; picomatch@4 dialect via
+     * the shared `isFileInDocScope` predicate). A changed file matching any
+     * entry is dropped whole with reason `'ignored'`, classified BEFORE the
+     * built-ins. Empty / omitted → no ignore dropping (observably no-op).
+     */
+    ignorePaths?: string[];
+}
 /**
  * Filter a unified-diff string deterministically.
  *
@@ -28,6 +47,11 @@ export interface FilterDiffResult {
  * not lose surrounding context.
  *
  * Identical input → identical output (NFR46 reproducibility carries forward).
+ *
+ * `options.builtins` (default `true`) gates the built-in noise classifiers;
+ * `options.ignorePaths` adds user `ignore_code_scope` dropping on top. With
+ * the default options (`{ builtins: true, ignorePaths: [] }`) the output is
+ * byte-identical to the legacy single-arg `filterDiff(diff)`.
  */
-export declare function filterDiff(diff: string): FilterDiffResult;
+export declare function filterDiff(diff: string, options?: FilterDiffOptions): FilterDiffResult;
 //# sourceMappingURL=diff-filter.d.ts.map

package/dist/diff-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff-filter.d.ts","sourceRoot":"","sources":["../src/diff-filter.ts"],"names":[],"mappings":"AAsBA,sCAAsC;AACtC,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,WAAW,GACX,UAAU,GACV,SAAS,GACT,iBAAiB,GACjB,aAAa,CAAA;AAEjB,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,UAAU,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,YAAY,EAAE,WAAW,EAAE,CAAA;IAC3B,0DAA0D;IAC1D,YAAY,EAAE,WAAW,EAAE,CAAA;CAC5B;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CA0DzD"}
+{"version":3,"file":"diff-filter.d.ts","sourceRoot":"","sources":["../src/diff-filter.ts"],"names":[],"mappings":"AAgCA,sCAAsC;AACtC,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,WAAW,GACX,UAAU,GACV,SAAS,GACT,iBAAiB,GACjB,aAAa,GAGb,SAAS,CAAA;AAEb,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,UAAU,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,YAAY,EAAE,WAAW,EAAE,CAAA;IAC3B,0DAA0D;IAC1D,YAAY,EAAE,WAAW,EAAE,CAAA;CAC5B;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAgF1F"}

package/dist/diff-filter.js

@@ -8,8 +8,16 @@
 // Pure-logic — no I/O, no clock, no randomness, no new runtime dep. ESLint
 // `no-restricted-imports` on packages/drift-engine/src/**/*.ts forbids fs /
 // child_process / http / https / @anthropic-ai/sdk / openai / @langchain/* /
-// process.env. Path classification uses hand-written predicates — NO
-// `picomatch` (Story Dev Notes §"Path classification predicates").
+// process.env. The BUILT-IN noise classifiers (lockfile/generated/vendored/
+// fixture) use hand-written predicates — NO `picomatch` (Story Dev Notes
+// §"Path classification predicates").
+//
+// ignore_code_scope (user-configurable ignore paths) is the ONE place this
+// module reaches for picomatch — via the shared `isFileInDocScope` predicate
+// (sibling module, same package, no new external dep). User globs MUST use the
+// same picomatch@4 dialect as the CLI config + the Action array-filter so a
+// file the Skill ignores is the file the Action ignores (ADR-2026-06-01
+// dialect parity). The hand-written built-ins above are unrelated and stay.
 //
 // Exposed via `index.ts` (unlike the P3.7.1 relevance internals, which run
 // INSIDE `buildPrompt`). The gate for this filter lives at the CONSUMER —
@@ -19,6 +27,7 @@
 // `@delfini/drift-engine/src/...` imports). The default consumer path never
 // invokes this module, so `buildPrompt` output stays byte-identical and the
 // NFR44 snapshot gate stays green (NFR49(b) parity discipline).
+import { isFileInDocScope } from './doc-scope.js';
 // -- Public entry point ------------------------------------------------------
 /**
  * Filter a unified-diff string deterministically.
@@ -31,8 +40,16 @@
  * not lose surrounding context.
  *
  * Identical input → identical output (NFR46 reproducibility carries forward).
+ *
+ * `options.builtins` (default `true`) gates the built-in noise classifiers;
+ * `options.ignorePaths` adds user `ignore_code_scope` dropping on top. With
+ * the default options (`{ builtins: true, ignorePaths: [] }`) the output is
+ * byte-identical to the legacy single-arg `filterDiff(diff)`.
  */
-export function filterDiff(diff) {
+export function filterDiff(diff, options = {}) {
+    const builtins = options.builtins ?? true;
+    const ignorePaths = options.ignorePaths ?? [];
+    const hasIgnore = ignorePaths.length > 0;
     const droppedPaths = [];
     const droppedHunks = [];
     const files = parseDiffIntoFiles(diff);
@@ -41,6 +58,22 @@ export function filterDiff(diff) {
         keptParts.push(files.preamble);
     }
     for (const file of files.files) {
+        // ignore_code_scope wins over everything — the dev explicitly told Delfini
+        // this code path is out of bounds for drift, so it is dropped whole and
+        // reported as 'ignored' regardless of whether the built-ins would also have
+        // matched it. Shared picomatch@4 predicate → parity with the CLI config and
+        // the Action's array-filter.
+        if (hasIgnore && isFileInDocScope(file.path, ignorePaths)) {
+            droppedPaths.push({ path: file.path, reason: 'ignored' });
+            continue;
+        }
+        // Built-ins off (ignore-only pass): a non-ignored file passes through
+        // verbatim — no path-level or hunk-level noise dropping. Byte-fidelity via
+        // the original slice.
+        if (!builtins) {
+            keptParts.push(file.rawSlice);
+            continue;
+        }
         // Path-level drops — classified first, in priority order. Lockfiles win
         // over generated/vendored/fixture since the canonical lockfile names
         // never overlap those patterns in practice.

package/dist/index.d.ts

@@ -6,6 +6,6 @@ export { normalizeDocScope, validateDocScopeEntry, classifyEntry, isFileInDocSco
 export { filterDiff } from './diff-filter.js';
 export { rankedFillSections } from './relevance.js';
 export type { AnalysisInput, AnalysisResult, DocFile, Contradiction, Addition, ClarifyingQuestion, PRMetadata, Severity, BuildPromptOptions, } from './types.js';
-export type { DropReason, DroppedPath, DroppedHunk, FilterDiffResult, } from './diff-filter.js';
+export type { DropReason, DroppedPath, DroppedHunk, FilterDiffResult, FilterDiffOptions, } from './diff-filter.js';
 export type { DocSection, DroppedSection, RankedFillCandidate, RankedFillResult, } from './relevance.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAI5C,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AAOvB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAS7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEnD,YAAY,EACV,aAAa,EACb,cAAc,EACd,OAAO,EACP,aAAa,EACb,QAAQ,EACR,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,kBAAkB,GACnB,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,GACjB,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EACV,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAI5C,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AAOvB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAS7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEnD,YAAY,EACV,aAAa,EACb,cAAc,EACd,OAAO,EACP,aAAa,EACb,QAAQ,EACR,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,kBAAkB,GACnB,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EACV,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gBAAgB,CAAA"}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@delfini/drift-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Legends-of-Tech/delfini.git",
+    "directory": "packages/drift-engine"
+  },
   "publishConfig": {
     "access": "public"
   },