@gitkraken/conflict-tools 0.2.4-beta.2 → 0.2.4-beta.20

package/CHANGELOG.md

@@ -9,8 +9,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- Reference-integrity detection. `resolveConflicts` now attaches a `StepResult.detection` report listing broken references (symbols that resolved in a pre-merge parent but no longer resolve in the merged result, with provenance), duplicate definitions, and syntax errors in the resolved files. Detection is opt-in via a new `ParserPort` (`ResolverDeps.parser`) that supplies parsing/symbol resolution per surface (tree-sitter, language server); when it is absent, unavailable, or a file's language is unsupported, the report says so rather than implying a clean result. Report-only in this release — no automatic fixing.
-- Auto-merged scope for reference-integrity detection: the detector discovers the merge's incoming/auto-merged set itself (new optional `changedFiles` git-port op; `git diff --name-only base..theirs`, base from `refs.base` or `mergeBase`) and includes it in scope, so dangling references in cleanly-merged files are caught. Scope is capped and reported via `DetectionReport.scope`; an optional `ResolutionContext.touchedFiles` overrides discovery. Adds a `dropped-side` finding when a whole-side take (take-ours/take-theirs/fallback) discards a substantial diff from the other side.
+- `ResolverConfig.maxModelCalls` — an optional global model-call budget for the whole operation. When set and the budget is spent, the opt-in fix phase stops attempting further fixes and leaves the remainder in the findings (so the verdict still reflects the true post-fix state), emitting a new `fix:budget-exhausted` progress event (`{ spent, limit }`). When unset, the fix phase is not budget-limited.
+- `fix:failed` progress event (`{ filePath?, reason }`) — emitted when the opt-in fix phase throws a non-abort error, so a consumer can observe the graceful degradation rather than only seeing the checks flip to `errored`.
+- Cross-file fixes in the fix phase (opt-in `ResolverConfig.fix`). After per-file convergence, a project-tier broken reference (an import/cross-file use whose target stopped resolving) is routed to the refine of its **use-site** file: the finding becomes a fix instruction, and the whole set is re-detected, up to `crossFileMaxIterations` rounds (default 2). Each cross-file fix is a single refine pass plus a mandatory per-file re-validation; the final whole-set detection also re-checks per-file for files a cross-file fix touched. **Limitation:** only use-site files that have an AI resolution are routed — a cross-file break landing on an auto-merged file (no resolution to carry the edit) is reported but not auto-fixed yet (needs a patches channel). The definition side, if broken, arrives as its own finding on its own file. Report-only (fix off) is unchanged.
+- Per-file fix loop (opt-in via `ResolverConfig.fix`, default `false`). When enabled, an AI-resolved (`strategy: 'ai'`) text file that carries error-severity per-file findings is routed back through refine: the findings become fix instructions, the file is re-analyzed after each edit, and the loop repeats until the file is clean, a round makes no progress, or `fixLoopMaxIterations` (default 3) is reached. Whatever it cannot fix stays in the findings, so the verdict reflects the post-fix state. The no-markers invariant holds (a fix that reintroduces markers is discarded). New progress events `fix:started` / `fix:completed`. Report-only (fix off) is unchanged. Deferred for the opt-in fix path: rebase per-step-ref/transient discipline, parser/validator call caching, cross-file fixes, and a full finding-lifecycle model (double-counting is handled here by fingerprint dedup when folding findings into the report).
+- `collectFileFindings` — a per-file detection unit (structural + intra-file broken references + consumer validator issues, all `tier: 'file'`) over already-loaded parent snapshots; the fix loop re-runs it after each edit. `detect()` remains the authoritative whole-set report.
+- Reference-integrity detection. `resolveConflicts` now attaches a `StepResult.detection` report listing broken references (symbols that resolved in a pre-merge parent but no longer resolve in the merged result, with provenance), duplicate definitions, and syntax errors in the resolved files. Detection is opt-in via a new `ParserPort` (`ResolverDeps.parser`) that supplies parsing/symbol resolution per surface (tree-sitter, language server); when it is absent, unavailable, or a file's language is unsupported, the report says so rather than implying a clean result. Detection itself is report-only; fixing is opt-in via the fix phase (above) and off by default.
+- Auto-merged scope for reference-integrity detection: the detector discovers the merge's incoming/auto-merged set itself (new optional `changedFiles` git-port op; `git diff --name-only base..theirs`, base from `refs.base` or `mergeBase`) and includes it in scope, so dangling references in cleanly-merged files are caught. Scope is capped and reported via `DetectionReport.scope`; an optional `ResolutionContext.touchedFiles` overrides discovery. Adds a `dropped-side` finding when the resolver's emergency fallback took one side wholesale and discarded a substantial diff from the other; a deliberate rule/default take is not flagged.
+- `ResolutionContext.detectionRefs` — optional parent tips for reference-integrity detection's before/after comparison, separate from `refs` (which drives the resolver's three-way diff). Detection uses `detectionRefs ?? refs`. Needed when the resolver's refs are the in-flight per-step state (e.g. a rebase) while detection needs the two stable pre-merge branch tips; in a merge they coincide and it can be left unset.
+- Binding-aware broken-reference detection. `ParsedFile` gains an optional `bindings` (names bound at any scope, module-level and nested), and reference-integrity now treats a name as "resolvable before the merge" if a parent resolved it as a reference **or** defined/bound it. This catches a reference broken by removing a nested binding (e.g. a `const` used by a closure elsewhere in the same file): the dangling use was never a resolved reference — because it was locally bound — so the before/after reference diff alone could not see the regression. Backends that only surface top-level `definitions` can omit `bindings`; they simply do not gain the nested-binding case.
+- Operation-level assessment: `buildOperationDigest`/`summarizeOperation` now fold `StepResult.detection` into the rollup. A file with any finding is added to `needsReview` (`reason: 'finding'`) regardless of confidence — even a file with no resolution of its own; an error finding (broken-reference, syntax-error, dropped-side) drives `verdict: 'blocked'`, while a warning finding (duplicate-definition, consumer-validator warnings) drives `needs-review`; `OperationDigest.detectionComplete` reports whether every detection check ran (so empty findings on a skipped check are not read as clean); and a derived `OperationDigest.verdict` (`'clean' | 'needs-review' | 'blocked'`) gives consumers an honest gate signal. `ReviewItem` gains `reason` and optional `findingCategories`, and its `confidence` is now optional.
+
+### Changed
+
+- Reference-integrity findings are now tiered by locality: an intra-file break — a local definition/binding the merge dropped while a use of it remains in the same file (e.g. a `const` used by a closure below) — is a `tier: 'file'` finding; a broken cross-file reference (an import whose target stopped resolving) stays `tier: 'project'`. Previously every `broken-reference` was `'project'`. Classification uses the reference's `target` file when the parser supplies it, else whether the name was a local definition/binding in the parent. This sets up the per-file vs cross-file fix loops.
+- **Breaking**: consumer validation moved to a `Validator` port — `validate(sources: SourceOverlay): Promise<ValidatorFinding[]>` (replaces the per-file `ResolutionVerifier.verify`). It runs post-refine, non-blocking, over an overlay (one file for per-file validation, or the touched set for cross-file); its findings fold into the operation's detection findings and verdict. `Resolution.findings` replaces `Resolution.issues`. `Finding.category` is now an open `string` so a consumer validator can contribute its own categories — the package still emits the well-known `FindingCategory` values. `defaultVerifier` / `VerificationResult` are no longer exported (`checkResidualMarkers` stays internal, the built-in marker gate).
+- **Breaking**: the resolver's in-loop blocking check is now **residual conflict markers only** (built-in, language-agnostic). Consumer validation (the `Validator` port, above) no longer gates the resolve loop or triggers re-resolution — it runs once **after** refine, **non-blocking**, and its findings are folded into the report (advisory). This stops the resolver from burning its step budget on non-marker validation (which was exhausting into a whole-file `take-theirs` fallback), and puts consumer validation in its intended post-refine, report-only role. `ResolverLoopResult` no longer carries `issues`.
+- The per-file fix loop now emits `fix:completed` (iterations 0, remaining 0) even when a file has no findings to fix, so a consumer can distinguish "the fix loop evaluated this file and it was clean" from "the fix loop never reached this file". Previously a clean file returned silently, leaving the two cases indistinguishable in the event stream.
+
+### Fixed
+
+- The opt-in fix phase is now fault-isolated. A parser, validator, or model throw inside the fix phase no longer rejects the whole operation: the resolutions (possibly partially fixed) are kept, both detection checks are reported as `errored` (so the verdict is `needs-review`, never a false `clean`), and the throw is surfaced via `fix:failed`. A user abort still propagates and cancels the operation.
+- `OperationDigest.verdict` can now reach `clean` on a real repository. `detectionComplete` treated `partial-unsupported-language` as "did not run", so any operation whose scope contained a non-code file (package.json, README, lockfiles — always present in a real merge) forced `verdict: 'needs-review'` even with zero findings and full confidence. Since `--fix` gates auto-apply on `verdict === 'clean'`, this made auto-apply effectively unreachable. A check now counts as complete when it ran, including when some scope files were an unsupported language (they carry no references to break); only a check that could not run at all — no parser, no refs, an unreadable parent snapshot, or a thrown parser — leaves detection incomplete.
+- A non-abort error in the refine pass no longer destroys the pre-refine resolution. Previously the refine `catch` rethrew, bubbling to `resolveOne` and degrading a good resolve-stage result into a take-side fallback (confidence 0) — the same class of failure as a throwing validator, one stage later. The pre-refine resolution is now kept, its confidence capped (the enhancement did not complete), and the error reported via `refine:failed`. A user abort still cancels (rethrown past the fallback).
+- A throwing consumer validator no longer destroys a good resolution. The post-refine `validator.validate()` call is now guarded: a validator error is reported via a new `validation:failed` progress event and the resolution is kept intact, instead of bubbling to `resolveOne` and degrading a successful AI resolve into a whole-file take-side fallback (confidence 0) — the exact dropped-side loss the tool guards against. The validator stays advisory.
+- A user abort mid-resolve now cancels the operation instead of degrading into a take-side fallback. `resolveOne` rethrows when `signal.aborted` (covering aborts raised from the resolve loop, refine, or the validator), bypassing the emergency fallback rather than turning a cancellation into a whole-file take-one-side resolution.
+- The refine pass no longer floods its bounded step budget when the model spirals. After a run of consecutive `edit_file_lines` apply errors (a model repeatedly proposing ops that never apply), the pass bails early — keeping whatever edits landed — and emits a new `refine:bailed` progress event, instead of executing failing tool calls until the step budget is exhausted.
+- Reference-integrity detection no longer reads as "clean" when the parent snapshots could not be loaded. A git port that returns empty content for an unreadable parent (e.g. a `showFile` that swallows read errors into `""` instead of throwing) previously produced empty findings with `referenceIntegrity: 'ran'`, masking a total read failure as a clean result. `buildSnapshots` now ignores empty parent content; `DetectionReport.scope` reports `readable` (parents actually loaded) alongside `analyzed` (files in scope); and `referenceIntegrity` reports a new `'skipped-unreadable-source'` status when nothing in scope could be read — which flips `OperationDigest.detectionComplete` to `false` and the verdict to `needs-review` instead of `clean`.
 
 ## [0.2.3] - 2026-07-06
 

package/README.md

@@ -1,6 +1,6 @@
 # @gitkraken/conflict-tools
 
-AI-powered git conflict resolution. Parses conflict markers (including delete-modify conflicts), resolves them with an agentic AI loop that has access to git context (blame, grep, diff, log, show, file content), and writes results back to the working tree.
+AI-powered git conflict resolution. Parses conflict markers (including delete-modify conflicts), resolves them with an agentic AI loop that has access to git context (blame, grep, diff, log, show, file content), refines the result with targeted intra-file edits, then runs deterministic reference-integrity detection over the whole touched set and produces an honest verdict. Results are written back to the working tree by the consumer.
 
 ## What it does
 
@@ -8,9 +8,9 @@ Three entry points, each serving a different consumer need:
 
 - `extractConflict()` — parses conflict markers from a single file and returns a structured representation. Handles both text conflicts (with markers) and delete-modify conflicts (one side deleted, the other modified). No AI, no resolution.
 
-- `resolveConflict()` — takes one `Conflict` and an optional `ResolutionContext`, runs the AI tool-use loop, returns a `Resolution` with resolved content, confidence, and metrics. The single-file workhorse.
+- `resolveConflict()` — takes one `Conflict` and an optional `ResolutionContext`, runs the AI tool-use loop and per-file refine, returns a `Resolution` with resolved content, confidence, and metrics. The single-file workhorse.
 
-- `resolveConflicts() + applyResolutions()` — batch-resolve every currently unmerged file in the working tree, then write and stage results. Supports pattern-based routing: skip files, apply take-ours/take-theirs, or route to AI per glob pattern. The library does NOT orchestrate `git rebase`/`merge`/`cherry-pick` — the consumer drives the operation lifecycle.
+- `resolveConflicts() + applyResolutions()` — batch-resolve every currently unmerged file in the working tree, run set-level detection, then write and stage results. Supports pattern-based routing: skip files, apply take-ours/take-theirs, or route to AI per glob pattern. The library does NOT orchestrate `git rebase`/`merge`/`cherry-pick` — the consumer drives the operation lifecycle.
 
 The library never calls `git` or an AI provider directly. Consumers supply adapters via ports.
 
@@ -20,6 +20,16 @@ The library never calls `git` or an AI provider directly. Consumers supply adapt
 pnpm add @gitkraken/conflict-tools
 ```
 
+## Pipeline
+
+An operation runs in three stages. **Report-only is the default**, and the stage shape is identical whether or not the opt-in fix phase is enabled — the fix phase only adds edit attempts, it does not change the flow.
+
+1. **Resolve** — the agentic AI tool-use loop replaces conflict markers, self-assessing a confidence per marker. The *only* blocking gate is residual conflict markers (checked built-in, language-agnostic): a candidate that still contains markers is rejected and retried. No other check gates this stage — parser, validator, and detection are all downstream and advisory.
+2. **Refine** (per file) — when the resolver returns `followUpInstructions` (targeted edits it could not express as a whole-chunk decision), a second agentic loop applies them via the `edit_file_lines` tool. A refine that reintroduces markers is discarded; a refined file's confidence is capped at 0.9.
+3. **Detection** (set level) — after every file is resolved, deterministic reference-integrity detection runs over the whole touched set: per-file structural checks (syntax errors, duplicate definitions, intra-file broken references) on the resolved *and* the auto-merged/incoming files, plus cross-file broken-reference checks. Report-only — it never mutates state or fails the operation. It produces the `DetectionReport` attached to `StepResult.detection`, which drives the verdict.
+
+The opt-in **fix phase** (`config.fix: true`) sits between refine and the final detection report: it re-detects, routes the error-severity findings back through refine (per-file convergence, then cross-file routing), and only then emits the final report. What it cannot fix stays in the findings, so the verdict always reflects the post-fix state. See [Fix phase](#fix-phase-opt-in).
+
 ## Ports
 
 ### `ConflictGitPort`
@@ -42,6 +52,7 @@ High-level ops the library dispatches through:
 | `showFile(ref, path, opts?)` | Read file content at a specific ref. Supports `startLine`/`endLine` |
 | `unmergedEntries()` | List files git considers unresolved |
 | `mergeBase(a, b)` | Common ancestor between two refs |
+| `changedFiles(from, to)` | Paths changed between two refs (name-only). Used to discover the merge's incoming/auto-merged set for detection |
 | `blame(path, opts?)` | Line-level authorship. Supports `startLine`/`endLine` (maps to `git blame -L`) |
 | `grep(pattern, opts?)` | Content search across the tree. Supports `maxResults` |
 | `diff(from, to, opts?)` | Unified diff between refs, optionally scoped to a path |
@@ -73,29 +84,64 @@ const model: ConflictModelPort = {
 
 The shape of `tools`, `toolCalls`, and `toolResults` follows abstract types (`ToolDefinition`, `ToolCall`, `ToolResult`) so consumers can adapt any SDK. The library does not require streaming or any provider-specific feature.
 
-### `ResolutionVerifier` (optional)
+### `ParserPort` (optional — enables detection)
+
+A **facts-in** port. Given a content overlay, it returns per-file parse facts — definitions, references (each with a `resolved` flag), optional bindings, and syntax errors. The *package* derives findings from those facts; the port itself never classifies anything as a conflict or a break.
+
+```typescript
+import type { ParserPort, SourceOverlay, ParsedFile } from '@gitkraken/conflict-tools';
+
+const parser: ParserPort = {
+    async analyze(sources: SourceOverlay): Promise<ReadonlyMap<string, ParsedFile>> {
+        // tree-sitter (merge-mate) or a language server (GitLens/GKD), overlaying `sources`.
+        // Return one ParsedFile per input path.
+    },
+};
+```
+
+Three properties define the contract:
+
+- **Content-in overlay, no FS access.** `analyze(sources)` sees exactly the `SourceOverlay` contents (a `ReadonlyMap<path, content>`) and never reads the filesystem itself. This is what lets the package hand it pre-merge parent snapshots *and* the post-merge result and diff the two. A tree-sitter backend sees only these files; a language server may resolve against its workspace with these contents overlaid on top.
+- **Language-agnostic.** A file the backend cannot parse comes back with `language: 'unsupported'` and empty facts; the detector skips it (and reports `partial-unsupported-language`) rather than emitting false findings.
+- **Precision-abstracting.** A tree-sitter backend and a language-server backend differ in how completely they resolve references — the port hides that difference behind the same shape.
+
+`ParsedFile`:
+
+| Field | Meaning |
+|---|---|
+| `language` | Backend's language id; `'unsupported'` means "skip this file" |
+| `definitions` | `SymbolDefinition[]` — top-level defs (`name`, `kind?`, 1-indexed `line`) |
+| `references` | `SymbolReference[]` — `name`, `line`, `column?`, `resolved` (did it resolve within the overlay), `target?` |
+| `bindings?` | Optional names bound at *any* scope (module-level and nested). Populating it lets detection catch a reference broken by removing a nested binding. A backend that only surfaces top-level `definitions` may omit it |
+| `syntaxErrors` | `SyntaxIssue[]` — `line`, `message` |
+
+Pass via `deps.parser`. When absent, detection is skipped and the report says so (`skipped-no-parser`) — never a silent clean.
 
-A pluggable post-resolution check. The library ships a `defaultVerifier` that scans the assembled content for residual conflict markers. During the AI loop, a failed verification triggers a retry with feedback — the model gets a chance to self-correct.
+### `Validator` (optional)
+
+The consumer's validation port. Plug in any checks — syntax, real import resolution, types, lint, project rules. It runs **post-refine over an overlay** (one file for per-file validation, or the whole touched set for cross-file) and returns `ValidatorFinding[]`.
 
 ```typescript
-import { defaultVerifier } from '@gitkraken/conflict-tools';
-import type { ResolutionVerifier } from '@gitkraken/conflict-tools';
-
-// Use the built-in (checks for residual <<<<<<< / ======= / >>>>>>>)
-const verifier = defaultVerifier;
-
-// Or provide your own (e.g. run a linter, compile check)
-const custom: ResolutionVerifier = {
-    verify: async (filePath, content) => {
-        const errors = await lint(content);
-        return errors.length === 0
-            ? { valid: true }
-            : { valid: false, feedback: errors.join('\n') };
+import type { Validator, ValidatorFinding } from '@gitkraken/conflict-tools';
+
+const validator: Validator = {
+    async validate(sources) {
+        const findings: ValidatorFinding[] = [];
+        for (const [file, content] of sources) {
+            for (const err of await typecheck(file, content)) {
+                findings.push({ category: 'type-error', severity: 'error', file, line: err.line, message: err.message });
+            }
+        }
+        return findings;
     },
 };
 ```
 
-Pass the verifier via `deps.verifier` to `resolveConflict` or `resolveConflicts`.
+**Advisory, never blocking.** Its findings fold into the operation's detection findings and the verdict; a validator finding never triggers a re-resolve, and a *throwing* validator is caught (reported via `validation:failed`) and the resolution is kept intact. `ValidatorFinding.category` is an open string (e.g. `'type-error'`, `'lint:no-console'`) so consumer categories flow through alongside the package's own `FindingCategory` values.
+
+The one blocking gate — **residual conflict markers** — is *not* this port's job. It is checked built-in and language-agnostic inside the resolve loop. (This was the old `defaultVerifier`; it is now internal. `defaultVerifier`, `ResolutionVerifier`, and `VerificationResult` are no longer exported.)
+
+Pass via `deps.validator` to `resolveConflict` or `resolveConflicts`.
 
 ## Entry points
 
@@ -130,19 +176,25 @@ import { resolveConflict } from '@gitkraken/conflict-tools';
 const resolution = await resolveConflict(conflict, context, {
     model,
     git,
+    validator, // optional — advisory per-file checks
     config: { maxSteps: 15, temperature: 0 },
     onProgress: (event) => console.log(event),
 });
 
 // resolution.content       — resolved file content (markers replaced)
 // resolution.strategy      — 'ai' | 'take-ours' | 'take-theirs' | 'deleted' | 'skipped'
-// resolution.confidence    — 0..1, from the AI's own self-assessment
+// resolution.confidence    — 0..1, from the AI's own self-assessment (capped at 0.9 if refined)
 // resolution.description   — one-or-two sentence rationale, from the AI
+// resolution.findings?     — advisory per-file findings from the validator port (post-refine)
 // resolution.chunks?       — per-marker decisions (for observability and validation)
+// resolution.edits?        — IntraFileEditOp[] applied during refine (absent if refine did not run)
 // resolution.metrics?      — { inputTokens, outputTokens, stepCount, toolCallCount, ... }
+// resolution.rawSignals?   — policy-free measurements for the consumer's own assessment
 ```
 
-`ResolutionContext` carries optional hints the AI can use:
+`resolveConflict` runs stages 1–2 (resolve + refine) for a single file. Set-level detection (stage 3) is only run by the batch entry point, since it needs the whole touched set; use `detect()` directly if you want detection for a single-file flow.
+
+`ResolutionContext` carries optional hints the AI can use, plus the refs detection compares against:
 
 ```typescript
 interface ResolutionContext {
@@ -150,21 +202,25 @@ interface ResolutionContext {
     prDescription?: string;
     previousResolutions?: Resolution[];
     fileNeighbors?: string[];
+    /** Auto-merged files beyond the conflict set. Usually unset — detection discovers this from refs. */
+    touchedFiles?: string[];
     refs?: { ours: string; theirs: string; base?: string };
+    /** Parent tips for detection's before/after comparison, when they differ from `refs`. */
+    detectionRefs?: { ours: string; theirs: string; base?: string };
     threeWayDiff?: { oursDiff: string; theirsDiff: string };
+    /** Whole-file free-text guidance, rendered as a top-level <user-guidance> block. */
+    userGuidance?: string;
     metadata?: Record<string, unknown>;
 }
 ```
 
 When `refs` is provided, the library computes `git diff base..ours -- file` and `git diff base..theirs -- file` automatically and includes both in the prompt. This typically lets the AI resolve without any tool calls. Consumers that already have these diffs cached can pass `threeWayDiff` directly to skip the computation.
 
-### Phase 2 refine pass
-
-After Phase 1 resolves conflict markers, the AI may return `followUpInstructions: string[]` on the resolution — a list of targeted edits it could not express as a whole-chunk decision (for example, re-applying a partial change from the incoming branch). When `followUpInstructions` is non-empty, `resolveConflict` automatically runs a second agentic loop (Phase 2) that applies those edits via the `edit_file_lines` tool.
+`refs` drives the resolver's three-way diff; `detectionRefs` (falling back to `refs`) drives detection's before/after comparison. They differ in a rebase — where `refs` is the in-flight per-step state while detection needs the two stable pre-merge branch tips — and coincide in a plain merge, so `detectionRefs` is usually left unset.
 
-`ResolverConfig.refineMaxSteps?: number` controls how many model turns Phase 2 is allowed. Defaults to 5.
+#### Refine edits
 
-`Resolution.edits?: IntraFileEditOp[]` carries the list of edit operations that were successfully applied during Phase 2. Absent when Phase 2 did not run or all edits were discarded.
+The refine pass (stage 2) applies edits the resolver could not express as whole-chunk decisions — for example, re-applying a partial change from the incoming branch. `ResolverConfig.refineMaxSteps` (default 5) bounds its model turns. `Resolution.edits?: IntraFileEditOp[]` lists the operations that survived (absent when refine did not run or all edits were discarded).
 
 `IntraFileEditOp` is a discriminated union on `kind`:
 
@@ -176,12 +232,14 @@ After Phase 1 resolves conflict markers, the AI may return `followUpInstructions
 ### `resolveConflicts(deps, context?) + applyResolutions(resolutions, deps)` — batch
 
 ```typescript
-import { resolveConflicts, applyResolutions } from '@gitkraken/conflict-tools';
+import { resolveConflicts, applyResolutions, summarizeOperation } from '@gitkraken/conflict-tools';
 
 const step = await resolveConflicts(
     {
         model,
         git,
+        parser,     // optional — supply to enable set-level detection (stage 3)
+        validator,  // optional — advisory per-file checks
         config: {
             rules: [
                 { match: ['*.lock', 'pnpm-lock.yaml'], strategy: 'take-theirs' },
@@ -200,8 +258,13 @@ const step = await resolveConflicts(
 // step.resolutions[]       — successful resolutions
 // step.errors[]            — { filePath, error } for files that failed (no fallback or AI exhausted)
 // step.skipped?[]          — { filePath, reason } for files that were excluded or had no markers
+// step.detection?          — DetectionReport over the whole touched set (present when a parser was supplied)
 
-await applyResolutions(step.resolutions, { git });
+// Gate on the verdict, not on raw confidence — see below.
+const { digest } = await summarizeOperation(step);
+if (digest.verdict === 'clean') {
+    await applyResolutions(step.resolutions, { git });
+}
 // Resolutions are written via writeFile, checkoutFile, or removeFile and staged.
 ```
 
@@ -221,7 +284,117 @@ Available strategies for rules and `defaultStrategy`:
 | `'deleted'` | Remove the file entirely |
 | `'skip'` | Skip the file (no resolution produced) |
 
-The function inspects the working tree once (via `unmergedEntries`), processes each conflict sequentially, and returns. It does not call `git rebase --continue` or any other operation command — that is the consumer's job.
+The function inspects the working tree once (via `unmergedEntries`), processes each conflict sequentially, runs detection over the touched set, and returns. It does not call `git rebase --continue` or any other operation command — that is the consumer's job.
+
+## Detection & verdict
+
+### `detect(resolutions, context, deps)`
+
+Deterministic, report-only post-resolution detection. It never mutates state or fails the operation. `resolveConflicts` calls it for you and attaches the result to `StepResult.detection`; call it directly for a single-file or custom flow.
+
+```typescript
+import { detect } from '@gitkraken/conflict-tools';
+
+const report = await detect(step.resolutions, { refs }, { git, parser });
+```
+
+`DetectDeps` is `{ git; parser?; signal? }`. It flags:
+
+- references that resolved in a pre-merge parent (ours/theirs) but no longer resolve in the merged result (`broken-reference`, with `provenance`),
+- duplicate definitions and syntax errors in the resolved files (`duplicate-definition`, `syntax-error`),
+- the resolver's emergency fallback taking one side wholesale and discarding a substantial diff (`dropped-side`).
+
+The scope includes the resolved files *and* the merge's auto-merged/incoming set (discovered from `refs` via `changedFiles`/`mergeBase`, or overridden by `context.touchedFiles`), so a dangling reference in a cleanly-merged file is still caught.
+
+`DetectionReport`:
+
+```typescript
+interface DetectionReport {
+    findings: Finding[];
+    checks: { referenceIntegrity: CheckStatus; structural: CheckStatus };
+    /** Honest coverage — present only when the reference check ran. */
+    scope?: { analyzed: number; readable: number; truncated: boolean };
+}
+```
+
+`Finding`:
+
+| Field | Meaning |
+|---|---|
+| `category` | Open string. The package emits `FindingCategory`; a consumer validator may add its own |
+| `severity` | `'error'` \| `'warning'` |
+| `tier` | `'file'` (intra-file) or `'project'` (cross-file) — the fix phase routes each tier differently |
+| `location` | `{ file; line; symbol? }` |
+| `provenance?` | For `broken-reference`: the pre-merge side (`'ours'`/`'theirs'`) that still resolved it, and where |
+| `message` | Human-readable description |
+
+`FindingCategory` (the well-known values the package itself emits):
+
+| Category | Meaning |
+|---|---|
+| `broken-reference` | A symbol resolved in a pre-merge parent but no longer resolves in the merged result |
+| `duplicate-definition` | The same symbol is defined twice in a resolved file (advisory `warning` — the detector cannot tell a genuine redefinition from legal overloads / declaration merging) |
+| `syntax-error` | The parser reported a syntax error in a resolved file |
+| `dropped-side` | The resolver's emergency fallback took one side wholesale, discarding a substantial diff (a deliberate rule/default take is not flagged) |
+
+`CheckStatus` tells "ran, clean" apart from "did not run" — so an empty `findings` array is never mistaken for a clean result:
+
+| Status | Meaning |
+|---|---|
+| `ran` | The check ran to completion |
+| `skipped-no-parser` | No `ParserPort` supplied |
+| `skipped-no-refs` | No refs, so the before/after comparison was impossible (structural checks still ran) |
+| `skipped-unreadable-source` | Refs were present but the parent snapshots came back empty (unreadable source) |
+| `partial-unsupported-language` | The check ran, but some files in scope were an unsupported language |
+| `errored` | The parser was present but threw |
+
+### `summarizeOperation` / `buildOperationDigest`
+
+`buildOperationDigest(result, reviewThreshold?)` is a pure, model-free rollup of a `StepResult` that folds in `detection`. `summarizeOperation(result, opts?)` returns `{ digest, prose?, usage? }` — always the digest, plus a prose narrative when `opts.model` is supplied.
+
+```typescript
+import { buildOperationDigest } from '@gitkraken/conflict-tools';
+
+const digest = buildOperationDigest(step);
+// digest.verdict            — 'clean' | 'needs-review' | 'blocked'
+// digest.detectionComplete  — did every detection check run to completion
+// digest.findingCount       — total detection findings
+// digest.needsReview        — ReviewItem[] (findings first, then lowest confidence first)
+// digest.minConfidence      — lowest file confidence, or null
+// digest.byStrategy         — resolution count per strategy
+```
+
+`OperationVerdict`:
+
+- `blocked` — at least one error-severity finding exists (the build is known-broken).
+- `needs-review` — confidence is low, detection did not fully run, a resolution errored, or a warning finding exists.
+- `clean` — none of the above.
+
+**Gate auto-apply on the verdict, not on confidence.** A refined or fixed file has its confidence capped at 0.9 — so a "confidence must be 1.0" gate would reject exactly the files the tool improved. `verdict === 'clean'` is the honest signal. And an *absent* verdict must NOT be read as clean: if you never ran detection (no parser) or never summarized, `detectionComplete` is `false` and empty findings mean "we didn't look," not "nothing's wrong." Only `verdict === 'clean'` is clean.
+
+A `ReviewItem` distinguishes a low-confidence flag from a finding: `reason: 'low-confidence' | 'finding'`, with `confidence?` (absent for a file flagged purely by a finding, e.g. an auto-merged file with no resolution of its own) and `findingCategories?` (present when `reason` is `'finding'`).
+
+## Fix phase (opt-in)
+
+By default the pipeline is **report-only**: detection findings land in `StepResult.detection` and the verdict, and the consumer decides what to do. Set `config.fix: true` to have the library attempt to fix error-severity findings before emitting the final report. The pipeline shape is identical in both modes — the fix phase only inserts edit attempts between refine and the final detection.
+
+When enabled:
+
+- **Per-file convergence** — an AI-resolved (`strategy: 'ai'`) text file carrying error-severity per-file findings is routed back through refine; the file is re-analyzed after each edit and the loop repeats until it is clean, a round makes no progress, or `fixLoopMaxIterations` (default 3) is reached.
+- **Cross-file routing** — a `tier: 'project'` broken reference (an import/cross-file use whose target stopped resolving) is routed to the refine of its *use-site* file, and the whole set is re-detected, up to `crossFileMaxIterations` (default 2) rounds. Only use-site files that have an AI resolution are routed; a break landing on an auto-merged file (no resolution to carry the edit) is reported but not auto-fixed.
+
+Whatever the fix phase cannot fix stays in the findings, so the verdict always reflects the post-fix state. The no-markers invariant holds throughout: a fix that reintroduces conflict markers is discarded rather than written.
+
+`ResolverConfig` fix-phase fields:
+
+| Field | Default | Effect |
+|---|---|---|
+| `fix` | `false` | Opt in to the fix phase. Off → report-only |
+| `fixLoopMaxIterations` | `3` | Max per-file fix iterations (refine → re-detect the file) |
+| `crossFileMaxIterations` | `2` | Max cross-file fix rounds (route project-level breaks → re-detect the set) |
+| `maxModelCalls` | unset | Global model-call budget for the whole operation. When set and the budget is spent, the fix phase stops attempting further fixes and leaves the remainder in the findings, emitting `fix:budget-exhausted`. When unset, the fix phase is not budget-limited |
+
+The fix phase is **fault-isolated**: a parser, validator, or model throw inside it does not reject the whole operation. The resolutions computed so far (possibly partially fixed, since the fix phase mutates them as it goes) are kept, both detection checks are reported as `errored`, and a `fix:failed` event is emitted (a user abort still propagates and cancels the operation).
 
 ## Consumer examples
 
@@ -241,8 +414,9 @@ if (conflict) {
 ### GitLens / GKD — batch "resolve all" (user-driven)
 
 ```typescript
-const step = await resolveConflicts({ git, model, onProgress: webview.post });
-const approved = await reviewDialog(step.resolutions);
+const step = await resolveConflicts({ git, model, parser, onProgress: webview.post }, { refs });
+const { digest } = await summarizeOperation(step);
+const approved = await reviewDialog(step.resolutions, step.detection, digest.verdict);
 await applyResolutions(approved, { git });
 // User clicks "continue rebase" themselves.
 ```
@@ -256,13 +430,18 @@ for (const commit of commits) {
     if (result.exitCode === 0) continue;
 
     const step = await resolveConflicts({
-        git, model,
+        git, model, parser,
         config: {
             rules: [{ match: '*.lock', strategy: 'take-theirs' }],
             fallbackStrategy: 'take-ours',
+            fix: true, // attempt to fix detected breaks before reporting
         },
         onProgress: emit,
-    });
+    }, { refs });
+
+    const { digest } = await summarizeOperation(step);
+    if (digest.verdict === 'blocked') { await escalateToHuman(step); break; }
+
     await applyResolutions(step.resolutions, { git });
     await git.exec(['rebase', '--continue']);
 }
@@ -282,27 +461,34 @@ score(resolution, goldenFile);
 
 | Event | When |
 |---|---|
-| `conflict:found` | A conflict file has been parsed |
+| `conflict:found` | A conflict file has been parsed (`conflictType`, `markerCount`) |
 | `conflict:excluded` | A file was skipped by a rule with `strategy: 'skip'` |
-| `conflict:skipped` | A file had no conflict markers and no delete-modify reason |
-| `resolution:applied` | A resolution was produced for a file |
-| `resolution:fallback` | AI failed; fallback strategy applied |
-| `resolution:failed` | AI failed and no fallback configured |
-| `resolver:tool-call` | The AI invoked a tool. Includes `reason` (why the AI called it) |
-| `resolver:step-usage` | Token usage for one model call |
-| `resolver:completed` | The resolver finished a single file |
-| `resolver:response` | Phase 1 produced its final response |
-| `resolver:tool-result` | A Phase 1 tool returned content |
-| `refine:started` | Phase 2 has begun |
-| `refine:skipped` | Phase 2 was not run (no follow-ups) |
-| `refine:tool-call` | Phase 2 model invoked `edit_file_lines` |
-| `refine:tool-result` | Phase 2 tool returned feedback |
-| `refine:final-text` | Phase 2 model emitted final description |
-| `refine:completed` | Phase 2 finished successfully (includes `appliedCount`) |
-| `refine:failed` | Phase 2 threw before completing |
-| `edit:discarded` | An edit batch was rejected (introduced markers) |
-
-Note: `refine:tool-result.appliedCount` reports edits applied to an in-progress buffer per turn. The final disposition is signaled by `refine:completed` / `edit:discarded` / `refine:failed` — only edits that survive residual-marker validation appear in `Resolution.edits`.
+| `conflict:skipped` | A file had no conflict markers and no delete-modify reason (`reason`, `entryReason?`) |
+| `resolution:applied` | A resolution was produced for a file (`strategy`, `confidence?`, `description?`) |
+| `resolution:fallback` | AI failed; fallback strategy applied (`error`, `cause?`) |
+| `resolution:failed` | AI failed and no fallback configured (`error`) |
+| `resolver:tool-call` | The AI invoked a tool during resolve (`tool`, `args`, `stepNumber`, `reason?`) |
+| `resolver:step-usage` | Token usage for one resolve model call (`stepNumber`, `usage`) |
+| `resolver:completed` | The resolver finished a single file (`stepCount`) |
+| `resolver:response` | The resolve stage produced its final structured response (`chunks`, `confidence`, `description`, `strategy?`, `followUpInstructions?`) |
+| `resolver:tool-result` | A resolve-stage tool returned content (`tool`, `stepNumber`, `content`) |
+| `refine:started` | The refine pass has begun |
+| `refine:skipped` | Refine was not run (`reason`, e.g. no follow-ups) |
+| `refine:tool-call` | Refine model invoked `edit_file_lines` (`stepNumber`, `ops`) |
+| `refine:tool-result` | A refine tool returned feedback (`stepNumber`, `appliedCount`, `isError`, `feedback`) |
+| `refine:final-text` | Refine model emitted its final description (`text`) |
+| `refine:completed` | Refine finished successfully (`appliedCount`) |
+| `refine:failed` | Refine threw before completing (`reason`) |
+| `refine:bailed` | Refine bailed early after consecutive apply errors, keeping edits that landed (`reason`) |
+| `refine:discarded` | A refine/fix edit batch was rejected because it reintroduced conflict markers (`reason`) |
+| `refine:touched-user-region` | Refine modified a user-resolved marker region (`markerIndexes`) |
+| `fix:started` | The fix loop began fixing a file (`findingCount`) |
+| `fix:completed` | The fix loop finished evaluating a file (`iterations`, `remaining`) — emitted even for a clean file (iterations 0, remaining 0) |
+| `fix:failed` | The opt-in fix phase threw a non-abort error (`filePath?`, `reason`); the operation degrades gracefully — the resolutions (possibly partially fixed) are kept and both checks are reported as `errored` |
+| `fix:budget-exhausted` | The global `maxModelCalls` budget was spent (`spent`, `limit`); the fix phase stopped and left the remainder in findings |
+| `validation:failed` | The consumer validator threw; reported and swallowed, resolution kept (`reason`) |
+
+Note: `refine:tool-result.appliedCount` reports edits applied to an in-progress buffer per turn. The final disposition is signaled by `refine:completed` / `refine:discarded` / `refine:failed` — only edits that survive residual-marker validation appear in `Resolution.edits`.
 
 Operation-level events (rebase started, step completed, etc.) are the consumer's responsibility — the library has no opinion about the surrounding workflow.
 
@@ -328,7 +514,7 @@ try {
 }
 ```
 
-In the batch entry point, errors that have a configured fallback do not throw — they are downgraded to `resolution:fallback` events, and the resulting resolutions appear in `step.resolutions`. Errors without a fallback land in `step.errors` and the loop continues with the next file.
+In the batch entry point, errors that have a configured fallback do not throw — they are downgraded to `resolution:fallback` events, and the resulting resolutions appear in `step.resolutions`. Errors without a fallback land in `step.errors` and the loop continues with the next file. The advisory stages (refine, validator, detection, fix phase) are fault-isolated — a non-abort throw there is reported and swallowed rather than destroying a good resolution. A user abort (`signal.aborted`) always propagates and cancels the operation.
 
 ## Semver policy
 

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { AIError, AIErrorCode } from "./errors/ai.js";
 import { ConflictError, ConflictErrorCode } from "./errors/conflict.js";
 import { BlameOptions, ConflictDiffOptions, ConflictGitOps, ConflictGitPort, ConflictGitPortMissingOpError, GrepOptions, LogOptions, OpOptions, ShowFileOptions, ShowOptions, UnmergedEntry, UnmergedReason } from "./ports/git.js";
+import { CheckStatus, DetectionReport, Finding, FindingCategory, FindingTier } from "./types/findings.js";
 import { IntraFileEditOp } from "./types/hints.js";
-import { Issue } from "./types/issue.js";
 import { DiffStats, Resolution, ResolutionContext, ResolutionMetrics, ResolutionRawSignals, ResolutionRefs, ResolutionStrategy, ResolvedChunk, ThreeWayDiff } from "./types/resolution.js";
 import { Conflict, ConflictMarker, ConflictMarkerUserInput, ConflictType } from "./types/conflict.js";
 import { extractConflict } from "./extraction/extract.js";
@@ -10,8 +10,7 @@ import { checkoutFile, removeFile, show } from "./git/port-dispatch.js";
 import { ToolCall, ToolDefinition, ToolResult } from "./types/tool.js";
 import { ConflictModelMessage, ConflictModelParams, ConflictModelPort, ConflictModelResult, ResolverConfig } from "./ports/model.js";
 import { ParsedFile, ParserPort, SourceOverlay, SymbolDefinition, SymbolReference, SyntaxIssue } from "./ports/parser.js";
-import { ResolutionVerifier, VerificationResult, defaultVerifier } from "./ports/verify.js";
-import { CheckStatus, DetectionReport, Finding, FindingCategory, FindingTier } from "./types/findings.js";
+import { Validator, ValidatorFinding } from "./ports/verify.js";
 import { DetectDeps, detect } from "./reference-integrity/detect.js";
 import { createResolution } from "./resolution/create-resolution.js";
 import { takeOurs, takeTheirs } from "./resolution/take-strategy.js";
@@ -20,6 +19,6 @@ import { ConflictProgressEvent } from "./types/events.js";
 import { resolveConflict } from "./resolver/resolve-conflict.js";
 import { FileRule, StepConfig, StepResult } from "./types/step.js";
 import { resolveConflicts } from "./resolver/resolve-conflicts.js";
-import { OperationDigest, OperationSummary, ReviewItem } from "./types/summary.js";
+import { OperationDigest, OperationSummary, OperationVerdict, ReviewItem } from "./types/summary.js";
 import { SummarizeOperationOptions, buildOperationDigest, summarizeOperation } from "./resolver/summarize-operation.js";
-export { AIError, type AIErrorCode, type BlameOptions, type CheckStatus, type Conflict, type ConflictDiffOptions, ConflictError, type ConflictErrorCode, type ConflictGitOps, type ConflictGitPort, ConflictGitPortMissingOpError, type ConflictMarker, type ConflictMarkerUserInput, type ConflictModelMessage, type ConflictModelParams, type ConflictModelPort, type ConflictModelResult, type ConflictProgressEvent, type ConflictType, type DetectDeps, type DetectionReport, type DiffStats, type FileRule, type Finding, type FindingCategory, type FindingTier, type GrepOptions, type IntraFileEditOp, type Issue, type LogOptions, type OpOptions, type OperationDigest, type OperationSummary, type ParsedFile, type ParserPort, type Resolution, type ResolutionContext, type ResolutionMetrics, type ResolutionRawSignals, type ResolutionRefs, type ResolutionStrategy, type ResolutionVerifier, type ResolvedChunk, type ResolverConfig, type ReviewItem, type ShowFileOptions, type ShowOptions, type SourceOverlay, type StepConfig, type StepResult, type SummarizeOperationOptions, type SymbolDefinition, type SymbolReference, type SyntaxIssue, type ThreeWayDiff, type ToolCall, type ToolDefinition, type ToolResult, type UnmergedEntry, type UnmergedReason, type VerificationResult, applyResolutions, buildOperationDigest, checkoutFile, createResolution, defaultVerifier, detect, extractConflict, removeFile, resolveConflict, resolveConflicts, show, summarizeOperation, takeOurs, takeTheirs };
+export { AIError, type AIErrorCode, type BlameOptions, type CheckStatus, type Conflict, type ConflictDiffOptions, ConflictError, type ConflictErrorCode, type ConflictGitOps, type ConflictGitPort, ConflictGitPortMissingOpError, type ConflictMarker, type ConflictMarkerUserInput, type ConflictModelMessage, type ConflictModelParams, type ConflictModelPort, type ConflictModelResult, type ConflictProgressEvent, type ConflictType, type DetectDeps, type DetectionReport, type DiffStats, type FileRule, type Finding, type FindingCategory, type FindingTier, type GrepOptions, type IntraFileEditOp, type LogOptions, type OpOptions, type OperationDigest, type OperationSummary, type OperationVerdict, type ParsedFile, type ParserPort, type Resolution, type ResolutionContext, type ResolutionMetrics, type ResolutionRawSignals, type ResolutionRefs, type ResolutionStrategy, type ResolvedChunk, type ResolverConfig, type ReviewItem, type ShowFileOptions, type ShowOptions, type SourceOverlay, type StepConfig, type StepResult, type SummarizeOperationOptions, type SymbolDefinition, type SymbolReference, type SyntaxIssue, type ThreeWayDiff, type ToolCall, type ToolDefinition, type ToolResult, type UnmergedEntry, type UnmergedReason, type Validator, type ValidatorFinding, applyResolutions, buildOperationDigest, checkoutFile, createResolution, detect, extractConflict, removeFile, resolveConflict, resolveConflicts, show, summarizeOperation, takeOurs, takeTheirs };

package/dist/index.js

@@ -1 +1 @@
-import{AIError as e}from"./errors/ai.js";import{ConflictError as t}from"./errors/conflict.js";import{ConflictGitPortMissingOpError as n}from"./ports/git.js";import{checkoutFile as r,removeFile as i,show as a}from"./git/port-dispatch.js";import{extractConflict as o}from"./extraction/extract.js";import{defaultVerifier as s}from"./ports/verify.js";import{detect as c}from"./reference-integrity/detect.js";import{createResolution as l}from"./resolution/create-resolution.js";import{takeOurs as u,takeTheirs as d}from"./resolution/take-strategy.js";import{applyResolutions as f}from"./resolver/apply-resolutions.js";import{resolveConflict as p}from"./resolver/resolve-conflict.js";import{resolveConflicts as m}from"./resolver/resolve-conflicts.js";import{buildOperationDigest as h,summarizeOperation as g}from"./resolver/summarize-operation.js";export{e as AIError,t as ConflictError,n as ConflictGitPortMissingOpError,f as applyResolutions,h as buildOperationDigest,r as checkoutFile,l as createResolution,s as defaultVerifier,c as detect,o as extractConflict,i as removeFile,p as resolveConflict,m as resolveConflicts,a as show,g as summarizeOperation,u as takeOurs,d as takeTheirs};
+import{AIError as e}from"./errors/ai.js";import{ConflictError as t}from"./errors/conflict.js";import{ConflictGitPortMissingOpError as n}from"./ports/git.js";import{checkoutFile as r,removeFile as i,show as a}from"./git/port-dispatch.js";import{extractConflict as o}from"./extraction/extract.js";import{detect as s}from"./reference-integrity/detect.js";import{createResolution as c}from"./resolution/create-resolution.js";import{takeOurs as l,takeTheirs as u}from"./resolution/take-strategy.js";import{applyResolutions as d}from"./resolver/apply-resolutions.js";import{resolveConflict as f}from"./resolver/resolve-conflict.js";import{resolveConflicts as p}from"./resolver/resolve-conflicts.js";import{buildOperationDigest as m,summarizeOperation as h}from"./resolver/summarize-operation.js";export{e as AIError,t as ConflictError,n as ConflictGitPortMissingOpError,d as applyResolutions,m as buildOperationDigest,r as checkoutFile,c as createResolution,s as detect,o as extractConflict,i as removeFile,f as resolveConflict,p as resolveConflicts,a as show,h as summarizeOperation,l as takeOurs,u as takeTheirs};

package/dist/ports/model.d.ts

@@ -35,6 +35,13 @@ interface ResolverConfig {
   maxSteps?: number;
   temperature?: number;
   refineMaxSteps?: number;
+  /** Global cap on `model.generate` calls for the whole operation (resolve + refine + fix). Default
+   *  `undefined` = unlimited. Primarily a backstop for the fix phase's multiplicative worst case
+   *  (files × fixLoopMaxIterations + crossFileMaxIterations × routable calls). When spent, the fix
+   *  phase stops attempting further fixes and leaves the remainder in findings — it never aborts the
+   *  operation. The resolve loop is not gated by this (it is already bounded by `maxSteps`); its calls
+   *  still count toward the cap. */
+  maxModelCalls?: number;
 }
 //#endregion
 export { ConflictModelMessage, ConflictModelParams, ConflictModelPort, ConflictModelResult, ResolverConfig };

package/dist/ports/parser.d.ts

@@ -32,6 +32,12 @@ interface ParsedFile {
   language: string;
   definitions: SymbolDefinition[];
   references: SymbolReference[];
+  /** Names bound anywhere in the file, at any scope (module-level and nested). Optional: a backend that
+   *  only surfaces top-level `definitions` may omit it. Populating it lets the detector catch a
+   *  reference broken by removing a *nested* binding — a use satisfied by a local binding is never
+   *  itself reported as a resolved reference, so without the binding as its "before" the before/after
+   *  diff has no transition to flag. */
+  bindings?: SymbolDefinition[];
   syntaxErrors: SyntaxIssue[];
 }
 /**
@@ -43,9 +49,9 @@ interface ParserPort {
   /**
    * Parse and resolve every file in `sources`, treating those contents as authoritative for their
    * paths. Returns one {@link ParsedFile} per input path. Works only from the provided content — it
-   * never reads the filesystem itself.
+   * never reads the filesystem itself. `signal`, when provided, should abort an in-flight analysis.
    */
-  analyze(sources: SourceOverlay): Promise<ReadonlyMap<string, ParsedFile>>;
+  analyze(sources: SourceOverlay, signal?: AbortSignal): Promise<ReadonlyMap<string, ParsedFile>>;
 }
 //#endregion
 export { ParsedFile, ParserPort, SourceOverlay, SymbolDefinition, SymbolReference, SyntaxIssue };

package/dist/ports/verify.d.ts

@@ -1,3 +1,4 @@
+import { SourceOverlay } from "./parser.js";
 import { Issue } from "../types/issue.js";
 
 //#region src/ports/verify.d.ts
@@ -5,10 +6,25 @@ interface VerificationResult {
   valid: boolean;
   issues?: Issue[];
 }
-interface ResolutionVerifier {
-  verify(filePath: string, content: string): Promise<VerificationResult>;
+interface ValidatorFinding {
+  /** Open category string set by the consumer (e.g. `'type-error'`, `'lint:no-console'`). */
+  category: string;
+  severity: 'error' | 'warning';
+  file: string;
+  /** 1-indexed. */
+  line?: number;
+  message: string;
+}
+/**
+ * The consumer's validation port (RFC stages 5/7). Plug in any checks — syntax, real import
+ * resolution, types, lint, project rules. **Non-blocking**: runs post-refine over an overlay (one file
+ * for per-file validation, or the whole touched set for cross-file); its findings are advisory (folded
+ * into the operation's findings and verdict), never a re-resolve. The only blocking gate is residual
+ * conflict markers, checked built-in by the resolver ({@link checkResidualMarkers}) — not this port.
+ */
+interface Validator {
+  validate(sources: SourceOverlay, signal?: AbortSignal): Promise<ValidatorFinding[]>;
 }
 declare function checkResidualMarkers(_filePath: string, content: string): VerificationResult;
-declare const defaultVerifier: ResolutionVerifier;
 //#endregion
-export { ResolutionVerifier, VerificationResult, checkResidualMarkers, defaultVerifier };
+export { Validator, ValidatorFinding, VerificationResult, checkResidualMarkers };

package/dist/ports/verify.js

@@ -1,2 +1,2 @@
 const e=[/^<{7}(\s|$)/,/^\|{7}(\s|$)/,/^={7}(\s|$)/,/^>{7}(\s|$)/];function t(t,n){let r=n.split(`
-`),i=[];for(let t=0;t<r.length;t++){let n=r[t]??``;for(let r of e)if(r.test(n)){i.push(t+1);break}}return i.length===0?{valid:!0}:{valid:!1,issues:[{severity:`error`,message:`Residual conflict markers found at line(s) ${i.join(`, `)}.`}]}}const n={async verify(e,n){return t(e,n)}};export{t as checkResidualMarkers,n as defaultVerifier};
+`),i=[];for(let t=0;t<r.length;t++){let n=r[t]??``;for(let r of e)if(r.test(n)){i.push(t+1);break}}return i.length===0?{valid:!0}:{valid:!1,issues:[{severity:`error`,message:`Residual conflict markers found at line(s) ${i.join(`, `)}.`}]}}export{t as checkResidualMarkers};

package/dist/reference-integrity/detect.d.ts

@@ -1,7 +1,8 @@
 import { ConflictGitPort } from "../ports/git.js";
+import { DetectionReport, Finding } from "../types/findings.js";
 import { Resolution, ResolutionContext } from "../types/resolution.js";
 import { ParserPort } from "../ports/parser.js";
-import { DetectionReport } from "../types/findings.js";
+import { Validator } from "../ports/verify.js";
 
 //#region src/reference-integrity/detect.d.ts
 interface DetectDeps {
@@ -17,5 +18,19 @@ interface DetectDeps {
  * parser is supplied, or refs are missing, the report says so instead of implying a clean result.
  */
 declare function detect(resolutions: Resolution[], context: ResolutionContext, deps: DetectDeps): Promise<DetectionReport>;
+interface FileFindingsDeps {
+  parser: ParserPort;
+  validator?: Validator;
+  signal?: AbortSignal;
+}
+/**
+ * Per-file findings for one file's current content, compared against its pre-merge parents: structural
+ * (syntax/duplicate) + intra-file broken references (a local definition/binding the merge dropped while
+ * a use of it remains in the same file) + the consumer validator's per-file issues. All `tier: 'file'`.
+ * Cross-file references need the full set and are not computed here — `detect()` remains the
+ * authoritative whole-set report. This is the lightweight unit the per-file fix loop re-runs after each
+ * edit, over already-loaded parent snapshots (no git reads, no incoming-set discovery).
+ */
+declare function collectFileFindings(file: string, oursContent: string | undefined, theirsContent: string | undefined, resultContent: string, deps: FileFindingsDeps): Promise<Finding[]>;
 //#endregion
-export { DetectDeps, detect };
+export { DetectDeps, FileFindingsDeps, collectFileFindings, detect };

package/dist/reference-integrity/detect.js

@@ -1,3 +1,3 @@
-import{buildSnapshots as e}from"./snapshot.js";async function t(t,r,o){let c=o.parser;if(!c)return{findings:[],checks:{referenceIntegrity:`skipped-no-parser`,structural:`skipped-no-parser`}};try{let l=r.refs?await e(t,r,o):null;if(l){let[e,r,o]=await Promise.all([c.analyze(l.ours),c.analyze(l.theirs),c.analyze(l.result)]);return{findings:[...n(e,r,o),...i(o),...a(t,l)],checks:{referenceIntegrity:s([e,r,o])?`partial-unsupported-language`:`ran`,structural:s([o])?`partial-unsupported-language`:`ran`},scope:{analyzed:l.analyzed,truncated:l.truncated}}}let u=new Map(t.map(e=>[e.filePath,e.content])),d=await c.analyze(u);return{findings:i(d),checks:{referenceIntegrity:`skipped-no-refs`,structural:s([d])?`partial-unsupported-language`:`ran`}}}catch{return{findings:[],checks:{referenceIntegrity:`errored`,structural:`errored`}}}}function n(e,t,n){let i=new Map;r(e,`ours`,i),r(t,`theirs`,i);let a=[];for(let[e,t]of n)for(let n of t.references){if(n.resolved)continue;let t=i.get(c(e,n.name));t&&a.push({category:`broken-reference`,severity:`error`,tier:`project`,location:{file:e,line:n.line,symbol:n.name},provenance:t,message:`Reference "${n.name}" resolved before the merge (on ${t.side}) but no longer resolves.`})}return a}function r(e,t,n){for(let[r,i]of e)for(let e of i.references){if(!e.resolved)continue;let i=c(r,e.name);n.has(i)||n.set(i,{side:t,line:e.line})}}function i(e){let t=[];for(let[n,r]of e){let e=new Map;for(let i of r.definitions){let r=e.get(i.name);r==null?e.set(i.name,i.line):t.push({category:`duplicate-definition`,severity:`error`,tier:`file`,location:{file:n,line:i.line,symbol:i.name},message:`Duplicate definition of "${i.name}" (also defined at line ${r}).`})}for(let e of r.syntaxErrors)t.push({category:`syntax-error`,severity:`error`,tier:`file`,location:{file:n,line:e.line},message:e.message})}return t}function a(e,t){let n=[];for(let r of e){let e=r.strategy===`take-ours`?`theirs`:r.strategy===`take-theirs`?`ours`:null;if(!e)continue;let i=(e===`ours`?t.ours:t.theirs).get(r.filePath);if(i==null)continue;let a=o(i,r.content);a<20||n.push({category:`dropped-side`,severity:`error`,tier:`file`,location:{file:r.filePath,line:1},message:`Resolution took "${r.strategy}" wholesale, discarding ~${a} line(s) of the ${e} side.`})}return n}function o(e,t){let n=new Set(t.split(`
+import{buildSnapshots as e}from"./snapshot.js";async function t(t,n,i){let s=i.parser;if(!s)return{findings:[],checks:{referenceIntegrity:`skipped-no-parser`,structural:`skipped-no-parser`}};try{let l=n.detectionRefs??n.refs?await e(t,n,i):null;if(l){let[e,n,u]=await Promise.all([s.analyze(l.ours,i.signal),s.analyze(l.theirs,i.signal),s.analyze(l.result,i.signal)]),d=l.analyzed>0&&l.readable===0?`skipped-unreadable-source`:c([e,n,u])?`partial-unsupported-language`:`ran`;return{findings:[...r(e,n,u),...a(u),...o(t,l)],checks:{referenceIntegrity:d,structural:c([u])?`partial-unsupported-language`:`ran`},scope:{analyzed:l.analyzed,readable:l.readable,truncated:l.truncated}}}let u=new Map(t.map(e=>[e.filePath,e.content])),d=await s.analyze(u,i.signal);return{findings:a(d),checks:{referenceIntegrity:`skipped-no-refs`,structural:c([d])?`partial-unsupported-language`:`ran`}}}catch{return{findings:[],checks:{referenceIntegrity:`errored`,structural:`errored`}}}}async function n(e,t,n,i,o){let s=async t=>t==null?new Map:o.parser.analyze(new Map([[e,t]]),o.signal),c=await s(t),l=await s(n),u=await o.parser.analyze(new Map([[e,i]]),o.signal),d=[...r(c,l,u).filter(e=>e.tier===`file`),...a(u)];if(o.validator){let t=await o.validator.validate(new Map([[e,i]]),o.signal);for(let e of t)d.push({category:e.category,severity:e.severity,tier:`file`,location:{file:e.file,line:e.line??1},message:e.message})}return d}function r(e,t,n){let r=new Map;i(e,`ours`,r),i(t,`theirs`,r);let a=[];for(let[e,t]of n)for(let n of t.references){if(n.resolved)continue;let t=r.get(l(e,n.name));t&&a.push({category:`broken-reference`,severity:`error`,tier:t.crossFile?`project`:`file`,location:{file:e,line:n.line,symbol:n.name},provenance:{side:t.side,line:t.line},message:`Reference "${n.name}" resolved before the merge (on ${t.side}) but no longer resolves.`})}return a}function i(e,t,n){let r=(e,r,i,a)=>{let o=l(e,r);n.has(o)||n.set(o,{side:t,line:i,crossFile:a})};for(let[t,n]of e){for(let e of n.definitions)r(t,e.name,e.line,!1);for(let e of n.bindings??[])r(t,e.name,e.line,!1)}for(let[t,n]of e)for(let e of n.references)e.resolved&&r(t,e.name,e.line,e.target?e.target.file!==t:!0)}function a(e){let t=[];for(let[n,r]of e){let e=new Map;for(let i of r.definitions){let r=e.get(i.name);r==null?e.set(i.name,i.line):t.push({category:`duplicate-definition`,severity:`warning`,tier:`file`,location:{file:n,line:i.line,symbol:i.name},message:`Duplicate definition of "${i.name}" (also defined at line ${r}).`})}for(let e of r.syntaxErrors)t.push({category:`syntax-error`,severity:`error`,tier:`file`,location:{file:n,line:e.line},message:e.message})}return t}function o(e,t){let n=[];for(let r of e){let e=r.strategy===`take-ours`?`theirs`:r.strategy===`take-theirs`?`ours`:null;if(!e||r.confidence!==0)continue;let i=(e===`ours`?t.ours:t.theirs).get(r.filePath);if(i==null)continue;let a=s(i,r.content);a<20||n.push({category:`dropped-side`,severity:`error`,tier:`file`,location:{file:r.filePath,line:1},message:`Resolution took "${r.strategy}" wholesale, discarding ~${a} line(s) of the ${e} side.`})}return n}function s(e,t){let n=new Set(t.split(`
 `)),r=0;for(let t of e.split(`
-`))t.trim()!==``&&!n.has(t)&&r++;return r}function s(e){return e.some(e=>{for(let t of e.values())if(t.language===`unsupported`)return!0;return!1})}function c(e,t){return JSON.stringify([e,t])}export{t as detect};
+`))t.trim()!==``&&!n.has(t)&&r++;return r}function c(e){return e.some(e=>{for(let t of e.values())if(t.language===`unsupported`)return!0;return!1})}function l(e,t){return JSON.stringify([e,t])}export{n as collectFileFindings,t as detect};

package/dist/reference-integrity/snapshot.d.ts

@@ -7,8 +7,11 @@ interface DetectionSnapshots {
   ours: SourceOverlay;
   theirs: SourceOverlay;
   result: SourceOverlay;
-  /** Number of files actually included in the snapshots (after the cap). */
+  /** Number of files in scope (after the cap). */
   analyzed: number;
+  /** How many scope files had loadable parent content on `ours` or `theirs`. When this is 0 the
+   *  before/after comparison had nothing to read — a total read failure, not a clean result. */
+  readable: number;
   /** Whether the scope exceeded the cap and was truncated. */
   truncated: boolean;
 }

package/dist/reference-integrity/snapshot.js

@@ -1 +1 @@
-import{changedFiles as e,mergeBase as t,readFile as n,showFile as r}from"../git/port-dispatch.js";async function i(e,t,n){let r=t.refs;if(!r)return null;let i=n.signal?{signal:n.signal}:void 0,c=new Map(e.map(e=>[e.filePath,e.content])),l=t.touchedFiles??await a(n.git,r,i),u=[],d=new Set;for(let e of[...c.keys(),...l,...t.fileNeighbors??[]])d.has(e)||(d.add(e),u.push(e));let f=u.length>400,p=f?u.slice(0,400):u,m=new Map,h=new Map,g=new Map;for(let e of p){let t=await o(n.git,r.ours,e,i);t!=null&&m.set(e,t);let a=await o(n.git,r.theirs,e,i);a!=null&&h.set(e,a);let l=c.get(e);if(l!=null)g.set(e,l);else{let t=await s(n.git,e,i);t!=null&&g.set(e,t)}}return{ours:m,theirs:h,result:g,analyzed:p.length,truncated:f}}async function a(n,r,i){try{return await e(n,r.base??await t(n,r.ours,r.theirs,i),r.theirs,i)}catch{return[]}}async function o(e,t,n,i){try{return await r(e,t,n,i)}catch{return null}}async function s(e,t,r){try{return await n(e,t,r)}catch{return null}}export{i as buildSnapshots};
+import{changedFiles as e,mergeBase as t,readFile as n,showFile as r}from"../git/port-dispatch.js";async function i(e,t,n){let r=t.detectionRefs??t.refs;if(!r)return null;let i=n.signal?{signal:n.signal}:void 0,c=new Map(e.map(e=>[e.filePath,e.content])),l=t.touchedFiles??await a(n.git,r,i),u=[],d=new Set;for(let e of[...c.keys(),...l,...t.fileNeighbors??[]])d.has(e)||(d.add(e),u.push(e));let f=u.length>400,p=f?u.slice(0,400):u,m=new Map,h=new Map,g=new Map,_=0;for(let e of p){let t=await o(n.git,r.ours,e,i);t&&m.set(e,t);let a=await o(n.git,r.theirs,e,i);a&&h.set(e,a),(t||a)&&_++;let l=c.get(e);if(l!=null)g.set(e,l);else{let t=await s(n.git,e,i);t!=null&&g.set(e,t)}}return{ours:m,theirs:h,result:g,analyzed:p.length,readable:_,truncated:f}}async function a(n,r,i){try{return await e(n,r.base??await t(n,r.ours,r.theirs,i),r.theirs,i)}catch{return[]}}async function o(e,t,n,i){try{return await r(e,t,n,i)}catch{return null}}async function s(e,t,r){try{return await n(e,t,r)}catch{return null}}export{i as buildSnapshots};

package/dist/resolver/deps.d.ts

@@ -1,7 +1,7 @@
 import { ConflictGitPort } from "../ports/git.js";
 import { ConflictModelPort, ResolverConfig } from "../ports/model.js";
 import { ParserPort } from "../ports/parser.js";
-import { ResolutionVerifier } from "../ports/verify.js";
+import { Validator } from "../ports/verify.js";
 import { ConflictProgressEvent } from "../types/events.js";
 
 //#region src/resolver/deps.d.ts
@@ -11,7 +11,7 @@ interface ResolverDeps<C extends ResolverConfig = ResolverConfig> {
   config?: C;
   onProgress?: (event: ConflictProgressEvent) => void;
   signal?: AbortSignal;
-  verifier?: ResolutionVerifier;
+  validator?: Validator;
   parser?: ParserPort;
 }
 //#endregion

package/dist/resolver/fix-loop.d.ts

@@ -0,0 +1,61 @@
+import { ConflictGitPort } from "../ports/git.js";
+import { DetectionReport } from "../types/findings.js";
+import { Resolution, ResolutionContext } from "../types/resolution.js";
+import { ConflictModelPort } from "../ports/model.js";
+import { ParserPort } from "../ports/parser.js";
+import { Validator } from "../ports/verify.js";
+import { ConflictProgressEvent } from "../types/events.js";
+import { StepConfig } from "../types/step.js";
+import { ModelBudget } from "./model-budget.js";
+
+//#region src/resolver/fix-loop.d.ts
+interface FixLoopDeps {
+  model: ConflictModelPort;
+  parser: ParserPort;
+  validator?: Validator;
+  config?: StepConfig;
+  onProgress?: (event: ConflictProgressEvent) => void;
+  signal?: AbortSignal;
+  /** Global model-call budget for the operation. When exhausted, the loop stops before any further
+   *  model call and leaves the remaining findings unfixed. Absent = unlimited. */
+  budget?: ModelBudget;
+  /** Invoked the first time the budget stops work. The caller dedupes so the operation emits a single
+   *  `fix:budget-exhausted`, whether the stop happens here or in the cross-file stage. */
+  onBudgetExhausted?: () => void;
+}
+/**
+ * Per-file convergence loop (opt-in `config.fix`). Re-detects the file's per-file findings, feeds the
+ * error-severity ones back through refine as fix instructions, and repeats until the file is clean, a
+ * round makes no progress, or the iteration budget runs out. What it cannot fix stays in the returned
+ * `Resolution.findings` — the verdict is computed from that remainder, never from a stale pre-fix set.
+ *
+ * Only intra-file findings are addressed here (from {@link collectFileFindings}); cross-file references
+ * are a separate set-level stage. `dropped-side` is not produced per-file and so is never routed. The
+ * caller should invoke this only for AI-resolved (`strategy: 'ai'`) text files.
+ */
+declare function runFixLoop(resolution: Resolution, oursContent: string | undefined, theirsContent: string | undefined, deps: FixLoopDeps): Promise<Resolution>;
+interface FixPhaseDeps {
+  model: ConflictModelPort;
+  git: ConflictGitPort;
+  parser: ParserPort;
+  validator?: Validator;
+  config?: StepConfig;
+  onProgress?: (event: ConflictProgressEvent) => void;
+  signal?: AbortSignal;
+  /** Global model-call budget for the operation. When exhausted, both fix stages stop before any
+   *  further model call, leaving the remainder in the report. Absent = unlimited. */
+  budget?: ModelBudget;
+}
+/**
+ * The fix phase (opt-in). Stage 2: per-file convergence over each AI resolution ({@link runFixLoop}).
+ * Stage 3: route cross-file (`tier: 'project'`) broken references back to the refine of their use-site
+ * file and re-detect over the whole set, up to `crossFileMaxIterations` rounds. Mutates `resolutions`
+ * in place and returns the final whole-set {@link DetectionReport} — which, being whole-set, also
+ * re-checks per-file for files touched by cross-file fixes.
+ *
+ * Cross-file findings on files without an AI resolution (e.g. auto-merged) are not routed: they have no
+ * carrier for an edit yet (needs a patches channel), so they remain in the report unchanged.
+ */
+declare function runFixPhase(resolutions: Resolution[], context: ResolutionContext, deps: FixPhaseDeps): Promise<DetectionReport>;
+//#endregion
+export { FixLoopDeps, FixPhaseDeps, runFixLoop, runFixPhase };

package/dist/resolver/fix-loop.js

@@ -0,0 +1,2 @@
+import{buildSnapshots as e}from"../reference-integrity/snapshot.js";import{collectFileFindings as t,detect as n}from"../reference-integrity/detect.js";import{checkResidualMarkers as r}from"../ports/verify.js";import{runRefinePass as i}from"./refine-pass.js";const a=.9;async function o(e,n,o,l){let u=l.config?.fixLoopMaxIterations??3,d={parser:l.parser,validator:l.validator,signal:l.signal},f=e.content,p=await t(e.filePath,n,o,f,d),m=p.filter(e=>e.severity===`error`);if(m.length===0)return l.onProgress?.({type:`fix:completed`,filePath:e.filePath,iterations:0,remaining:0}),p.length>0?{...e,findings:p}:e;if(l.budget?.exhausted())return l.onBudgetExhausted?.(),l.onProgress?.({type:`fix:completed`,filePath:e.filePath,iterations:0,remaining:m.length}),{...e,findings:p};l.onProgress?.({type:`fix:started`,filePath:e.filePath,findingCount:m.length});let h=[],g=0,_=c(m);for(;g<u&&m.length>0;g++){if(l.budget?.exhausted()){l.onBudgetExhausted?.();break}let a=await i(f,e.description,m.map(s),{model:l.model,signal:l.signal,temperature:l.config?.temperature,refineMaxSteps:l.config?.refineMaxSteps,onProgress:l.onProgress,filePath:e.filePath});if(a.edits.length===0)break;if(!r(e.filePath,a.content).valid){l.onProgress?.({type:`refine:discarded`,filePath:e.filePath,reason:`Fix edits introduced conflict markers.`});break}f=a.content,h.push(...a.edits),p=await t(e.filePath,n,o,f,d),m=p.filter(e=>e.severity===`error`);let u=c(m);if(u===_)break;_=u}l.onProgress?.({type:`fix:completed`,filePath:e.filePath,iterations:g,remaining:m.length});let v={...e,content:f,findings:p};return h.length>0&&(v={...v,strategy:`ai`,edits:[...e.edits??[],...h],confidence:Math.min(v.confidence,a)}),v}function s(e){let t=e.location.symbol?`"${e.location.symbol}" (line ${e.location.line})`:`line ${e.location.line}`;return`${e.category} at ${t}: ${e.message}`}function c(e){return e.map(e=>`${e.category}\u0000${e.location.file}\u0000${e.location.symbol??``}`).sort().join(`
+`)}async function l(t,r,i){let a={git:i.git,parser:i.parser,signal:i.signal},s=await e(t,r,{git:i.git,signal:i.signal});if(!s)return n(t,r,a);let c=!1,l=()=>{c||(c=!0,i.onProgress?.({type:`fix:budget-exhausted`,spent:i.budget?.spent()??0,limit:i.config?.maxModelCalls??0}))},f={model:i.model,parser:i.parser,validator:i.validator,config:i.config,onProgress:i.onProgress,signal:i.signal,budget:i.budget,onBudgetExhausted:l};for(let e=0;e<t.length;e++){let n=t[e];!n||n.strategy!==`ai`||(t[e]=await o(n,s.ours.get(n.filePath),s.theirs.get(n.filePath),f))}let p=i.config?.crossFileMaxIterations??2,m=await n(t,r,a);for(let e=0;e<p;e++){if(i.budget?.exhausted()){l();break}let e=d(m.findings,t);if(e.size===0)break;let o=!1;for(let[n,r]of e){if(i.budget?.exhausted()){l();break}let e=t.findIndex(e=>e.filePath===n),a=e>=0?t[e]:void 0;if(!a)continue;let c=a.content,d=await u(a,r,s.ours.get(n),s.theirs.get(n),f);t[e]=d,d.content!==c&&(o=!0)}if(!o)break;m=await n(t,r,a)}return m}async function u(e,n,o,c,l){let u=await i(e.content,e.description,n.map(s),{model:l.model,signal:l.signal,temperature:l.config?.temperature,refineMaxSteps:l.config?.refineMaxSteps,onProgress:l.onProgress,filePath:e.filePath});if(u.edits.length===0)return e;if(!r(e.filePath,u.content).valid)return l.onProgress?.({type:`refine:discarded`,filePath:e.filePath,reason:`Cross-file fix introduced conflict markers.`}),e;let d=await t(e.filePath,o,c,u.content,{parser:l.parser,validator:l.validator,signal:l.signal});return{...e,content:u.content,strategy:`ai`,edits:[...e.edits??[],...u.edits],confidence:Math.min(e.confidence,a),findings:d}}function d(e,t){let n=new Set(t.filter(e=>e.strategy===`ai`).map(e=>e.filePath)),r=new Map;for(let t of e){if(t.tier!==`project`||t.severity!==`error`||!n.has(t.location.file))continue;let e=r.get(t.location.file)??[];e.push(t),r.set(t.location.file,e)}return r}export{o as runFixLoop,l as runFixPhase};

package/dist/resolver/loop.d.ts

@@ -1,4 +1,3 @@
-import { Issue } from "../types/issue.js";
 import { ResolutionContext, ResolutionMetrics, ResolvedChunk } from "../types/resolution.js";
 import { Conflict } from "../types/conflict.js";
 import { ResolverDeps } from "./deps.js";
@@ -11,7 +10,6 @@ interface ResolverLoopResult {
   description: string;
   metrics: ResolutionMetrics;
   followUpInstructions?: string[];
-  issues?: Issue[];
 }
 declare function runResolverLoop(conflict: Conflict, context: ResolutionContext, deps: ResolverDeps): Promise<ResolverLoopResult>;
 //#endregion

package/dist/resolver/loop.js

@@ -1 +1 @@
-import{AIError as e}from"../errors/ai.js";import{applyChunks as t}from"../resolution/chunk-apply.js";import{sumUsages as n}from"../resolution/metrics.js";import{parseModelResponse as r}from"./parse-response.js";import{buildPrompt as i}from"./prompt.js";import{createResolverTools as a}from"./tools.js";import{validateChunks as o}from"./validate.js";async function s(n,s,d){let f=d.config?.maxSteps??15,p=d.config?.temperature??0,{definitions:m,execute:h}=a(d.git),{system:g,userMessage:_}=i(n,s,{maxSteps:f}),v=[{role:`user`,content:_}],y=d.signal?{signal:d.signal}:void 0,b=0,x=0,S=0,C=[],w=n.markers.some(e=>e.userResolution!=null),T;for(;b<f;){b++;let e=await d.model.generate({system:g,messages:[...v],tools:m,temperature:p,signal:d.signal});if(e.usage&&(C.push(e.usage),d.onProgress?.({type:`resolver:step-usage`,filePath:n.filePath,stepNumber:b,usage:e.usage})),e.toolCalls&&e.toolCalls.length>0){v.push({role:`assistant`,content:e.text,toolCalls:e.toolCalls});for(let t of e.toolCalls){let e=typeof t.args.reason==`string`?t.args.reason:void 0;d.onProgress?.({type:`resolver:tool-call`,filePath:n.filePath,tool:t.name,args:t.args,stepNumber:b,reason:e}),x++;let r=await h(t,y);d.onProgress?.({type:`resolver:tool-result`,filePath:n.filePath,tool:t.name,stepNumber:b,content:r.content}),v.push({role:`tool`,toolCallId:r.toolCallId,toolName:t.name,content:r.content})}continue}let i=e.text??``;if(!i.trim()){S++,v.push({role:`assistant`,content:``}),v.push({role:`user`,content:`[Step ${b}/${f}] Your response was empty. Please respond with a valid JSON object containing "description" (1-2 sentences) and either "strategy" ("ours", "theirs", or "deleted") with a top-level "confidence" (0-1) for a file-level decision, or "chunks" (array of { markerIndex, strategy, confidence, content?, reason? }).`});continue}let a;try{a=r(i,n.markers.length)}catch(e){S++;let t=e instanceof Error?e.message:String(e);v.push({role:`assistant`,content:i}),v.push({role:`user`,content:`[Step ${b}/${f}] Failed to parse your response: ${t}. Please respond with a valid JSON object containing "description" (1-2 sentences) and either "strategy" ("ours", "theirs", or "deleted") with a top-level "confidence" (0-1) for a file-level decision, or "chunks" (array of { markerIndex, strategy, confidence, content?, reason? }).`});continue}if(a.strategy===`deleted`&&n.type!==`delete-modify`){S++,v.push({role:`assistant`,content:i}),v.push({role:`user`,content:`[Step ${b}/${f}] Strategy "deleted" is only valid for delete-modify conflicts. This is a text conflict — respond with "chunks" or a file-level "ours"/"theirs" strategy.`});continue}if(a.strategy){let e=a.strategy;if((e===`ours`||e===`theirs`)&&w)a.chunks=n.markers.map((t,n)=>t.userResolution==null?{markerIndex:n,strategy:e}:null).filter(e=>e!==null),a.strategy=void 0;else return d.onProgress?.({type:`resolver:response`,filePath:n.filePath,chunks:a.chunks,strategy:e,confidence:a.confidence,description:a.description,...a.followUpInstructions?{followUpInstructions:a.followUpInstructions}:{}}),{chunks:a.chunks,strategy:e,confidence:a.confidence,description:a.description,metrics:u(C,b,x,S),...a.followUpInstructions?{followUpInstructions:a.followUpInstructions}:{}}}if(n.markers.length===0&&!a.strategy){S++,v.push({role:`assistant`,content:i}),v.push({role:`user`,content:`[Step ${b}/${f}] Delete-modify conflicts require a file-level strategy field ("ours", "theirs", or "deleted"). Please respond with a JSON object containing "strategy".`});continue}let s=a.chunks.filter(e=>n.markers[e.markerIndex]?.userResolution==null),_=o(s,n);if(!_.valid){S++;let e=(_.issues??[]).map(e=>e.message).join(` `);v.push({role:`assistant`,content:i}),v.push({role:`user`,content:`[Step ${b}/${f}] Validation failed: ${e}\nPlease fix the issues and respond with a corrected JSON object. Make sure every marker index appears exactly once, or use a top-level "strategy" field.`});continue}let E=l(s,n);if(d.verifier&&n.type===`text`){let e=t(n.rawContent,n.markers,E),r=await d.verifier.verify(n.filePath,e);if(!r.valid){S++;let e=(r.issues??[]).filter(e=>e.severity===`error`).map(e=>e.message).join(` `)||`Content did not pass verification.`;v.push({role:`assistant`,content:i}),v.push({role:`user`,content:`[Step ${b}/${f}] Verification failed: ${e}\nPlease fix and respond with corrected JSON.`});continue}let a=(r.issues??[]).filter(e=>e.severity===`warning`);a.length>0&&(T=a,d.onProgress?.({type:`verification:issues`,filePath:n.filePath,issues:a}))}let D=c(s,a.confidence);return d.onProgress?.({type:`resolver:response`,filePath:n.filePath,chunks:a.chunks,confidence:D,description:a.description,...a.followUpInstructions?{followUpInstructions:a.followUpInstructions}:{}}),{chunks:E,confidence:D,description:a.description,metrics:u(C,b,x,S),...a.followUpInstructions?{followUpInstructions:a.followUpInstructions}:{},...T&&T.length>0?{issues:T}:{}}}throw new e(`VALIDATION_EXHAUSTED`,`Resolver exhausted ${f} steps without producing a valid resolution for ${n.filePath}.`)}function c(e,t){let n=e.map(e=>e.confidence).filter(e=>e!==void 0);return n.length>0?Math.min(...n):e.length>0?t:1}function l(e,t){let n=[...e];for(let e=0;e<t.markers.length;e++){let r=t.markers[e]?.userResolution;r!=null&&n.push({markerIndex:e,...r})}return n.sort((e,t)=>e.markerIndex-t.markerIndex),n}function u(e,t,r,i){return{...n(e)??{inputTokens:0,outputTokens:0},stepCount:t,toolCallCount:r,retryCount:i}}export{s as runResolverLoop};
+import{AIError as e}from"../errors/ai.js";import{sumUsages as t}from"../resolution/metrics.js";import{parseModelResponse as n}from"./parse-response.js";import{buildPrompt as r}from"./prompt.js";import{createResolverTools as i}from"./tools.js";import{validateChunks as a}from"./validate.js";async function o(t,o,u){let d=u.config?.maxSteps??15,f=u.config?.temperature??0,{definitions:p,execute:m}=i(u.git),{system:h,userMessage:g}=r(t,o,{maxSteps:d}),_=[{role:`user`,content:g}],v=u.signal?{signal:u.signal}:void 0,y=0,b=0,x=0,S=[],C=t.markers.some(e=>e.userResolution!=null);for(;y<d;){y++;let e=await u.model.generate({system:h,messages:[..._],tools:p,temperature:f,signal:u.signal});if(e.usage&&(S.push(e.usage),u.onProgress?.({type:`resolver:step-usage`,filePath:t.filePath,stepNumber:y,usage:e.usage})),e.toolCalls&&e.toolCalls.length>0){_.push({role:`assistant`,content:e.text,toolCalls:e.toolCalls});for(let n of e.toolCalls){let e=typeof n.args.reason==`string`?n.args.reason:void 0;u.onProgress?.({type:`resolver:tool-call`,filePath:t.filePath,tool:n.name,args:n.args,stepNumber:y,reason:e}),b++;let r=await m(n,v);u.onProgress?.({type:`resolver:tool-result`,filePath:t.filePath,tool:n.name,stepNumber:y,content:r.content}),_.push({role:`tool`,toolCallId:r.toolCallId,toolName:n.name,content:r.content})}continue}let r=e.text??``;if(!r.trim()){x++,_.push({role:`assistant`,content:``}),_.push({role:`user`,content:`[Step ${y}/${d}] Your response was empty. Please respond with a valid JSON object containing "description" (1-2 sentences) and either "strategy" ("ours", "theirs", or "deleted") with a top-level "confidence" (0-1) for a file-level decision, or "chunks" (array of { markerIndex, strategy, confidence, content?, reason? }).`});continue}let i;try{i=n(r,t.markers.length)}catch(e){x++;let t=e instanceof Error?e.message:String(e);_.push({role:`assistant`,content:r}),_.push({role:`user`,content:`[Step ${y}/${d}] Failed to parse your response: ${t}. Please respond with a valid JSON object containing "description" (1-2 sentences) and either "strategy" ("ours", "theirs", or "deleted") with a top-level "confidence" (0-1) for a file-level decision, or "chunks" (array of { markerIndex, strategy, confidence, content?, reason? }).`});continue}if(i.strategy===`deleted`&&t.type!==`delete-modify`){x++,_.push({role:`assistant`,content:r}),_.push({role:`user`,content:`[Step ${y}/${d}] Strategy "deleted" is only valid for delete-modify conflicts. This is a text conflict — respond with "chunks" or a file-level "ours"/"theirs" strategy.`});continue}if(i.strategy){let e=i.strategy;if((e===`ours`||e===`theirs`)&&C)i.chunks=t.markers.map((t,n)=>t.userResolution==null?{markerIndex:n,strategy:e}:null).filter(e=>e!==null),i.strategy=void 0;else return u.onProgress?.({type:`resolver:response`,filePath:t.filePath,chunks:i.chunks,strategy:e,confidence:i.confidence,description:i.description,...i.followUpInstructions?{followUpInstructions:i.followUpInstructions}:{}}),{chunks:i.chunks,strategy:e,confidence:i.confidence,description:i.description,metrics:l(S,y,b,x),...i.followUpInstructions?{followUpInstructions:i.followUpInstructions}:{}}}if(t.markers.length===0&&!i.strategy){x++,_.push({role:`assistant`,content:r}),_.push({role:`user`,content:`[Step ${y}/${d}] Delete-modify conflicts require a file-level strategy field ("ours", "theirs", or "deleted"). Please respond with a JSON object containing "strategy".`});continue}let o=i.chunks.filter(e=>t.markers[e.markerIndex]?.userResolution==null),g=a(o,t);if(!g.valid){x++;let e=(g.issues??[]).map(e=>e.message).join(` `);_.push({role:`assistant`,content:r}),_.push({role:`user`,content:`[Step ${y}/${d}] Validation failed: ${e}\nPlease fix the issues and respond with a corrected JSON object. Make sure every marker index appears exactly once, or use a top-level "strategy" field.`});continue}let w=c(o,t),T=s(o,i.confidence);return u.onProgress?.({type:`resolver:response`,filePath:t.filePath,chunks:i.chunks,confidence:T,description:i.description,...i.followUpInstructions?{followUpInstructions:i.followUpInstructions}:{}}),{chunks:w,confidence:T,description:i.description,metrics:l(S,y,b,x),...i.followUpInstructions?{followUpInstructions:i.followUpInstructions}:{}}}throw new e(`VALIDATION_EXHAUSTED`,`Resolver exhausted ${d} steps without producing a valid resolution for ${t.filePath}.`)}function s(e,t){let n=e.map(e=>e.confidence).filter(e=>e!==void 0);return n.length>0?Math.min(...n):e.length>0?t:1}function c(e,t){let n=[...e];for(let e=0;e<t.markers.length;e++){let r=t.markers[e]?.userResolution;r!=null&&n.push({markerIndex:e,...r})}return n.sort((e,t)=>e.markerIndex-t.markerIndex),n}function l(e,n,r,i){return{...t(e)??{inputTokens:0,outputTokens:0},stepCount:n,toolCallCount:r,retryCount:i}}export{o as runResolverLoop};

package/dist/resolver/model-budget.d.ts

@@ -0,0 +1,20 @@
+import { ConflictModelPort } from "../ports/model.js";
+
+//#region src/resolver/model-budget.d.ts
+/** A shared, per-operation counter of `model.generate` calls. Created once per {@link resolveConflicts}
+ *  run; the wrapped model increments the counter but never blocks — enforcement is the caller's job via
+ *  {@link ModelBudget.exhausted}, checked before fix-phase model calls only. Counting instead of throwing
+ *  is deliberate: a throw inside the resolve loop would be caught by the fallback path and degrade a good
+ *  resolution into a whole-side take — the exact data loss this package guards against. */
+interface ModelBudget {
+  /** Wrap a model so every `generate` call increments this budget's shared counter, then delegates to
+   *  the real model unchanged. Multiple wraps share one counter. */
+  wrap(model: ConflictModelPort): ConflictModelPort;
+  spent(): number;
+  /** Calls left before the cap. `Infinity` when the budget is unlimited (`max` undefined). */
+  remaining(): number;
+  exhausted(): boolean;
+}
+declare function createModelBudget(max?: number): ModelBudget;
+//#endregion
+export { ModelBudget, createModelBudget };

package/dist/resolver/model-budget.js

@@ -0,0 +1 @@
+function e(e){let t=0,n=()=>e===void 0?1/0:e-t;return{wrap(e){return{generate:n=>(t++,e.generate(n))}},spent:()=>t,remaining:n,exhausted:()=>n()<=0}}export{e as createModelBudget};

package/dist/resolver/refine-pass.js

@@ -1 +1 @@
-import{sumUsages as e}from"../resolution/metrics.js";import{buildRefinePrompt as t}from"./prompt.js";import{createRefineTools as n}from"./refine-tools.js";async function r(r,i,a,o){let s=o.refineMaxSteps??5,{system:c,userMessage:l}=t(r,i,a),{definitions:u,execute:d}=n(),f=[{role:`user`,content:l}],p=r,m=[],h=0,g=[];for(let t=0;t<s;t++){let n=t+1,r=await o.model.generate({system:c,messages:[...f],tools:u,temperature:o.temperature??0,signal:o.signal});if(r.usage&&g.push(r.usage),r.toolCalls&&r.toolCalls.length>0){f.push({role:`assistant`,content:r.text,toolCalls:r.toolCalls});for(let e of r.toolCalls){let t=e.args.ops,r=Array.isArray(t)?t:[];o.onProgress?.({type:`refine:tool-call`,filePath:o.filePath,stepNumber:n,ops:r});let{content:i,edits:a,verifiedCount:s,feedback:c,isError:l}=d(e,p);l||(p=i,m.push(...a),h+=s),o.onProgress?.({type:`refine:tool-result`,filePath:o.filePath,stepNumber:n,appliedCount:a.length,isError:l,feedback:c}),f.push({role:`tool`,toolCallId:e.id,toolName:e.name,content:c})}continue}let i=(r.text??``).trim();return o.onProgress?.({type:`refine:final-text`,filePath:o.filePath,text:i}),{edits:m,verifies:h,content:p,description:i,usage:e(g)}}return{edits:m,verifies:h,content:p,description:``,usage:e(g)}}export{r as runRefinePass};
+import{sumUsages as e}from"../resolution/metrics.js";import{buildRefinePrompt as t}from"./prompt.js";import{createRefineTools as n}from"./refine-tools.js";async function r(r,i,a,o){let s=o.refineMaxSteps??5,{system:c,userMessage:l}=t(r,i,a),{definitions:u,execute:d}=n(),f=[{role:`user`,content:l}],p=r,m=[],h=0,g=0,_=[];for(let t=0;t<s;t++){let n=t+1,r=await o.model.generate({system:c,messages:[...f],tools:u,temperature:o.temperature??0,signal:o.signal});if(r.usage&&_.push(r.usage),r.toolCalls&&r.toolCalls.length>0){f.push({role:`assistant`,content:r.text,toolCalls:r.toolCalls});for(let t of r.toolCalls){let r=t.args.ops,i=Array.isArray(r)?r:[];o.onProgress?.({type:`refine:tool-call`,filePath:o.filePath,stepNumber:n,ops:i});let{content:a,edits:s,verifiedCount:c,feedback:l,isError:u}=d(t,p);if(u?g++:(p=a,m.push(...s),h+=c,g=0),o.onProgress?.({type:`refine:tool-result`,filePath:o.filePath,stepNumber:n,appliedCount:s.length,isError:u,feedback:l}),f.push({role:`tool`,toolCallId:t.id,toolName:t.name,content:l}),g>=3)return o.onProgress?.({type:`refine:bailed`,filePath:o.filePath,reason:`Stopped after ${g} consecutive apply errors.`}),{edits:m,verifies:h,content:p,description:``,usage:e(_)}}continue}let i=(r.text??``).trim();return o.onProgress?.({type:`refine:final-text`,filePath:o.filePath,text:i}),{edits:m,verifies:h,content:p,description:i,usage:e(_)}}return{edits:m,verifies:h,content:p,description:``,usage:e(_)}}export{r as runRefinePass};

package/dist/resolver/resolve-conflict.js

@@ -1 +1 @@
-import{checkResidualMarkers as e}from"../ports/verify.js";import{resolveChunkContent as t}from"../resolution/chunk-apply.js";import{createResolution as n}from"../resolution/create-resolution.js";import{mergeUsages as r}from"../resolution/metrics.js";import{runResolverLoop as i}from"./loop.js";import{runRefinePass as a}from"./refine-pass.js";import{buildThreeWayDiff as o}from"./three-way-diff.js";const s={refineNoAction:.6,refineApplied:.9};async function c(c,l,u){let d=l.threeWayDiff||!l.refs?l:{...l,threeWayDiff:await o(c.filePath,l.refs,{git:u.git,signal:u.signal})},{chunks:f,strategy:p,confidence:m,description:h,metrics:g,followUpInstructions:_,issues:v}=await i(c,d,{model:u.model,git:u.git,config:u.config,onProgress:u.onProgress,signal:u.signal,verifier:u.verifier}),y=n(c,f,{confidence:m,description:h,metrics:g,...p?{fileStrategy:p}:{},...d.threeWayDiff?{threeWayDiff:d.threeWayDiff}:{}});v&&v.length>0&&(y={...y,issues:v});let b=_&&_.length>0;if(c.type===`text`&&b){u.onProgress?.({type:`refine:started`,filePath:c.filePath});let n=0;try{let i=await a(y.content,y.description,_,{model:u.model,signal:u.signal,temperature:u.config?.temperature,refineMaxSteps:u.config?.refineMaxSteps,onProgress:u.onProgress,filePath:c.filePath});if(i.edits.length>0){let t=e(c.filePath,i.content);if(t.valid)y={...y,content:i.content,edits:i.edits,strategy:`ai`},n=i.edits.length;else{let e=(t.issues??[]).map(e=>e.message).join(` `);u.onProgress?.({type:`refine:discarded`,filePath:c.filePath,reason:`Edits introduced conflict markers: ${e}`})}}if(n>0){y={...y,confidence:Math.min(y.confidence,s.refineApplied)};let e=[];for(let n=0;n<c.markers.length;n++){let r=c.markers[n];if(!r||r.userResolution==null)continue;let a=t({markerIndex:n,...r.userResolution},r);a!==``&&(i.content.includes(a)||e.push(n))}e.length>0&&(u.onProgress?.({type:`refine:touched-user-region`,filePath:c.filePath,markerIndexes:e}),y={...y,note:`Refine modified user-resolved region(s): marker ${e.join(`, `)}.`})}else i.edits.length===0&&i.verifies>0||(y={...y,confidence:Math.min(y.confidence,s.refineNoAction)});if(i.usage){let e=r(y.metrics??{inputTokens:0,outputTokens:0},i.usage);y={...y,metrics:{...y.metrics,...e}}}u.onProgress?.({type:`refine:completed`,filePath:c.filePath,appliedCount:n})}catch(e){let t=e instanceof Error?e.message:String(e);throw u.onProgress?.({type:`refine:failed`,filePath:c.filePath,reason:t}),e}}else u.onProgress?.({type:`refine:skipped`,filePath:c.filePath,reason:`no-follow-ups`});return u.onProgress?.({type:`resolver:completed`,filePath:c.filePath,stepCount:g.stepCount??0}),y}export{c as resolveConflict};
+import{resolveChunkContent as e}from"../resolution/chunk-apply.js";import{createResolution as t}from"../resolution/create-resolution.js";import{checkResidualMarkers as n}from"../ports/verify.js";import{mergeUsages as r}from"../resolution/metrics.js";import{runResolverLoop as i}from"./loop.js";import{runRefinePass as a}from"./refine-pass.js";import{buildThreeWayDiff as o}from"./three-way-diff.js";const s={refineNoAction:.6,refineApplied:.9};async function c(c,l,u){let d=l.threeWayDiff||!l.refs?l:{...l,threeWayDiff:await o(c.filePath,l.refs,{git:u.git,signal:u.signal})},{chunks:f,strategy:p,confidence:m,description:h,metrics:g,followUpInstructions:_}=await i(c,d,{model:u.model,git:u.git,config:u.config,onProgress:u.onProgress,signal:u.signal}),v=t(c,f,{confidence:m,description:h,metrics:g,...p?{fileStrategy:p}:{},...d.threeWayDiff?{threeWayDiff:d.threeWayDiff}:{}}),y=_&&_.length>0;if(c.type===`text`&&y){u.onProgress?.({type:`refine:started`,filePath:c.filePath});let t=0;try{let i=await a(v.content,v.description,_,{model:u.model,signal:u.signal,temperature:u.config?.temperature,refineMaxSteps:u.config?.refineMaxSteps,onProgress:u.onProgress,filePath:c.filePath});if(i.edits.length>0){let e=n(c.filePath,i.content);if(e.valid)v={...v,content:i.content,edits:i.edits,strategy:`ai`},t=i.edits.length;else{let t=(e.issues??[]).map(e=>e.message).join(` `);u.onProgress?.({type:`refine:discarded`,filePath:c.filePath,reason:`Edits introduced conflict markers: ${t}`})}}if(t>0){v={...v,confidence:Math.min(v.confidence,s.refineApplied)};let t=[];for(let n=0;n<c.markers.length;n++){let r=c.markers[n];if(!r||r.userResolution==null)continue;let a=e({markerIndex:n,...r.userResolution},r);a!==``&&(i.content.includes(a)||t.push(n))}t.length>0&&(u.onProgress?.({type:`refine:touched-user-region`,filePath:c.filePath,markerIndexes:t}),v={...v,note:`Refine modified user-resolved region(s): marker ${t.join(`, `)}.`})}else i.edits.length===0&&i.verifies>0||(v={...v,confidence:Math.min(v.confidence,s.refineNoAction)});if(i.usage){let e=r(v.metrics??{inputTokens:0,outputTokens:0},i.usage);v={...v,metrics:{...v.metrics,...e}}}u.onProgress?.({type:`refine:completed`,filePath:c.filePath,appliedCount:t})}catch(e){if(u.signal?.aborted)throw e;let t=e instanceof Error?e.message:String(e);u.onProgress?.({type:`refine:failed`,filePath:c.filePath,reason:t}),v={...v,confidence:Math.min(v.confidence,s.refineNoAction)}}}else u.onProgress?.({type:`refine:skipped`,filePath:c.filePath,reason:`no-follow-ups`});if(u.validator&&c.type===`text`)try{let e=await u.validator.validate(new Map([[c.filePath,v.content]]),u.signal);if(e.length>0){let t=e.map(e=>({category:e.category,severity:e.severity,tier:`file`,location:{file:e.file,line:e.line??1},message:e.message}));v={...v,findings:t}}}catch(e){if(u.signal?.aborted)throw e;let t=e instanceof Error?e.message:String(e);u.onProgress?.({type:`validation:failed`,filePath:c.filePath,reason:t})}return u.onProgress?.({type:`resolver:completed`,filePath:c.filePath,stepCount:g.stepCount??0}),v}export{c as resolveConflict};

package/dist/resolver/resolve-conflicts.js

@@ -1 +1 @@
-import{AIError as e}from"../errors/ai.js";import{unmergedEntries as t}from"../git/port-dispatch.js";import{extractConflict as n}from"../extraction/extract.js";import{detect as r}from"../reference-integrity/detect.js";import{createResolution as i}from"../resolution/create-resolution.js";import{takeOurs as a,takeTheirs as o}from"../resolution/take-strategy.js";import{resolveConflict as s}from"./resolve-conflict.js";import c from"picomatch";function l(e){let t=e.map(e=>{let t=(Array.isArray(e.match)?e.match:[e.match]).map(e=>c(e,{basename:!e.includes(`/`)}));return{isMatch:e=>t.some(t=>t(e)),strategy:e.strategy}});return e=>{for(let{isMatch:n,strategy:r}of t)if(n(e))return r}}async function u(e,s){let c=e.config?.rules??[],u=e.config?.defaultStrategy??`ai`,p=l(c),m=await t(e.git,{signal:e.signal}),h={...s??{}},g=[],_=[],v=[];for(let t of m){if(e.signal?.aborted)break;let r=p(t.path)??u;if(r===`skip`){v.push({filePath:t.path,reason:`excluded`}),e.onProgress?.({type:`conflict:excluded`,filePath:t.path});continue}let s;try{s=await n(t.path,{git:e.git,signal:e.signal},t.reason)}catch(e){_.push({filePath:t.path,error:f(e)});continue}if(!s){v.push({filePath:t.path,reason:`no-markers`}),e.onProgress?.({type:`conflict:skipped`,filePath:t.path,reason:`no-markers`,entryReason:t.reason});continue}e.onProgress?.({type:`conflict:found`,filePath:s.filePath,conflictType:s.type,markerCount:s.markers.length});let c=null;c=r===`take-ours`?a(s):r===`take-theirs`?o(s):r===`deleted`?i(s,[],{confidence:1,fileStrategy:`deleted`}):await d(s,h,e,_),c&&(h.previousResolutions=[...h.previousResolutions??[],c],g.push(c),e.onProgress?.({type:`resolution:applied`,filePath:c.filePath,strategy:c.strategy,confidence:c.confidence,description:c.description}))}return{resolutions:g,errors:_,skipped:v,detection:await r(g,h,{git:e.git,parser:e.parser,signal:e.signal})}}async function d(t,n,r,i){try{return await s(t,n,{model:r.model,git:r.git,config:r.config,onProgress:r.onProgress,signal:r.signal,verifier:r.verifier})}catch(n){let s=f(n),c=r.config?.fallbackStrategy;return c?(r.onProgress?.({type:`resolution:fallback`,filePath:t.filePath,error:s,cause:s instanceof e?s.code:void 0}),{...c===`take-ours`?a(t):o(t),confidence:0}):(i.push({filePath:t.filePath,error:s}),r.onProgress?.({type:`resolution:failed`,filePath:t.filePath,error:s}),null)}}function f(e){return e instanceof Error?e:Error(String(e))}export{u as resolveConflicts};
+import{AIError as e}from"../errors/ai.js";import{unmergedEntries as t}from"../git/port-dispatch.js";import{extractConflict as n}from"../extraction/extract.js";import{detect as r}from"../reference-integrity/detect.js";import{createResolution as i}from"../resolution/create-resolution.js";import{takeOurs as a,takeTheirs as o}from"../resolution/take-strategy.js";import{resolveConflict as s}from"./resolve-conflict.js";import{runFixPhase as c}from"./fix-loop.js";import{createModelBudget as l}from"./model-budget.js";import u from"picomatch";function d(e){let t=e.map(e=>{let t=(Array.isArray(e.match)?e.match:[e.match]).map(e=>u(e,{basename:!e.includes(`/`)}));return{isMatch:e=>t.some(t=>t(e)),strategy:e.strategy}});return e=>{for(let{isMatch:n,strategy:r}of t)if(n(e))return r}}async function f(e,s){let u=e.config?.rules??[],f=e.config?.defaultStrategy??`ai`,g=d(u),_=await t(e.git,{signal:e.signal}),v=l(e.config?.maxModelCalls),y=v.wrap(e.model),b={...s??{}},x=[],S=[],C=[];for(let t of _){if(e.signal?.aborted)break;let r=g(t.path)??f;if(r===`skip`){C.push({filePath:t.path,reason:`excluded`}),e.onProgress?.({type:`conflict:excluded`,filePath:t.path});continue}let s;try{s=await n(t.path,{git:e.git,signal:e.signal},t.reason)}catch(e){S.push({filePath:t.path,error:m(e)});continue}if(!s){C.push({filePath:t.path,reason:`no-markers`}),e.onProgress?.({type:`conflict:skipped`,filePath:t.path,reason:`no-markers`,entryReason:t.reason});continue}e.onProgress?.({type:`conflict:found`,filePath:s.filePath,conflictType:s.type,markerCount:s.markers.length});let c=null;c=r===`take-ours`?a(s):r===`take-theirs`?o(s):r===`deleted`?i(s,[],{confidence:1,fileStrategy:`deleted`}):await p(s,b,{...e,model:y},S),c&&(b.previousResolutions=[...b.previousResolutions??[],c],x.push(c),e.onProgress?.({type:`resolution:applied`,filePath:c.filePath,strategy:c.strategy,confidence:c.confidence,description:c.description}))}let w;if(e.config?.fix&&e.parser)try{w=await c(x,b,{model:y,git:e.git,parser:e.parser,validator:e.validator,config:e.config,onProgress:e.onProgress,signal:e.signal,budget:v})}catch(t){if(e.signal?.aborted)throw t;e.onProgress?.({type:`fix:failed`,reason:m(t).message}),w=await r(x,b,{git:e.git,parser:e.parser,signal:e.signal}),w={...w,checks:{referenceIntegrity:`errored`,structural:`errored`}}}else w=await r(x,b,{git:e.git,parser:e.parser,signal:e.signal});let T=x.flatMap(e=>e.findings??[]);return{resolutions:x,errors:S,skipped:C,detection:{...w,findings:h([...w.findings,...T])}}}async function p(t,n,r,i){try{return await s(t,n,{model:r.model,git:r.git,config:r.config,onProgress:r.onProgress,signal:r.signal,validator:r.validator})}catch(n){let s=m(n);if(r.signal?.aborted)throw s;let c=r.config?.fallbackStrategy;return c?(r.onProgress?.({type:`resolution:fallback`,filePath:t.filePath,error:s,cause:s instanceof e?s.code:void 0}),{...c===`take-ours`?a(t):o(t),confidence:0}):(i.push({filePath:t.filePath,error:s}),r.onProgress?.({type:`resolution:failed`,filePath:t.filePath,error:s}),null)}}function m(e){return e instanceof Error?e:Error(String(e))}function h(e){let t=new Set,n=[];for(let r of e){let{category:e,location:i}=r,a=`${e}\u0000${i.file}\u0000${i.line}\u0000${i.symbol??``}`;t.has(a)||(t.add(a),n.push(r))}return n}export{f as resolveConflicts};

package/dist/resolver/summarize-operation.d.ts

@@ -5,7 +5,7 @@ import { OperationDigest, OperationSummary } from "../types/summary.js";
 //#region src/resolver/summarize-operation.d.ts
 /**
  * Options for {@link summarizeOperation}. Intentionally a flat bag rather than the resolver's
- * `ResolverDeps` shape: summarization is a leaf operation that needs no git, verifier, or progress
+ * `ResolverDeps` shape: summarization is a leaf operation that needs no git, validator, or progress
  * sink, and its `model` is optional — omit it for a digest-only result.
  */
 interface SummarizeOperationOptions {
@@ -16,7 +16,8 @@ interface SummarizeOperationOptions {
   reviewThreshold?: number;
   temperature?: number;
 }
-/** Pure, model-free rollup of a {@link StepResult}. */
+/** Pure, model-free rollup of a {@link StepResult}, folding in `detection` so a file with an error
+ *  finding — or a detection check that did not run — can never read as clean. */
 declare function buildOperationDigest(result: StepResult, reviewThreshold?: number): OperationDigest;
 /**
  * Summarize a resolve operation for a reviewer. Always returns a deterministic `digest`; when

package/dist/resolver/summarize-operation.js

@@ -1 +1 @@
-import{buildSummaryPrompt as e}from"./prompt.js";const t=.8;function n(e,n=t){let r={ai:0,"take-ours":0,"take-theirs":0,deleted:0,skipped:0},i=0,a=null,o=[];for(let t of e.resolutions)r[t.strategy]++,i+=t.chunks?.length??0,a=a===null?t.confidence:Math.min(a,t.confidence),t.confidence<n&&o.push({filePath:t.filePath,confidence:t.confidence});return o.sort((e,t)=>e.confidence-t.confidence),{files:e.resolutions.length,conflicts:i,byStrategy:r,minConfidence:a,needsReview:o,skipped:e.skipped?.length??0,errors:e.errors.length}}async function r(r,i={}){let a=n(r,i.reviewThreshold??t);if(!i.model)return{digest:a};let{system:o,userMessage:s}=e(r,a),c=await i.model.generate({system:o,messages:[{role:`user`,content:s}],temperature:i.temperature??0,signal:i.signal}),l=c.text?.trim();return{digest:a,...l?{prose:l}:{},...c.usage?{usage:c.usage}:{}}}export{n as buildOperationDigest,r as summarizeOperation};
+import{buildSummaryPrompt as e}from"./prompt.js";const t=.8;function n(e,n=t){let o={ai:0,"take-ours":0,"take-theirs":0,deleted:0,skipped:0},s=0,c=null,l=new Map;for(let t of e.resolutions)o[t.strategy]++,s+=t.chunks?.length??0,c=c===null?t.confidence:Math.min(c,t.confidence),t.confidence<n&&l.set(t.filePath,{filePath:t.filePath,confidence:t.confidence,reason:`low-confidence`});let u=e.detection,d=u?.findings??[],f=new Map,p=!1;for(let e of d){e.severity===`error`&&(p=!0);let t=f.get(e.location.file)??new Set;t.add(e.category),f.set(e.location.file,t)}for(let[e,t]of f){let n=l.get(e);l.set(e,{filePath:e,...n?.confidence==null?{}:{confidence:n.confidence},reason:`finding`,findingCategories:[...t].sort()})}let m=[...l.values()].sort(i),h=u!=null&&r(u.checks.referenceIntegrity)&&r(u.checks.structural),g=a({hasErrorFinding:p,hasWarningFinding:d.some(e=>e.severity===`warning`),needsReview:m.length>0,detectionComplete:h,hasErrors:e.errors.length>0});return{files:e.resolutions.length,conflicts:s,byStrategy:o,minConfidence:c,needsReview:m,skipped:e.skipped?.length??0,errors:e.errors.length,detectionComplete:h,findingCount:d.length,verdict:g}}function r(e){return e===`ran`||e===`partial-unsupported-language`}function i(e,t){return e.reason===t.reason?(e.confidence??1)-(t.confidence??1):e.reason===`finding`?-1:1}function a(e){return e.hasErrorFinding?`blocked`:e.needsReview||!e.detectionComplete||e.hasErrors||e.hasWarningFinding?`needs-review`:`clean`}async function o(r,i={}){let a=n(r,i.reviewThreshold??t);if(!i.model)return{digest:a};let{system:o,userMessage:s}=e(r,a),c=await i.model.generate({system:o,messages:[{role:`user`,content:s}],temperature:i.temperature??0,signal:i.signal}),l=c.text?.trim();return{digest:a,...l?{prose:l}:{},...c.usage?{usage:c.usage}:{}}}export{n as buildOperationDigest,o as summarizeOperation};

package/dist/resolver/validate.d.ts

@@ -1,6 +1,6 @@
-import { Issue } from "../types/issue.js";
 import { ResolvedChunk } from "../types/resolution.js";
 import { Conflict } from "../types/conflict.js";
+import { Issue } from "../types/issue.js";
 
 //#region src/resolver/validate.d.ts
 interface ValidationResult {

package/dist/types/events.d.ts

@@ -1,4 +1,3 @@
-import { Issue } from "./issue.js";
 import { ResolutionStrategy, ResolvedChunk } from "./resolution.js";
 import { ConflictType } from "./conflict.js";
 import { AiTokenUsage } from "@gitkraken/shared-tools";
@@ -91,14 +90,35 @@ type ConflictProgressEvent = {
   type: 'refine:failed';
   filePath: string;
   reason: string;
+} | {
+  type: 'refine:bailed';
+  filePath: string;
+  reason: string;
 } | {
   type: 'refine:touched-user-region';
   filePath: string;
   markerIndexes: number[];
 } | {
-  type: 'verification:issues';
+  type: 'fix:started';
   filePath: string;
-  issues: Issue[];
+  findingCount: number;
+} | {
+  type: 'fix:completed';
+  filePath: string;
+  iterations: number;
+  remaining: number;
+} | {
+  type: 'fix:failed';
+  filePath?: string;
+  reason: string;
+} | {
+  type: 'fix:budget-exhausted';
+  spent: number;
+  limit: number;
+} | {
+  type: 'validation:failed';
+  filePath: string;
+  reason: string;
 } | {
   type: 'resolver:tool-result';
   filePath: string;

package/dist/types/findings.d.ts

@@ -1,8 +1,13 @@
 //#region src/types/findings.d.ts
+/** The package's own detection categories. `Finding.category` is an open `string` so consumer
+ *  validators can contribute their own kinds (e.g. `'type-error'`, `'lint:no-console'`); these are the
+ *  well-known values the package itself emits. */
 type FindingCategory = 'broken-reference' | 'duplicate-definition' | 'syntax-error' | 'dropped-side';
 type FindingTier = 'file' | 'project';
 interface Finding {
-  category: FindingCategory;
+  /** Finding kind. Open string — the package emits {@link FindingCategory} values; a consumer
+   *  validator may use its own category strings. */
+  category: string;
   severity: 'error' | 'warning';
   tier: FindingTier;
   location: {
@@ -19,19 +24,22 @@ interface Finding {
 }
 /** Why a check produced its result — lets a consumer tell "ran, clean" apart from "did not run".
  *  `errored` means the parser was present but threw; `partial-unsupported-language` means some files
- *  in scope could not be parsed. */
-type CheckStatus = 'ran' | 'skipped-no-parser' | 'skipped-no-refs' | 'partial-unsupported-language' | 'errored';
+ *  in scope could not be parsed; `skipped-unreadable-source` means the parent snapshots came back
+ *  empty (unreadable source), so the before/after comparison had nothing to compare against. */
+type CheckStatus = 'ran' | 'skipped-no-parser' | 'skipped-no-refs' | 'skipped-unreadable-source' | 'partial-unsupported-language' | 'errored';
 interface DetectionReport {
   findings: Finding[];
   checks: {
     referenceIntegrity: CheckStatus;
     structural: CheckStatus;
   };
-  /** How many files were analyzed and whether the scope was capped — an honest coverage signal so
-   *  empty findings on a truncated scope are not read as "clean". Present only when the reference
-   *  check ran (refs available). */
+  /** Honest coverage signal so empty findings are not read as "clean": `analyzed` is the number of
+   *  files in scope, `readable` how many had loadable parent content (0 means the before/after
+   *  comparison had nothing to compare), and `truncated` whether the scope was capped. Present only
+   *  when the reference check ran (refs available). */
   scope?: {
     analyzed: number;
+    readable: number;
     truncated: boolean;
   };
 }

package/dist/types/resolution.d.ts

@@ -1,5 +1,5 @@
+import { Finding } from "./findings.js";
 import { IntraFileEditOp } from "./hints.js";
-import { Issue } from "./issue.js";
 import { ConflictType } from "./conflict.js";
 import { AiTokenUsage } from "@gitkraken/shared-tools";
 
@@ -26,7 +26,9 @@ interface Resolution {
   confidence: number;
   description: string;
   note?: string;
-  issues?: Issue[];
+  /** Non-blocking per-file findings from the consumer's validator port (post-refine). Folded into
+   *  the operation's detection findings, hence into the verdict. */
+  findings?: Finding[];
   chunks?: ResolvedChunk[];
   edits?: IntraFileEditOp[];
   metrics?: ResolutionMetrics;
@@ -74,6 +76,11 @@ interface ResolutionContext {
    *  When provided, it overrides auto-discovery and defines the incoming detection scope. */
   touchedFiles?: string[];
   refs?: ResolutionRefs;
+  /** Parent tips for reference-integrity detection's before/after comparison, when they differ from
+   *  `refs`. `refs` is the resolver's three-way source (in a rebase, the in-flight per-step state);
+   *  detection needs the two stable pre-merge branch tips. In a merge they coincide, so this is
+   *  usually left unset and detection falls back to `refs`. */
+  detectionRefs?: ResolutionRefs;
   threeWayDiff?: ThreeWayDiff;
   /** Free-text guidance from the user that applies to the whole file ("prefer logging across the
    *  board; throw on invalid input"). Rendered into the prompt as a top-level `<user-guidance>`

package/dist/types/step.d.ts

@@ -1,6 +1,6 @@
+import { DetectionReport } from "./findings.js";
 import { Resolution } from "./resolution.js";
 import { ResolverConfig } from "../ports/model.js";
-import { DetectionReport } from "./findings.js";
 
 //#region src/types/step.d.ts
 interface StepResult {
@@ -23,6 +23,16 @@ interface StepConfig extends ResolverConfig {
   defaultStrategy?: 'ai' | 'take-ours' | 'take-theirs' | 'skip' | 'deleted';
   rules?: FileRule[];
   fallbackStrategy?: 'take-ours' | 'take-theirs';
+  /** Opt in to the fix phase (default `false` → report-only). When enabled, an AI-resolved file carrying
+   *  error-severity per-file findings is routed back through refine to attempt a fix; what it cannot fix
+   *  remains in the findings. Requires `ResolverDeps.parser` — without a parser the fix phase is a no-op
+   *  and the report-only detection path runs instead. Off by default so the report-only path is unchanged. */
+  fix?: boolean;
+  /** Max per-file fix iterations (refine → re-detect the file) when `fix` is on. Default 3. */
+  fixLoopMaxIterations?: number;
+  /** Max cross-file fix rounds (route project-level breaks to their use-site file → re-detect the whole
+   *  set) when `fix` is on. Default 2. */
+  crossFileMaxIterations?: number;
 }
 //#endregion
 export { FileRule, StepConfig, StepResult };

package/dist/types/summary.d.ts

@@ -2,11 +2,21 @@ import { ResolutionStrategy } from "./resolution.js";
 import { AiTokenUsage } from "@gitkraken/shared-tools";
 
 //#region src/types/summary.d.ts
-/** A resolved file flagged for human review because its file confidence is below the threshold. */
+/** A file flagged for human review. `reason` distinguishes a low file-confidence flag from a
+ *  detection finding; `confidence` is absent for files flagged purely by a finding (e.g. an
+ *  auto-merged file with no resolution of its own). */
 interface ReviewItem {
   filePath: string;
-  confidence: number;
+  confidence?: number;
+  reason: 'low-confidence' | 'finding';
+  /** Categories of the error-severity findings on this file; present when `reason` is `'finding'`. */
+  findingCategories?: string[];
 }
+/** Suggested honest verdict for the operation. `blocked` when any error-severity finding exists;
+ *  `needs-review` when confidence is low, detection did not fully run, resolution errored, or a
+ *  warning finding exists; `clean` only when none of those apply. Advisory — the consumer owns its
+ *  own gate, but this must not read as clean when the build is known-broken. */
+type OperationVerdict = 'clean' | 'needs-review' | 'blocked';
 /** Deterministic, model-free rollup of a resolve operation. */
 interface OperationDigest {
   /** Files that produced a resolution. */
@@ -17,12 +27,21 @@ interface OperationDigest {
   byStrategy: Record<ResolutionStrategy, number>;
   /** Lowest file confidence across all resolutions; null when there are none. */
   minConfidence: number | null;
-  /** Resolutions below the review threshold, lowest confidence first. */
+  /** Files needing review — low-confidence resolutions and files with error findings, findings
+   *  first, then lowest confidence first. */
   needsReview: ReviewItem[];
   /** Files skipped by rule or because they had no markers. */
   skipped: number;
   /** Files that errored during resolution. */
   errors: number;
+  /** Whether reference-integrity detection ran to completion (every check `ran`). `false` when no
+   *  detection was attached or any check was skipped/errored — so empty findings must NOT be read
+   *  as "clean". */
+  detectionComplete: boolean;
+  /** Total detection findings across the operation. */
+  findingCount: number;
+  /** Suggested honest verdict; see {@link OperationVerdict}. */
+  verdict: OperationVerdict;
 }
 /** Result of summarizing an operation: always a digest, plus a narrative when a model was provided. */
 interface OperationSummary {
@@ -33,4 +52,4 @@ interface OperationSummary {
   usage?: AiTokenUsage;
 }
 //#endregion
-export { OperationDigest, OperationSummary, ReviewItem };
+export { OperationDigest, OperationSummary, OperationVerdict, ReviewItem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitkraken/conflict-tools",
-  "version": "0.2.4-beta.2",
+  "version": "0.2.4-beta.20",
   "description": "AI-powered git conflict resolution.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Axosoft, LLC dba GitKraken",