auditor-lambda 0.3.41 → 0.6.0

package/dist/orchestrator/reviewPackets.js

@@ -1,24 +1,70 @@
 import { createHash } from "node:crypto";
-import { isRecord } from "@audit-tools/shared";
+import { estimateTokensFromBytes, isRecord } from "@audit-tools/shared";
 import { LENS_ORDER, priorityRank, sortLenses } from "./auditTaskUtils.js";
 import { UnionFind } from "./unionFind.js";
 const DEFAULT_MAX_TASKS_PER_PACKET = 0;
 const DEFAULT_TARGET_PACKET_LINES = 8000;
 export const ESTIMATED_TOKENS_PER_LINE = 4;
 export const ESTIMATED_PACKET_PROMPT_TOKENS = 900;
-export function estimateTaskGroupTokens(tasks) {
-    let totalLines = 0;
+// Default per-packet content-token budget. Kept equal to the legacy
+// line-target × per-line estimate so byte-derived sizing lands on the same
+// thresholds as the old line-based sizing when the line fallback is in effect.
+const DEFAULT_TARGET_PACKET_TOKENS = DEFAULT_TARGET_PACKET_LINES * ESTIMATED_TOKENS_PER_LINE;
+/**
+ * Build a path → size_bytes index from a repo manifest. Byte counts are
+ * recorded during intake, so this never reads files. Review packet token
+ * estimates are derived from these bytes (Phase 2) instead of counted lines.
+ */
+export function sizeIndexFromManifest(repoManifest) {
+    if (!repoManifest)
+        return {};
+    return Object.fromEntries(repoManifest.files.map((file) => [file.path, file.size_bytes]));
+}
+/**
+ * Estimated content tokens for a single file. Prefers a byte-based estimate
+ * from `sizeIndex` (sourced from the repo manifest); falls back to the legacy
+ * line-based estimate when no positive byte count is available (e.g. manually
+ * built tasks in tests, or paths absent from the manifest).
+ */
+function pathContentTokens(owner, path, sizeIndex, lineIndex) {
+    const bytes = sizeIndex?.[path];
+    if (typeof bytes === "number" && bytes > 0) {
+        return estimateTokensFromBytes(bytes);
+    }
+    const lines = owner?.file_line_counts?.[path] ?? lineIndex?.[path] ?? 0;
+    return lines * ESTIMATED_TOKENS_PER_LINE;
+}
+/** Estimated content tokens for one task across all of its files. */
+function taskContentTokens(task, sizeIndex, lineIndex) {
+    return task.file_paths.reduce((sum, path) => sum + pathContentTokens(task, path, sizeIndex, lineIndex), 0);
+}
+/**
+ * Estimated content tokens across a set of file paths, resolving an owning task
+ * per path so the line fallback can read its `file_line_counts`. Shared files
+ * are counted once.
+ */
+function fileGroupContentTokens(filePaths, tasks, sizeIndex, lineIndex) {
+    let total = 0;
+    for (const path of filePaths) {
+        const owner = tasks.find((task) => task.file_paths.includes(path));
+        total += pathContentTokens(owner, path, sizeIndex, lineIndex);
+    }
+    return total;
+}
+export function estimateTaskGroupTokens(tasks, sizeIndex, lineIndex) {
+    let contentTokens = 0;
     for (const task of tasks) {
-        if (task.file_line_counts) {
-            for (const count of Object.values(task.file_line_counts)) {
-                totalLines += count;
-            }
-        }
+        contentTokens += taskContentTokens(task, sizeIndex, lineIndex);
     }
-    return ESTIMATED_PACKET_PROMPT_TOKENS + totalLines * ESTIMATED_TOKENS_PER_LINE;
+    return ESTIMATED_PACKET_PROMPT_TOKENS + contentTokens;
 }
 const PACKET_EXPANSION_MIN_CONFIDENCE = 0.65;
-const HIGH_FAN_DEGREE_THRESHOLD = 12;
+/**
+ * Fan-in / fan-out degree above which a node is treated as a hub. Exported so
+ * the Phase 3 delta-scope expansion skips the same hubs that packet planning
+ * skips, preventing scope blow-up through highly-connected modules.
+ */
+export const HIGH_FAN_DEGREE_THRESHOLD = 12;
 const HIGH_FAN_EXPANSION_CONFIDENCE = 0.99;
 const MAX_PACKET_KEY_EDGES = 8;
 const MAX_PACKET_BOUNDARY_FILES = 12;
@@ -86,10 +132,10 @@ function buildTaskGroups(tasks) {
     }
     return groups;
 }
-function normalizeGraphPath(path) {
+export function normalizeGraphPath(path) {
     return path.replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
 }
-function collectGraphEdges(graphBundle) {
+export function collectGraphEdges(graphBundle) {
     if (!graphBundle?.graphs) {
         return [];
     }
@@ -125,7 +171,7 @@ function collectGraphEdges(graphBundle) {
     }
     return edges;
 }
-function graphEdgeConfidence(edge) {
+export function graphEdgeConfidence(edge) {
     if (typeof edge.confidence === "number" && Number.isFinite(edge.confidence)) {
         return Math.min(1, Math.max(0, edge.confidence));
     }
@@ -140,7 +186,7 @@ function graphEdgeConfidence(edge) {
 function isConcreteGraphEdge(edge) {
     return edge.kind !== "heuristic-container-edge";
 }
-function buildGraphDegreeIndex(edges) {
+export function buildGraphDegreeIndex(edges) {
     const fanIn = new Map();
     const fanOut = new Map();
     for (const edge of edges) {
@@ -346,13 +392,11 @@ function buildBoundedClusterEdges(params) {
         const allFiles = new Set(componentEntries.flatMap((entry) => [...entry.filePaths]));
         const totalTasks = componentEntries.reduce((sum, entry) => sum + entry.taskCount, 0);
         const clusterTasks = entries.flatMap((entry) => entry.tasks);
-        const totalLines = [...allFiles].reduce((sum, path) => {
-            const owner = clusterTasks.find((task) => task.file_paths.includes(path));
-            return sum + (owner ? lineCountForPath(owner, path, params.lineIndex) : 0);
-        }, 0);
+        const totalContentTokens = fileGroupContentTokens(allFiles, clusterTasks, params.sizeIndex, params.lineIndex);
         if (allFiles.size > MAX_SUBSYSTEM_CLUSTER_FILES ||
             totalTasks > MAX_SUBSYSTEM_CLUSTER_TASKS ||
-            totalLines > (params.targetPacketLines ?? DEFAULT_TARGET_PACKET_LINES)) {
+            totalContentTokens >
+                (params.targetPacketTokens ?? DEFAULT_TARGET_PACKET_TOKENS)) {
             continue;
         }
         for (let index = 1; index < componentEntries.length; index++) {
@@ -370,7 +414,7 @@ function buildBoundedClusterEdges(params) {
     }
     return clusterEdges.sort(compareGraphEdges);
 }
-function buildSubsystemClusterEdges(groups, graphEdges, lineIndex, targetPacketLines = DEFAULT_TARGET_PACKET_LINES) {
+function buildSubsystemClusterEdges(groups, graphEdges, lineIndex, sizeIndex, targetPacketTokens = DEFAULT_TARGET_PACKET_TOKENS) {
     return buildBoundedClusterEdges({
         groups,
         graphEdges,
@@ -379,7 +423,8 @@ function buildSubsystemClusterEdges(groups, graphEdges, lineIndex, targetPacketL
         edgeConfidence: SUBSYSTEM_CLUSTER_CONFIDENCE,
         reasonForCluster: (root, fileCount) => `Bounded subsystem cluster '${root}' groups ${fileCount} file(s) without stronger graph evidence.`,
         lineIndex,
-        targetPacketLines,
+        sizeIndex,
+        targetPacketTokens,
     });
 }
 function packageManifestRoot(path) {
@@ -479,7 +524,7 @@ function packageOwnershipRootForTasks(tasks, packageRoots) {
     const roots = new Set(rootsForFiles);
     return roots.size === 1 ? [...roots][0] : undefined;
 }
-function buildPackageOwnershipClusterEdges(groups, graphEdges, lineIndex, targetPacketLines = DEFAULT_TARGET_PACKET_LINES) {
+function buildPackageOwnershipClusterEdges(groups, graphEdges, lineIndex, sizeIndex, targetPacketTokens = DEFAULT_TARGET_PACKET_TOKENS) {
     const packageRoots = collectPackageOwnershipRoots(groups, graphEdges);
     if (packageRoots.size === 0) {
         return [];
@@ -492,7 +537,8 @@ function buildPackageOwnershipClusterEdges(groups, graphEdges, lineIndex, target
         edgeConfidence: PACKAGE_OWNERSHIP_CLUSTER_CONFIDENCE,
         reasonForCluster: (root, fileCount) => `Package ownership root '${root}' groups ${fileCount} file(s) across bounded package subdirectories.`,
         lineIndex,
-        targetPacketLines,
+        sizeIndex,
+        targetPacketTokens,
     });
 }
 function collectModuleOwnershipRoots(groups, graphEdges) {
@@ -538,7 +584,7 @@ function moduleOwnershipRootForTasks(tasks, moduleRoots) {
     const roots = new Set(rootsForFiles);
     return roots.size === 1 ? [...roots][0] : undefined;
 }
-function buildModuleOwnershipClusterEdges(groups, graphEdges, lineIndex, targetPacketLines = DEFAULT_TARGET_PACKET_LINES) {
+function buildModuleOwnershipClusterEdges(groups, graphEdges, lineIndex, sizeIndex, targetPacketTokens = DEFAULT_TARGET_PACKET_TOKENS) {
     const moduleRoots = collectModuleOwnershipRoots(groups, graphEdges);
     if (moduleRoots.size === 0) {
         return [];
@@ -557,7 +603,8 @@ function buildModuleOwnershipClusterEdges(groups, graphEdges, lineIndex, targetP
                 : `Module ownership root '${root}' from project configuration groups ${fileCount} file(s) across bounded subdirectories.`;
         },
         lineIndex,
-        targetPacketLines,
+        sizeIndex,
+        targetPacketTokens,
     });
 }
 function buildEntrypointFlowBridgeEdges(groups, graphEdges, graphBundle) {
@@ -644,18 +691,18 @@ function buildEntrypointFlowBridgeEdges(groups, graphEdges, graphBundle) {
     }
     return [...bridgeEdges.values()].sort(compareGraphEdges);
 }
-function buildPlanningGraphEdges(groups, graphEdges, graphBundle, lineIndex, targetPacketLines = DEFAULT_TARGET_PACKET_LINES) {
+function buildPlanningGraphEdges(groups, graphEdges, graphBundle, lineIndex, sizeIndex, targetPacketTokens = DEFAULT_TARGET_PACKET_TOKENS) {
     const bridgeEdges = buildEntrypointFlowBridgeEdges(groups, graphEdges, graphBundle);
     const graphWithBridges = bridgeEdges.length > 0 ? [...graphEdges, ...bridgeEdges] : graphEdges;
-    const subsystemEdges = buildSubsystemClusterEdges(groups, graphWithBridges, lineIndex, targetPacketLines);
+    const subsystemEdges = buildSubsystemClusterEdges(groups, graphWithBridges, lineIndex, sizeIndex, targetPacketTokens);
     const graphWithSubsystems = subsystemEdges.length > 0
         ? [...graphWithBridges, ...subsystemEdges]
         : graphWithBridges;
-    const packageOwnershipEdges = buildPackageOwnershipClusterEdges(groups, graphWithSubsystems, lineIndex, targetPacketLines);
+    const packageOwnershipEdges = buildPackageOwnershipClusterEdges(groups, graphWithSubsystems, lineIndex, sizeIndex, targetPacketTokens);
     const graphWithPackageOwnership = packageOwnershipEdges.length > 0
         ? [...graphWithSubsystems, ...packageOwnershipEdges]
         : graphWithSubsystems;
-    const moduleOwnershipEdges = buildModuleOwnershipClusterEdges(groups, graphWithPackageOwnership, lineIndex, targetPacketLines);
+    const moduleOwnershipEdges = buildModuleOwnershipClusterEdges(groups, graphWithPackageOwnership, lineIndex, sizeIndex, targetPacketTokens);
     return moduleOwnershipEdges.length > 0
         ? [...graphWithPackageOwnership, ...moduleOwnershipEdges]
         : graphWithPackageOwnership;
@@ -781,7 +828,8 @@ function chunkPacketTasks(tasks, options) {
     let current = [];
     for (const task of tasks.sort(compareTasksForPacket)) {
         const isolatedLargeFileTask = task.file_paths.length === 1 &&
-            taskLineCount(task, options.lineIndex) > options.targetPacketLines;
+            taskContentTokens(task, options.sizeIndex, options.lineIndex) >
+                options.targetPacketTokens;
         if (isolatedLargeFileTask) {
             if (current.length > 0) {
                 chunks.push(current);
@@ -792,13 +840,10 @@ function chunkPacketTasks(tasks, options) {
         }
         const candidate = [...current, task];
         const uniquePaths = new Set(candidate.flatMap((item) => item.file_paths));
-        const candidateLines = [...uniquePaths].reduce((sum, path) => {
-            const owner = candidate.find((item) => item.file_paths.includes(path));
-            return sum + (owner ? lineCountForPath(owner, path, options.lineIndex) : 0);
-        }, 0);
+        const candidateContentTokens = fileGroupContentTokens(uniquePaths, candidate, options.sizeIndex, options.lineIndex);
         const wouldExceedTaskCount = options.maxTasksPerPacket > 0 && current.length > 0 && candidate.length > options.maxTasksPerPacket;
-        const wouldExceedLines = current.length > 0 && candidateLines > options.targetPacketLines;
-        if (wouldExceedTaskCount || wouldExceedLines) {
+        const wouldExceedTokens = current.length > 0 && candidateContentTokens > options.targetPacketTokens;
+        if (wouldExceedTaskCount || wouldExceedTokens) {
             chunks.push(current);
             current = [];
         }
@@ -820,7 +865,7 @@ function mergeGraphConnectedGroups(groups, graphEdges) {
     }
     return [...merged.values()];
 }
-function buildPacket(tasks, packetIndex, lineIndex, graphEdges = [], graphBundle) {
+function buildPacket(tasks, packetIndex, lineIndex, sizeIndex, graphEdges = [], graphBundle) {
     const filePaths = [...new Set(tasks.flatMap((task) => task.file_paths))].sort((a, b) => a.localeCompare(b));
     const graphContext = buildPacketGraphContext(filePaths, graphEdges, graphBundle);
     const fileLineCounts = Object.fromEntries(filePaths.map((path) => {
@@ -828,6 +873,8 @@ function buildPacket(tasks, packetIndex, lineIndex, graphEdges = [], graphBundle
         return [path, owner ? lineCountForPath(owner, path, lineIndex) : 0];
     }));
     const totalLines = Object.values(fileLineCounts).reduce((sum, value) => sum + value, 0);
+    const estimatedTokens = ESTIMATED_PACKET_PROMPT_TOKENS +
+        fileGroupContentTokens(filePaths, tasks, sizeIndex, lineIndex);
     const priority = tasks.reduce((highest, task) => priorityRank(task.priority) > priorityRank(highest)
         ? normalizePriority(task.priority)
         : highest, "low");
@@ -863,19 +910,18 @@ function buildPacket(tasks, packetIndex, lineIndex, graphEdges = [], graphBundle
             : undefined,
         quality: graphContext.quality,
         rationale: `${baseRationale}${graphRationale}`,
-        estimated_tokens: ESTIMATED_PACKET_PROMPT_TOKENS + totalLines * ESTIMATED_TOKENS_PER_LINE,
+        estimated_tokens: estimatedTokens,
     };
 }
 function buildReviewPacketPlanningData(tasks, options = {}) {
     const maxTasksPerPacket = options.maxTasksPerPacket ?? DEFAULT_MAX_TASKS_PER_PACKET;
-    const configuredTargetLines = options.targetPacketLines ?? DEFAULT_TARGET_PACKET_LINES;
-    const targetPacketLines = options.maxContextTokens != null
-        ? Math.min(configuredTargetLines, Math.max(1, Math.floor((options.maxContextTokens - ESTIMATED_PACKET_PROMPT_TOKENS) /
-            ESTIMATED_TOKENS_PER_LINE)))
-        : configuredTargetLines;
+    const configuredTargetTokens = options.targetPacketTokens ?? DEFAULT_TARGET_PACKET_TOKENS;
+    const targetPacketTokens = options.maxContextTokens != null
+        ? Math.min(configuredTargetTokens, Math.max(1, options.maxContextTokens - ESTIMATED_PACKET_PROMPT_TOKENS))
+        : configuredTargetTokens;
     const graphEdges = collectGraphEdges(options.graphBundle);
     const groups = buildTaskGroups(tasks);
-    const planningGraphEdges = buildPlanningGraphEdges(groups, graphEdges, options.graphBundle, options.lineIndex, targetPacketLines);
+    const planningGraphEdges = buildPlanningGraphEdges(groups, graphEdges, options.graphBundle, options.lineIndex, options.sizeIndex, targetPacketTokens);
     const packets = [];
     let packetIndex = 0;
     const groupedTasks = mergeGraphConnectedGroups(groups, planningGraphEdges).sort((a, b) => {
@@ -888,10 +934,11 @@ function buildReviewPacketPlanningData(tasks, options = {}) {
     for (const group of groupedTasks) {
         for (const chunk of chunkPacketTasks(group, {
             lineIndex: options.lineIndex,
+            sizeIndex: options.sizeIndex,
             maxTasksPerPacket,
-            targetPacketLines,
+            targetPacketTokens,
         })) {
-            packets.push(buildPacket(chunk, packetIndex, options.lineIndex, planningGraphEdges, options.graphBundle));
+            packets.push(buildPacket(chunk, packetIndex, options.lineIndex, options.sizeIndex, planningGraphEdges, options.graphBundle));
             packetIndex += 1;
         }
     }

package/dist/orchestrator/runtimeValidation.js

@@ -1,4 +1,4 @@
-import { access, readFile } from "node:fs/promises";
+import { discoverProjectCommands } from "@audit-tools/shared";
 function checksForFlow(requiredLenses) {
     const checks = [];
     if (requiredLenses.includes("security")) {
@@ -15,37 +15,10 @@ function checksForFlow(requiredLenses) {
     }
     return checks;
 }
-async function exists(path) {
-    try {
-        await access(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 export async function discoverRuntimeValidationCommand(root) {
-    const packageJsonPath = `${root}/package.json`;
-    if (await exists(packageJsonPath)) {
-        try {
-            const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
-            const testScript = packageJson.scripts?.test?.trim();
-            if (testScript &&
-                !/no test specified/i.test(testScript)) {
-                return ["npm", "test"];
-            }
-        }
-        catch {
-            // ignore unreadable package.json for runtime discovery
-        }
-    }
-    if (await exists(`${root}/go.mod`)) {
-        return ["go", "test", "./..."];
-    }
-    if (await exists(`${root}/pyproject.toml`) || await exists(`${root}/pytest.ini`)) {
-        return ["python", "-m", "pytest"];
-    }
-    return undefined;
+    // Shared discovery (Node test script → Go → Python) is the single source of
+    // truth; the runtime-validation command is the discovered test command.
+    return discoverProjectCommands(root).test;
 }
 export function buildRuntimeValidationTasks(params) {
     if (!params.command) {

package/dist/orchestrator/scope.d.ts

@@ -0,0 +1,62 @@
+import type { GraphBundle } from "@audit-tools/shared";
+import type { ArtifactBundle } from "../io/artifacts.js";
+import type { CoverageMatrix } from "../types.js";
+import type { AuditScopeBudget, AuditScopeManifest } from "../types/auditScope.js";
+/** Default cap on in-scope files (seeds + expanded) before expansion stops. */
+export declare const DEFAULT_SCOPE_MAX_FILES = 200;
+/** Graph edges below this confidence are never traversed during expansion. */
+export declare const SCOPE_EDGE_CONFIDENCE_FLOOR = 0.5;
+/**
+ * Expansion stops along a path once the accumulated path-confidence (the product
+ * of the traversed edge confidences) drops below this floor. With no fixed hop
+ * count, this — together with hub-skipping and the file budget — bounds the
+ * frontier deterministically.
+ */
+export declare const SCOPE_MIN_FRONTIER_CONFIDENCE = 0.5;
+export interface ComputeAuditScopeInput {
+    /** The git ref the delta is measured against. */
+    since: string;
+    /** Raw changed paths (git output, posix-relative). */
+    changed: string[];
+    /** Canonical auditable file paths (repo-manifest paths, non-excluded). */
+    includedFiles: string[];
+    /** Dependency graph used to expand from seeds to neighbours. */
+    graphBundle?: GraphBundle;
+    budget?: AuditScopeBudget;
+}
+/**
+ * Deterministic priority-frontier expansion (Phase 3). Starting from the changed
+ * files (seeds), walk the dependency graph outward, always visiting the neighbour
+ * with the highest accumulated path-confidence first (tie-broken by path). High
+ * fan-in/out hubs are skipped so a single change near a hub does not drag the
+ * whole repo into scope, low-confidence edges are dropped, and expansion halts at
+ * the file budget or when the best remaining frontier confidence falls below the
+ * floor. Same inputs → identical scope.
+ */
+export declare function computeAuditScope(input: ComputeAuditScopeInput): AuditScopeManifest;
+/** A full-audit scope (the default, and every fallback). */
+export declare function fullAuditScope(budget?: AuditScopeBudget, droppedNote?: string): AuditScopeManifest;
+export interface ResolveAuditScopeInput {
+    root?: string;
+    /** The `--since` ref, if any. Absent/empty → full audit. */
+    since?: string;
+    bundle: ArtifactBundle;
+    budget?: AuditScopeBudget;
+}
+/**
+ * Resolve the scope for a planning run. Returns a full-audit scope unless a
+ * `--since` ref was supplied against a real git repository; an unusable ref or
+ * missing root degrades to a full audit with an honest note. Reads the auditable
+ * file set from the repo manifest + disposition (the same lookup the graph
+ * extractor uses) and the dependency graph from the bundle.
+ */
+export declare function resolveAuditScope(input: ResolveAuditScopeInput): AuditScopeManifest;
+/**
+ * Apply a delta scope to a freshly-built coverage matrix. In-scope files (seeds
+ * + expanded neighbours) keep their fresh `pending` status to be re-audited.
+ * Out-of-scope files inherit a prior `complete` record verbatim when present (so
+ * previously-finished work is preserved, not re-run), and are otherwise excluded
+ * from this run with `classification_status: "out_of_scope_delta"`. Deterministic
+ * exclusions (non-auditable/trivial) are left untouched. A full scope is a no-op.
+ */
+export declare function applyScopeToCoverage(coverage: CoverageMatrix, scope: AuditScopeManifest, priorCoverage?: CoverageMatrix): CoverageMatrix;

package/dist/orchestrator/scope.js

@@ -0,0 +1,227 @@
+import { changedFiles, gitRefExists, isGitRepo } from "@audit-tools/shared";
+import { buildDispositionMap } from "../extractors/disposition.js";
+import { buildPathLookup } from "../extractors/graph.js";
+import { HIGH_FAN_DEGREE_THRESHOLD, buildGraphDegreeIndex, collectGraphEdges, graphEdgeConfidence, normalizeGraphPath, } from "./reviewPackets.js";
+/** Default cap on in-scope files (seeds + expanded) before expansion stops. */
+export const DEFAULT_SCOPE_MAX_FILES = 200;
+/** Graph edges below this confidence are never traversed during expansion. */
+export const SCOPE_EDGE_CONFIDENCE_FLOOR = 0.5;
+/**
+ * Expansion stops along a path once the accumulated path-confidence (the product
+ * of the traversed edge confidences) drops below this floor. With no fixed hop
+ * count, this — together with hub-skipping and the file budget — bounds the
+ * frontier deterministically.
+ */
+export const SCOPE_MIN_FRONTIER_CONFIDENCE = 0.5;
+/**
+ * Deterministic priority-frontier expansion (Phase 3). Starting from the changed
+ * files (seeds), walk the dependency graph outward, always visiting the neighbour
+ * with the highest accumulated path-confidence first (tie-broken by path). High
+ * fan-in/out hubs are skipped so a single change near a hub does not drag the
+ * whole repo into scope, low-confidence edges are dropped, and expansion halts at
+ * the file budget or when the best remaining frontier confidence falls below the
+ * floor. Same inputs → identical scope.
+ */
+export function computeAuditScope(input) {
+    const maxFiles = input.budget?.max_files ?? DEFAULT_SCOPE_MAX_FILES;
+    // normalized graph key -> canonical (repo-manifest) path for auditable files.
+    const canonicalByNorm = new Map();
+    for (const file of input.includedFiles) {
+        const key = normalizeGraphPath(file);
+        if (!canonicalByNorm.has(key)) {
+            canonicalByNorm.set(key, file);
+        }
+    }
+    // Seeds = changed files that are auditable (present in the manifest). Changed
+    // files that are excluded, deleted, or otherwise absent simply drop out.
+    const seedKeys = [];
+    const seedSeen = new Set();
+    for (const path of input.changed) {
+        const key = normalizeGraphPath(path);
+        if (canonicalByNorm.has(key) && !seedSeen.has(key)) {
+            seedSeen.add(key);
+            seedKeys.push(key);
+        }
+    }
+    const edges = collectGraphEdges(input.graphBundle);
+    const degree = buildGraphDegreeIndex(edges);
+    const isHub = (key) => (degree.fanIn.get(key) ?? 0) > HIGH_FAN_DEGREE_THRESHOLD ||
+        (degree.fanOut.get(key) ?? 0) > HIGH_FAN_DEGREE_THRESHOLD;
+    // Bidirectional adjacency: a change to a file is relevant to what it depends
+    // on AND to what depends on it. Edges below the confidence floor are dropped.
+    const adjacency = new Map();
+    const addEdge = (from, to, confidence) => {
+        const list = adjacency.get(from) ?? [];
+        list.push({ to, confidence });
+        adjacency.set(from, list);
+    };
+    for (const edge of edges) {
+        const confidence = graphEdgeConfidence(edge);
+        if (confidence < SCOPE_EDGE_CONFIDENCE_FLOOR) {
+            continue;
+        }
+        const from = normalizeGraphPath(edge.from);
+        const to = normalizeGraphPath(edge.to);
+        addEdge(from, to, confidence);
+        addEdge(to, from, confidence);
+    }
+    // Max-product shortest-path frontier. `best` holds the highest accumulated
+    // confidence discovered for each node; seeds start at 1.
+    const best = new Map();
+    for (const key of seedKeys) {
+        best.set(key, 1);
+    }
+    const visited = new Set();
+    const inScope = new Set(seedKeys);
+    const expandedKeys = [];
+    let budgetHit = false;
+    for (;;) {
+        let pick;
+        let pickConfidence = -1;
+        for (const [key, confidence] of best) {
+            if (visited.has(key))
+                continue;
+            if (confidence > pickConfidence ||
+                (confidence === pickConfidence && (pick === undefined || key < pick))) {
+                pick = key;
+                pickConfidence = confidence;
+            }
+        }
+        if (pick === undefined || pickConfidence < SCOPE_MIN_FRONTIER_CONFIDENCE) {
+            break;
+        }
+        visited.add(pick);
+        // Record newly-reached auditable files (seeds are already in scope).
+        if (canonicalByNorm.has(pick) && !inScope.has(pick)) {
+            if (inScope.size >= maxFiles) {
+                budgetHit = true;
+                break;
+            }
+            inScope.add(pick);
+            expandedKeys.push(pick);
+        }
+        // Relax neighbours, skipping hubs (never traverse through or into a hub) and
+        // non-auditable nodes.
+        for (const neighbour of adjacency.get(pick) ?? []) {
+            if (isHub(neighbour.to) || !canonicalByNorm.has(neighbour.to)) {
+                continue;
+            }
+            const candidate = pickConfidence * neighbour.confidence;
+            if (candidate < SCOPE_MIN_FRONTIER_CONFIDENCE) {
+                continue;
+            }
+            if (candidate > (best.get(neighbour.to) ?? 0)) {
+                best.set(neighbour.to, candidate);
+            }
+        }
+    }
+    const seedFiles = seedKeys
+        .map((key) => canonicalByNorm.get(key))
+        .sort((a, b) => a.localeCompare(b));
+    const expandedFiles = expandedKeys
+        .map((key) => canonicalByNorm.get(key))
+        .sort((a, b) => a.localeCompare(b));
+    const notes = [];
+    if (seedFiles.length === 0) {
+        notes.push(`No auditable files changed since ${input.since}.`);
+    }
+    if (budgetHit) {
+        notes.push(`Expansion stopped at the ${maxFiles}-file budget; some graph neighbours were left out of scope.`);
+    }
+    return {
+        mode: "delta",
+        since: input.since,
+        seed_files: seedFiles,
+        expanded_files: expandedFiles,
+        budget: { max_files: maxFiles },
+        ...(notes.length > 0 ? { dropped_note: notes.join(" ") } : {}),
+    };
+}
+/** A full-audit scope (the default, and every fallback). */
+export function fullAuditScope(budget, droppedNote) {
+    return {
+        mode: "full",
+        since: null,
+        seed_files: [],
+        expanded_files: [],
+        budget: { max_files: budget?.max_files ?? DEFAULT_SCOPE_MAX_FILES },
+        ...(droppedNote ? { dropped_note: droppedNote } : {}),
+    };
+}
+/**
+ * Resolve the scope for a planning run. Returns a full-audit scope unless a
+ * `--since` ref was supplied against a real git repository; an unusable ref or
+ * missing root degrades to a full audit with an honest note. Reads the auditable
+ * file set from the repo manifest + disposition (the same lookup the graph
+ * extractor uses) and the dependency graph from the bundle.
+ */
+export function resolveAuditScope(input) {
+    const since = input.since?.trim();
+    if (!since) {
+        return fullAuditScope(input.budget);
+    }
+    if (!input.root) {
+        return fullAuditScope(input.budget, `--since '${since}' was ignored: no repository root was available, so a full audit ran.`);
+    }
+    if (!isGitRepo(input.root)) {
+        return fullAuditScope(input.budget, `--since '${since}' was ignored: '${input.root}' is not a git repository, so a full audit ran.`);
+    }
+    if (!gitRefExists(input.root, since)) {
+        return fullAuditScope(input.budget, `--since '${since}' could not be resolved to a commit, so a full audit ran.`);
+    }
+    const dispositionMap = buildDispositionMap(input.bundle.file_disposition);
+    const includedFiles = input.bundle.repo_manifest
+        ? [
+            ...new Set(buildPathLookup(input.bundle.repo_manifest, dispositionMap).values()),
+        ].sort((a, b) => a.localeCompare(b))
+        : [];
+    return computeAuditScope({
+        since,
+        changed: changedFiles(input.root, since),
+        includedFiles,
+        graphBundle: input.bundle.graph_bundle,
+        budget: input.budget,
+    });
+}
+/**
+ * Apply a delta scope to a freshly-built coverage matrix. In-scope files (seeds
+ * + expanded neighbours) keep their fresh `pending` status to be re-audited.
+ * Out-of-scope files inherit a prior `complete` record verbatim when present (so
+ * previously-finished work is preserved, not re-run), and are otherwise excluded
+ * from this run with `classification_status: "out_of_scope_delta"`. Deterministic
+ * exclusions (non-auditable/trivial) are left untouched. A full scope is a no-op.
+ */
+export function applyScopeToCoverage(coverage, scope, priorCoverage) {
+    if (scope.mode !== "delta") {
+        return coverage;
+    }
+    const inScope = new Set([
+        ...scope.seed_files,
+        ...scope.expanded_files,
+    ]);
+    const priorByPath = new Map((priorCoverage?.files ?? []).map((file) => [file.path, file]));
+    for (const file of coverage.files) {
+        if (file.audit_status === "excluded") {
+            continue;
+        }
+        if (inScope.has(file.path)) {
+            continue;
+        }
+        const prior = priorByPath.get(file.path);
+        if (prior && prior.audit_status === "complete") {
+            file.required_lenses = [...prior.required_lenses];
+            file.completed_lenses = [...prior.completed_lenses];
+            file.unit_ids = [...prior.unit_ids];
+            file.audit_status = "complete";
+            file.classification_status = prior.classification_status;
+        }
+        else {
+            file.required_lenses = [];
+            file.completed_lenses = [];
+            file.unit_ids = [];
+            file.audit_status = "excluded";
+            file.classification_status = "out_of_scope_delta";
+        }
+    }
+    return coverage;
+}

package/dist/orchestrator/state.js

@@ -29,6 +29,7 @@ export function deriveAuditState(bundle) {
         "critical_flows.json",
         "risk_register.json",
     ], structureReady)));
+    obligations.push(obligation("graph_enrichment_current", staleOrSatisfied(staleArtifacts, ["analyzer_capability.json"], has(bundle.analyzer_capability))));
     obligations.push(obligation("design_assessment_current", staleOrSatisfied(staleArtifacts, ["design_assessment.json"], has(bundle.design_assessment))));
     obligations.push(obligation("design_review_completed", bundle.design_assessment?.reviewed ? "satisfied" : "missing"));
     const planningReady = has(bundle.coverage_matrix) &&
@@ -69,6 +70,7 @@ export function deriveAuditState(bundle) {
         ? "No deterministic runtime validation tasks were planned."
         : undefined));
     obligations.push(obligation("synthesis_current", staleOrSatisfied(staleArtifacts, ["audit-report.md"], has(bundle.audit_report))));
+    obligations.push(obligation("synthesis_narrative_current", staleOrSatisfied(staleArtifacts, ["synthesis-narrative.json"], has(bundle.synthesis_narrative))));
     let status = "not_started";
     if (!has(bundle.repo_manifest)) {
         status = "not_started";