auditor-lambda 0.7.0 → 0.9.0

package/dist/reporting/workBlocks.js

@@ -54,14 +54,17 @@ function computeDependencies(params) {
         }
     }
     for (const flow of params.criticalFlows?.flows ?? []) {
-        const flowBlocks = new Set();
+        // Order blocks by first appearance along the flow path so dependency
+        // direction follows the flow's traversal order, not block-id lexical order.
+        const ordered = [];
+        const seen = new Set();
         for (const path of flow.paths) {
             const blockId = blockByFile.get(path);
-            if (blockId) {
-                flowBlocks.add(blockId);
+            if (blockId && !seen.has(blockId)) {
+                seen.add(blockId);
+                ordered.push(blockId);
             }
         }
-        const ordered = [...flowBlocks].sort();
         for (let i = 1; i < ordered.length; i++) {
             dependsOn.get(ordered[i - 1])?.add(ordered[i]);
         }

package/dist/types/reviewPlanning.d.ts

@@ -36,6 +36,28 @@ export interface ReviewPacket {
     rationale: string;
     estimated_tokens: number;
 }
+/**
+ * Aggregate quality signals for a planned set of review packets — cohesion,
+ * boundary-crossing counts, and the weakly-explained-packet diagnostics. Promoted
+ * from an inline anonymous object on {@link AuditPlanMetrics} so it can be named
+ * and referenced.
+ */
+export interface PacketQuality {
+    average_cohesion_score: number;
+    boundary_crossing_count: number;
+    merge_edge_kind_counts: Record<string, number>;
+    boundary_edge_kind_counts: Record<string, number>;
+    orphan_task_count: number;
+    high_fan_in_file_count: number;
+    high_fan_out_file_count: number;
+    weakly_explained_gap_counts: Record<WeaklyExplainedPacketSample["primary_gap"], number>;
+    weakly_explained_file_extension_counts: Record<string, number>;
+    weakly_explained_packet_count: number;
+    weakly_explained_packet_ids: string[];
+    weakly_explained_packet_samples: WeaklyExplainedPacketSample[];
+    largest_unexplained_packet_id?: string;
+    largest_unexplained_packet_files: number;
+}
 export interface AuditPlanMetrics {
     generated_at: string;
     task_count: number;
@@ -55,22 +77,7 @@ export interface AuditPlanMetrics {
     largest_packet_id?: string;
     lens_task_counts: Partial<Record<Lens, number>>;
     priority_task_counts: Record<NonNullable<AuditTask["priority"]>, number>;
-    packet_quality: {
-        average_cohesion_score: number;
-        boundary_crossing_count: number;
-        merge_edge_kind_counts: Record<string, number>;
-        boundary_edge_kind_counts: Record<string, number>;
-        orphan_task_count: number;
-        high_fan_in_file_count: number;
-        high_fan_out_file_count: number;
-        weakly_explained_gap_counts: Record<WeaklyExplainedPacketSample["primary_gap"], number>;
-        weakly_explained_file_extension_counts: Record<string, number>;
-        weakly_explained_packet_count: number;
-        weakly_explained_packet_ids: string[];
-        weakly_explained_packet_samples: WeaklyExplainedPacketSample[];
-        largest_unexplained_packet_id?: string;
-        largest_unexplained_packet_files: number;
-    };
+    packet_quality: PacketQuality;
     packet_size: {
         single_task_packets: number;
         multi_task_packets: number;

package/dist/validation/auditResults.js

@@ -1,4 +1,4 @@
-import { describeValue, formatValidationIssues, isRecord, } from "@audit-tools/shared";
+import { describeValue, formatValidationIssues, isRecord, VALID_LENSES, VALID_SEVERITIES, VALID_CONFIDENCES, } from "@audit-tools/shared";
 export function normalizeCoveragePath(path) {
     return path.replace(/\\/g, "/").replace(/^\.\//, "");
 }
@@ -11,23 +11,11 @@ const REQUIRED_FINDING_FIELDS = [
     "lens",
     "summary",
 ];
-const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low", "info"]);
-const VALID_CONFIDENCES = new Set(["high", "medium", "low"]);
+// Severity / confidence / lens validity now come from the canonical shared
+// vocabulary (`@audit-tools/shared`); previously each was re-defined here and
+// drifted from the shared Lens / FindingSeverity / FindingConfidence types.
 const VALID_PRIORITIES = new Set(["high", "medium", "low"]);
 const LENS_VERIFICATION_TAG = "lens_verification";
-const VALID_LENSES = new Set([
-    "correctness",
-    "architecture",
-    "maintainability",
-    "security",
-    "reliability",
-    "performance",
-    "data_integrity",
-    "tests",
-    "operability",
-    "config_deployment",
-    "observability",
-]);
 function pushIssue(issues, params) {
     issues.push({
         ...params,
@@ -77,20 +65,12 @@ function validateExpectedStringField(value, label, expected, taskId, resultIndex
         });
     }
 }
-function validateFinding(finding, label, taskId, resultIndex) {
-    const issues = [];
-    if (!isRecord(finding)) {
-        pushIssue(issues, {
-            result_index: resultIndex,
-            task_id: taskId,
-            field: label,
-            message: `${label} must be an object, got ${describeValue(finding)}.`,
-        });
-        return issues;
-    }
+function validateFindingRequiredFields(finding, label, taskId, resultIndex, issues) {
     for (const field of REQUIRED_FINDING_FIELDS) {
         validateRequiredStringField(finding[field], `${label}.${field}`, taskId, resultIndex, issues);
     }
+}
+function validateFindingEnums(finding, label, taskId, resultIndex, issues) {
     if (typeof finding.severity === "string" &&
         !VALID_SEVERITIES.has(finding.severity)) {
         pushIssue(issues, {
@@ -117,6 +97,8 @@ function validateFinding(finding, label, taskId, resultIndex) {
             message: `Invalid lens '${finding.lens}'. Must be one of: ${[...VALID_LENSES].join(", ")}.`,
         });
     }
+}
+function validateAffectedFiles(finding, label, taskId, resultIndex, issues) {
     const affectedFiles = finding.affected_files;
     if (!Array.isArray(affectedFiles) || affectedFiles.length === 0) {
         pushIssue(issues, {
@@ -125,57 +107,58 @@ function validateFinding(finding, label, taskId, resultIndex) {
             field: `${label}.affected_files`,
             message: "affected_files must be a non-empty array.",
         });
+        return;
     }
-    else {
-        for (let k = 0; k < affectedFiles.length; k++) {
-            const item = affectedFiles[k];
-            if (!isRecord(item)) {
-                pushIssue(issues, {
-                    result_index: resultIndex,
-                    task_id: taskId,
-                    field: `${label}.affected_files[${k}]`,
-                    message: `affected_files[${k}] must be an object, got ${describeValue(item)}.`,
-                });
-                continue;
-            }
-            if (!isNonEmptyString(item.path)) {
-                pushIssue(issues, {
-                    result_index: resultIndex,
-                    task_id: taskId,
-                    field: `${label}.affected_files[${k}].path`,
-                    message: "affected_files entry has an empty path.",
-                });
-            }
-            if (item.line_start !== undefined &&
-                !Number.isInteger(item.line_start)) {
-                pushIssue(issues, {
-                    result_index: resultIndex,
-                    task_id: taskId,
-                    field: `${label}.affected_files[${k}].line_start`,
-                    message: `affected_files[${k}].line_start must be an integer, got ${describeValue(item.line_start)}.`,
-                });
-            }
-            if (item.line_end !== undefined &&
-                !Number.isInteger(item.line_end)) {
-                pushIssue(issues, {
-                    result_index: resultIndex,
-                    task_id: taskId,
-                    field: `${label}.affected_files[${k}].line_end`,
-                    message: `affected_files[${k}].line_end must be an integer, got ${describeValue(item.line_end)}.`,
-                });
-            }
-            if (Number.isInteger(item.line_start) &&
-                Number.isInteger(item.line_end) &&
-                Number(item.line_start) > Number(item.line_end)) {
-                pushIssue(issues, {
-                    result_index: resultIndex,
-                    task_id: taskId,
-                    field: `${label}.affected_files[${k}]`,
-                    message: "affected_files line_start must be less than or equal to line_end.",
-                });
-            }
+    for (let k = 0; k < affectedFiles.length; k++) {
+        const item = affectedFiles[k];
+        if (!isRecord(item)) {
+            pushIssue(issues, {
+                result_index: resultIndex,
+                task_id: taskId,
+                field: `${label}.affected_files[${k}]`,
+                message: `affected_files[${k}] must be an object, got ${describeValue(item)}.`,
+            });
+            continue;
+        }
+        if (!isNonEmptyString(item.path)) {
+            pushIssue(issues, {
+                result_index: resultIndex,
+                task_id: taskId,
+                field: `${label}.affected_files[${k}].path`,
+                message: "affected_files entry has an empty path.",
+            });
+        }
+        if (item.line_start !== undefined &&
+            !Number.isInteger(item.line_start)) {
+            pushIssue(issues, {
+                result_index: resultIndex,
+                task_id: taskId,
+                field: `${label}.affected_files[${k}].line_start`,
+                message: `affected_files[${k}].line_start must be an integer, got ${describeValue(item.line_start)}.`,
+            });
+        }
+        if (item.line_end !== undefined &&
+            !Number.isInteger(item.line_end)) {
+            pushIssue(issues, {
+                result_index: resultIndex,
+                task_id: taskId,
+                field: `${label}.affected_files[${k}].line_end`,
+                message: `affected_files[${k}].line_end must be an integer, got ${describeValue(item.line_end)}.`,
+            });
+        }
+        if (Number.isInteger(item.line_start) &&
+            Number.isInteger(item.line_end) &&
+            Number(item.line_start) > Number(item.line_end)) {
+            pushIssue(issues, {
+                result_index: resultIndex,
+                task_id: taskId,
+                field: `${label}.affected_files[${k}]`,
+                message: "affected_files line_start must be less than or equal to line_end.",
+            });
         }
     }
+}
+function validateEvidence(finding, label, taskId, resultIndex, issues) {
     const evidence = finding.evidence;
     if (!Array.isArray(evidence) || evidence.length === 0) {
         pushIssue(issues, {
@@ -184,33 +167,52 @@ function validateFinding(finding, label, taskId, resultIndex) {
             field: `${label}.evidence`,
             message: "evidence is empty — provide an array of plain strings such as \"src/foo.ts:42 - variable overwritten before use\".",
         });
+        return;
     }
-    else {
-        let hasSubstantiveEntry = false;
-        for (let k = 0; k < evidence.length; k++) {
-            const entry = evidence[k];
-            if (typeof entry !== "string") {
-                pushIssue(issues, {
-                    result_index: resultIndex,
-                    task_id: taskId,
-                    field: `${label}.evidence[${k}]`,
-                    message: `evidence[${k}] must be a string, got ${describeValue(entry)}.`,
-                });
-                continue;
-            }
-            if (entry.trim().length > 0) {
-                hasSubstantiveEntry = true;
-            }
-        }
-        if (!hasSubstantiveEntry) {
+    let hasSubstantiveEntry = false;
+    for (let k = 0; k < evidence.length; k++) {
+        const entry = evidence[k];
+        if (typeof entry !== "string") {
             pushIssue(issues, {
                 result_index: resultIndex,
                 task_id: taskId,
-                field: `${label}.evidence`,
-                message: "All evidence entries are empty strings.",
+                field: `${label}.evidence[${k}]`,
+                message: `evidence[${k}] must be a string, got ${describeValue(entry)}.`,
             });
+            continue;
+        }
+        if (entry.trim().length > 0) {
+            hasSubstantiveEntry = true;
         }
     }
+    if (!hasSubstantiveEntry) {
+        pushIssue(issues, {
+            result_index: resultIndex,
+            task_id: taskId,
+            field: `${label}.evidence`,
+            message: "All evidence entries are empty strings.",
+        });
+    }
+}
+// Thin orchestrator: validates one finding by delegating to the per-concern
+// validators (object-shape, required strings, enums, affected_files, evidence),
+// each of which pushes into the shared issues array. Behavior and messages are
+// identical to the former single 165-line function.
+function validateFinding(finding, label, taskId, resultIndex) {
+    const issues = [];
+    if (!isRecord(finding)) {
+        pushIssue(issues, {
+            result_index: resultIndex,
+            task_id: taskId,
+            field: label,
+            message: `${label} must be an object, got ${describeValue(finding)}.`,
+        });
+        return issues;
+    }
+    validateFindingRequiredFields(finding, label, taskId, resultIndex, issues);
+    validateFindingEnums(finding, label, taskId, resultIndex, issues);
+    validateAffectedFiles(finding, label, taskId, resultIndex, issues);
+    validateEvidence(finding, label, taskId, resultIndex, issues);
     return issues;
 }
 function validateOptionalStringArray(value, label, taskId, resultIndex, issues) {

package/dist/validation/sessionConfig.d.ts

@@ -1,7 +1,7 @@
 import { type SessionConfig, type ValidationIssue } from "@audit-tools/shared";
 export declare function validateSessionConfig(value: unknown): ValidationIssue[];
 export declare function validateConfiguredProviderEnvironment(sessionConfig: SessionConfig, options?: {
-    commandExists?: (command: string) => boolean;
+    commandExists?: (command: string) => Promise<boolean>;
     pathExists?: (commandPath: string) => boolean;
-}): ValidationIssue[];
+}): Promise<ValidationIssue[]>;
 export { formatValidationIssues } from "@audit-tools/shared";

package/dist/validation/sessionConfig.js

@@ -1,6 +1,8 @@
-import { spawnSync } from "node:child_process";
+import { exec } from "node:child_process";
 import { accessSync, constants } from "node:fs";
+import { promisify } from "node:util";
 import { ANALYZER_SETTINGS, PROVIDER_NAMES, SESSION_UI_MODES, isRecord, pushValidationIssue, } from "@audit-tools/shared";
+const execAsync = promisify(exec);
 const VALID_PROVIDERS = new Set(PROVIDER_NAMES);
 const VALID_UI_MODES = new Set(SESSION_UI_MODES);
 const VALID_ANALYZER_SETTINGS = new Set(ANALYZER_SETTINGS);
@@ -80,10 +82,15 @@ function validateAgentProviderSection(value, path, issues) {
         pushIssue(issues, `${path}.dangerously_skip_permissions`, "dangerously_skip_permissions must be a boolean when provided.");
     }
 }
-function commandExists(command) {
+async function commandExists(command) {
     const lookupCommand = process.platform === "win32" ? "where" : "which";
-    const result = spawnSync(lookupCommand, [command], { stdio: "ignore" });
-    return result.status === 0;
+    try {
+        await execAsync(`${lookupCommand} ${command}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 function configuredPathExists(commandPath) {
     try {
@@ -183,14 +190,14 @@ export function validateSessionConfig(value) {
     }
     return issues;
 }
-export function validateConfiguredProviderEnvironment(sessionConfig, options = {}) {
+export async function validateConfiguredProviderEnvironment(sessionConfig, options = {}) {
     const issues = [];
     const lookupCommand = options.commandExists ?? commandExists;
     const lookupPath = options.pathExists ?? configuredPathExists;
     const provider = sessionConfig.provider ?? "local-subprocess";
     if (provider === "claude-code") {
         const command = sessionConfig.claude_code?.command ?? "claude";
-        if (isBareExecutableName(command) && !lookupCommand(command)) {
+        if (isBareExecutableName(command) && !(await lookupCommand(command))) {
             pushIssue(issues, "claude_code.command", `Configured claude-code executable was not found on PATH: ${command}.`);
         }
         else if (isDirectExecutablePath(command) && !lookupPath(command)) {
@@ -202,7 +209,7 @@ export function validateConfiguredProviderEnvironment(sessionConfig, options = {
     }
     if (provider === "opencode") {
         const command = sessionConfig.opencode?.command ?? "opencode";
-        if (isBareExecutableName(command) && !lookupCommand(command)) {
+        if (isBareExecutableName(command) && !(await lookupCommand(command))) {
             pushIssue(issues, "opencode.command", `Configured opencode executable was not found on PATH: ${command}.`);
         }
         else if (isDirectExecutablePath(command) && !lookupPath(command)) {

package/docs/development.md

@@ -12,10 +12,10 @@
 
 ## Agent handoff
 
-Use `docs/handoff.md` as the current pickup note for the next implementation
-agent. It should name the latest completed slice, verification status, files
-touched, and the most practical next steps. Keep long-term product direction in
-`docs/product.md`; keep transient implementation pickup notes in the handoff.
+Keep long-term product direction in `docs/product.md` and archival context
+(shipped sprints, field-trial lessons) in `docs/history.md`. There is no
+standing per-sprint handoff file; sprint notes are folded into `docs/history.md`
+once the work ships.
 
 ## Build and test
 
@@ -30,79 +30,6 @@ The test suite is intentionally contract-heavy. Update tests when changing
 schema shape, prompt contracts, dispatch behavior, installer output, or release
 workflow semantics.
 
-## Production-readiness workflow
-
-Use field trials to decide what to fix next. For each representative repository,
-run to the local review handoff, validate the artifact bundle, and compare
-`audit_plan_metrics.json` across runs. Track at least packet count, weak packet
-count, average cohesion, `merge_edge_kind_counts`,
-`boundary_edge_kind_counts`, and `weakly_explained_packet_samples`.
-
-Only promote an extractor or planner change when those metrics expose a
-deterministic gap. Prefer improving shared graph resolution or importing
-generic analyzer ownership roots before adding another ecosystem-specific
-manifest parser.
-
-The latest remediator field trial closed the remaining mixed code/schema/test
-weak packet by adding package script links, schema contract test links, bounded
-TypeScript type contract suites, package-script-seeded script suite links, and
-generated test artifact disposition. Keep future suite links similarly bounded
-and evidence-led.
-
-The Polar field trial added `conftest-link` (conftest.py → Python files in
-scope) and `pyproject-testpaths-link` (pyproject.toml → conftest.py via
-`[tool.pytest.ini_options] testpaths`). `conftest-link` fires only when the
-conftest is inside a `isTestPath` directory to avoid O(n) fan-out from
-root-level conftests. `pyproject.toml` was also added to `shouldReadForGraph`
-so its content is available during the filesystem-backed build path. Together
-these raised Polar's average cohesion from 0.625 to 0.857 and reduced weak
-packets from 5 to 3.
-
-A second Polar field trial added `yaml-path-reference-link` (YAML/YML files
-→ other config files referenced by explicit relative path). Resolution tries
-repo-root-relative first, then file-directory-relative. The extractor only
-fires for string values ending in `.yaml`, `.yml`, `.json`, or `.toml` that
-resolve to an existing repo file. In Polar, this produced 4 edges from
-`configs/benchmark.yaml` to its template files and raised `internal_edge_count`
-in the `experiments-domains` packet from 90 to 94.
-
-A third Polar field trial added `python-test-util-suite-link`, which chains
-`.py` files co-located in `utils/`, `helpers/`, or `support/` subdirectories
-within `isTestPath` directories (same bounded-suite pattern as the TypeScript
-type, JSON schema, and package-script suite links). `conftest.py` is excluded
-from the predicate. In Polar, this produced 2 intra-unit edges within the
-`tests-utils` packet, raising its `internal_edge_count` from 0 to 2 and
-eliminating it as a weak packet. Polar metrics improved from 0.857 to 1.000
-cohesion and 3 to 2 weak packets. The 2 remaining weak packets share genuinely
-isolated files (`.auditorignore`, `experiments/domains/__init__.py`,
-`experiments/summarize_results.py`) that cannot be linked without false
-positives; treat as the current floor. Note that intra-unit suite edges do not
-appear in `merge_edge_kind_counts` — their effect is visible in the packet's
-`internal_edge_count` and `unexplained_file_count` fields instead.
-
-Before treating a build as production-ready, verify the complete review loop in
-one real host:
-
-```text
-audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
-worker reviews each packet prompt
-audit-code submit-packet ...
-audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
-audit-code validate
-```
-
-On Windows, runtime validation runs package-manager shim commands such as
-`npm`, `npx`, `pnpm`, and `yarn` through the command shell so `.cmd` wrappers
-execute reliably. Keep that behavior covered when changing runtime command
-execution.
-
-If the final `audit-report.md` cannot be copied into the target repository
-because of local permissions, completion should remain successful and the
-artifact copy remains authoritative. Run `audit-code validate` against the
-artifact bundle before treating the run as complete.
-
-Then run `npm run verify:release` from a clean checkout.
-
 ## Architecture
 
 The system separates deterministic extraction from bounded LLM judgment:
@@ -122,6 +49,8 @@ Portability rules:
 - review work is attributable to files, lenses, passes, and tasks
 - coverage gaps are machine-detectable
 
+`AuditTask` is the coverage identity; `AuditResult[]` is the ingestion contract.
+
 ## Adding language analyzers
 
 Language support should be adapter-based. A new analyzer should enrich shared
@@ -137,74 +66,41 @@ Preferred outputs:
 - graph edges with kind, direction, confidence, and reason
 - entrypoints and surfaces
 - test-to-source links
-- package/module ownership hints, including analyzer-supplied
-  `ownership_roots` that become `analyzer-ownership-root-link` graph references
-- contract-suite links for small JSON Schema, workflow, package script, or
+- package/module ownership hints, including analyzer-supplied `ownership_roots`
+  that become `analyzer-ownership-root-link` graph references
+- contract-suite links for small JSON Schema, workflow, package-script, or
   TypeScript type suites when planner metrics show otherwise weak packets
 - external boundary hints
 - line counts and anchor summaries for large files
 
-Current analyzer priorities:
-
-- planner observability before additional ecosystem breadth
-- exercising the generic ownership-root input from analyzers or imported
-  evidence
-- continued behavior-preserving extraction of high-concentration graph helpers
-- JS/TS compiler-backed resolution only after the current regex edges stay
-  stable
-- Python deterministic support beyond the current local import, package/module,
-  and pytest/unittest adjacency edges only where planner metrics show gaps
-- generic fallback from path patterns, ctags/tree-sitter, LSP output, or
-  external analyzer results when available
-
-Keep deep analyzers optional. Repositories should still produce useful packets
+Keep deep analyzers optional: a repository should still produce useful packets
 from manifests, paths, tests, and external analyzer results when a language has
-only fallback support.
-
-Command-backed analyzers should prove project intent before running. Prefer
-repo-local config checks, such as `eslint.config.*`, `.eslintrc*`, or
-`package.json` `eslintConfig`, over executing a globally installed tool and
+only fallback support. Command-backed analyzers should prove project intent
+before running — prefer repo-local config checks (`eslint.config.*`, `.eslintrc*`,
+`package.json` `eslintConfig`) over executing a globally installed tool and
 parsing its no-config failure.
 
-Language-agnostic semantic affinity can be useful for ranking adjacent context,
-but it should be low authority. Do not let shared token frequency alone force
-packet merges; use it for `boundary_files` or candidate explanations unless a
+Language-agnostic semantic affinity is useful for ranking adjacent context but
+should stay low-authority: don't let shared token frequency alone force packet
+merges; use it for `boundary_files` or candidate explanations unless a
 deterministic edge corroborates the relationship.
 
-## Packetization work
-
-The current packetizer groups tasks across lenses and merges graph-connected
-task groups within line budgets. Plan metrics now record which graph edge kinds
-caused packet merges, which candidate edge kinds stayed as boundary context,
-and which packets remain weakly explained. Weak-packet diagnostics aggregate
-primary gap counts and unique file-extension counts, while bounded samples
-include representative file paths. Together those metrics let real or fixture
-runs point at the next deterministic extractor or analyzer-ownership
-improvement. The next phase is consolidation and carefully chosen deterministic
-depth:
-
-- use packet-quality observations to prioritize extractor gaps
-- keep manifest/project-file edge extraction isolated from packet planning code
-- use the generic ownership-root contract before adding more ecosystem-specific
-  module formats
-- keep bounded suite edges as contract evidence, not as a generic
-  same-directory merge rule
-- exercise the Python import, package layout, and test/source edges against
-  fixture and real repositories before adding deeper Python framework handling
-
-Keep `AuditTask` as the coverage identity and `AuditResult[]` as the ingestion
-contract.
-
-## File-splitting priorities
-
-The largest implementation files should be split conservatively and
-behavior-preservingly:
-
-- move CLI command families out of `src/cli.ts`
-- move language metadata tables out of file inventory logic
-- move graph manifest/project-file parsers out of `src/extractors/graph.ts`
-- split selective-deepening task builders by trigger type
-- keep packetization, recovery, and schema changes easier to review
-
-Run the focused tests for each area before and after a split, then run
-`npm test`.
+## Production readiness
+
+Drive priorities from field trials, not speculation: run representative
+repositories through planning, validate the bundle (`audit-code validate`), and
+compare `audit_plan_metrics.json` (packet count, weak-packet count, cohesion,
+merge/boundary edge kinds) across runs. Promote an extractor or planner change
+when those metrics expose a deterministic gap — and prefer improving shared
+graph resolution or generic analyzer ownership roots before adding another
+ecosystem-specific parser.
+
+Before treating a build as production-ready, verify the full review loop in one
+real host (`prepare-dispatch` → worker reviews each packet → `submit-packet` →
+`merge-and-ingest` → `validate`), then run `npm run verify:release` from a clean
+checkout. On Windows, runtime validation runs package-manager shims (`npm`,
+`npx`, `pnpm`, `yarn`) through the command shell so `.cmd` wrappers execute
+reliably — keep that covered when changing runtime command execution. If the
+final `audit-report.md` cannot be copied into the target repo due to local
+permissions, completion still succeeds and the artifact copy is authoritative.
+</content>

package/docs/history.md

@@ -38,3 +38,29 @@ The old remediation baseline recorded fixes across:
 
 Current readiness is tracked in `docs/product.md`, `docs/operator-guide.md`,
 `docs/contracts.md`, `docs/release.md`, and `docs/development.md`.
+
+## Monorepo migration & drift reconciliation (2026-05 → 2026-06)
+
+The auditor and remediator began as standalone repos (`auditor-lambda`,
+`remediator-lambda`) and were merged into this npm-workspaces monorepo on a
+shared `@audit-tools/shared` foundation. `providers/` and `quota/` had been
+copy-pasted into both tools and forked in place; the ten resulting drift bugs
+were all fixed by centralizing the forked logic into `shared` (one source of
+truth). Durable decisions from that work:
+
+- **Access scoping is JSON, not MCP.** `AccessDeclaration` rides on the step
+  contract, so it works with any host; the MCP servers stay compatibility
+  adapters over the same contract.
+- **`--dangerously-skip-permissions` defaults ON for the remediator, OFF for the
+  auditor.** The remediator applies changes unattended and cannot pause; the
+  auditor is read-only. The asymmetry is intentional and the flag is overrideable.
+- **The remediator's machine input is `audit-findings.json`, not the Markdown
+  report.** `audit-report.md` is human-facing; a Markdown file handed to the
+  remediator flows through the free-form LLM extractor, not a deterministic parse.
+- **Prompts use one strict path** — no "or / unless / if-available" fallbacks.
+
+Large files were then broken up as behaviour-preserving pure moves (`cli.ts` from
+4072 lines to a thin dispatcher plus `src/cli/*` handlers; `graph.ts`,
+`reviewPackets.ts`, `internalExecutors.ts`, and the generated language table all
+split out). The sprint-by-sprint handoff docs that tracked this work were removed
+once shipped; this section is their durable residue.