auditor-lambda 0.6.12 → 0.8.0

package/dist/orchestrator/runtimeCommand.d.ts

@@ -0,0 +1,11 @@
+export declare function runCommand(command: string[], cwd: string, options?: {
+    opentoken?: boolean;
+}): Promise<{
+    status: "confirmed" | "not_confirmed" | "inconclusive";
+    summary: string;
+    evidence: string[];
+}>;
+export declare function resolveRuntimeValidationSpawnCommand(command: string[], platform?: NodeJS.Platform, shellCommand?: string): {
+    command: string;
+    args: string[];
+};

package/dist/orchestrator/runtimeCommand.js

@@ -0,0 +1,79 @@
+import { spawn } from "node:child_process";
+// Deterministic runtime-validation command execution: resolve a command to a
+// platform-correct spawn invocation (Windows package-manager shims need a
+// cmd.exe wrapper), optionally wrap it for opentoken accounting, and run it
+// capturing a confirmed/not_confirmed/inconclusive outcome. Hoisted out of
+// internalExecutors.ts as a shared, side-effect-only helper module.
+function resolveOpentokenWrap(resolved, platform = process.platform) {
+    if (platform === "win32") {
+        const shell = process.env.ComSpec ?? "cmd.exe";
+        const inner = [resolved.command, ...resolved.args]
+            .map((v) => (/^[A-Za-z0-9_./:=@+-]+$/.test(v) ? v : `"${v.replace(/(["^&|<>%])/g, "^$1")}"`))
+            .join(" ");
+        return { command: shell, args: ["/d", "/s", "/c", `opentoken wrap ${inner}`] };
+    }
+    return { command: "opentoken", args: ["wrap", resolved.command, ...resolved.args] };
+}
+export async function runCommand(command, cwd, options = {}) {
+    let spawnCommand = resolveRuntimeValidationSpawnCommand(command);
+    if (options.opentoken) {
+        spawnCommand = resolveOpentokenWrap(spawnCommand);
+    }
+    const displayCommand = command.join(" ");
+    return await new Promise((resolve) => {
+        const child = spawn(spawnCommand.command, spawnCommand.args, {
+            cwd,
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", (error) => {
+            resolve({
+                status: "inconclusive",
+                summary: `Failed to execute ${displayCommand}: ${error.message}`,
+                evidence: [],
+            });
+        });
+        child.on("exit", (code) => {
+            const output = `${stdout}\n${stderr}`.trim();
+            const evidence = output.length > 0 ? output.split(/\r?\n/).slice(-10) : [];
+            resolve({
+                status: code === 0 ? "confirmed" : "not_confirmed",
+                summary: code === 0
+                    ? `Deterministic runtime command succeeded: ${displayCommand}`
+                    : `Deterministic runtime command failed with exit code ${code}: ${displayCommand}`,
+                evidence,
+            });
+        });
+    });
+}
+export function resolveRuntimeValidationSpawnCommand(command, platform = process.platform, shellCommand = process.env.ComSpec ?? "cmd.exe") {
+    const [executable, ...args] = command;
+    if (!executable) {
+        return { command: "", args: [] };
+    }
+    if (platform !== "win32") {
+        return { command: executable, args };
+    }
+    const packageManager = executable.replace(/\.(cmd|bat)$/i, "").toLowerCase();
+    if (["npm", "npx", "pnpm", "yarn"].includes(packageManager)) {
+        return {
+            command: shellCommand,
+            args: ["/d", "/s", "/c", command.map(quoteCmdArg).join(" ")],
+        };
+    }
+    return { command: executable, args };
+}
+function quoteCmdArg(value) {
+    if (/^[A-Za-z0-9_./:=+-]+$/.test(value)) {
+        return value;
+    }
+    return `"${value.replace(/(["^&|<>%])/g, "^$1")}"`;
+}

package/dist/orchestrator/scope.js

@@ -1,7 +1,7 @@
 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";
+import { HIGH_FAN_DEGREE_THRESHOLD, buildGraphDegreeIndex, collectGraphEdges, graphEdgeConfidence, normalizeGraphPath, } from "./reviewPacketGraph.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. */

package/dist/orchestrator/syntaxResolutionExecutor.d.ts

@@ -1,3 +1,3 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
-import type { ExecutorRunResult } from "./internalExecutors.js";
+import type { ExecutorRunResult } from "./executorResult.js";
 export declare function runSyntaxResolutionExecutor(bundle: ArtifactBundle, root: string): ExecutorRunResult;

package/dist/orchestrator/synthesisExecutors.d.ts

@@ -0,0 +1,12 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+import type { AuditResult } from "../types.js";
+import type { ExecutorRunResult } from "./executorResult.js";
+import type { SynthesisNarrative } from "@audit-tools/shared";
+export declare function runSynthesisExecutor(bundle: ArtifactBundle, results?: AuditResult[]): ExecutorRunResult;
+/**
+ * Resolve the optional synthesis-narrative obligation. When a host/provider
+ * narrative is supplied it is merged into the canonical findings report and the
+ * human report is re-rendered with themes/executive-summary/top-risks; without
+ * one the narrative is recorded as omitted and the deterministic report stands.
+ */
+export declare function runSynthesisNarrativeExecutor(bundle: ArtifactBundle, narrative?: SynthesisNarrative): ExecutorRunResult;

package/dist/orchestrator/synthesisExecutors.js

@@ -0,0 +1,90 @@
+import { applyNarrative, buildAuditFindingsReport, buildAuditReportModel, renderAuditReportMarkdown, } from "../reporting/synthesis.js";
+function buildBaseFindingsReport(bundle, results) {
+    return buildAuditFindingsReport(buildAuditReportModel({
+        results,
+        unitManifest: bundle.unit_manifest,
+        graphBundle: bundle.graph_bundle,
+        criticalFlows: bundle.critical_flows,
+        coverageMatrix: bundle.coverage_matrix,
+        runtimeValidationReport: bundle.runtime_validation_report,
+        externalAnalyzerResults: bundle.external_analyzer_results,
+        designAssessment: bundle.design_assessment,
+    }));
+}
+export function runSynthesisExecutor(bundle, results) {
+    const finalResults = results ?? bundle.audit_results ?? [];
+    // Emit the canonical machine contract and render the human report from it.
+    // No narrative yet — that is layered by the synthesis-narrative obligation.
+    const findings = buildBaseFindingsReport(bundle, finalResults);
+    // Synthesis renders findings; it does NOT own audit_results. Writing
+    // audit_results back here desyncs it from its metadata entry (it isn't in
+    // artifacts_written, so computeArtifactMetadata reuses the prior hash) and, in
+    // the zero-result case, materializes an empty audit_results.jsonl that did not
+    // exist before — both perpetually re-stale coverage_matrix → planning,
+    // forcing a planning re-run that rewrites runtime_validation_report.json (the
+    // finalization-oscillation engine). Leave audit_results as the ingested value.
+    return {
+        updated: {
+            ...bundle,
+            audit_findings: findings,
+            audit_report: renderAuditReportMarkdown(findings, { scope: bundle.scope }),
+        },
+        artifacts_written: ["audit-findings.json", "audit-report.md"],
+        progress_summary: `Rendered deterministic audit report and canonical findings for ${finalResults.length} audit result entries.`,
+    };
+}
+/**
+ * Resolve the optional synthesis-narrative obligation. When a host/provider
+ * narrative is supplied it is merged into the canonical findings report and the
+ * human report is re-rendered with themes/executive-summary/top-risks; without
+ * one the narrative is recorded as omitted and the deterministic report stands.
+ */
+export function runSynthesisNarrativeExecutor(bundle, narrative) {
+    const baseReport = bundle.audit_findings ??
+        buildBaseFindingsReport(bundle, bundle.audit_results ?? []);
+    const needsBaseWrite = !bundle.audit_findings;
+    const hasNarrative = Boolean(narrative &&
+        ((narrative.themes?.length ?? 0) > 0 ||
+            (narrative.executive_summary?.trim().length ?? 0) > 0 ||
+            (narrative.top_risks?.length ?? 0) > 0));
+    if (!hasNarrative) {
+        const record = {
+            status: "omitted",
+            theme_count: 0,
+            executive_summary_present: false,
+            top_risk_count: 0,
+        };
+        return {
+            updated: {
+                ...bundle,
+                audit_findings: baseReport,
+                synthesis_narrative: record,
+            },
+            artifacts_written: needsBaseWrite
+                ? ["audit-findings.json", "synthesis-narrative.json"]
+                : ["synthesis-narrative.json"],
+            progress_summary: "Synthesis narrative omitted; deterministic findings report retained.",
+        };
+    }
+    const enriched = applyNarrative(baseReport, narrative);
+    const record = {
+        status: "applied",
+        theme_count: enriched.themes?.length ?? 0,
+        executive_summary_present: (enriched.executive_summary?.trim().length ?? 0) > 0,
+        top_risk_count: enriched.top_risks?.length ?? 0,
+    };
+    return {
+        updated: {
+            ...bundle,
+            audit_findings: enriched,
+            audit_report: renderAuditReportMarkdown(enriched, { scope: bundle.scope }),
+            synthesis_narrative: record,
+        },
+        artifacts_written: [
+            "audit-findings.json",
+            "audit-report.md",
+            "synthesis-narrative.json",
+        ],
+        progress_summary: `Synthesis narrative applied: ${record.theme_count} theme(s), ${record.top_risk_count} top risk(s).`,
+    };
+}

package/dist/orchestrator.js

@@ -1,3 +1,4 @@
+import { isLens } from "./types.js";
 const DEFAULT_LENS_ORDER = [
     "correctness",
     "architecture",
@@ -10,13 +11,9 @@ const DEFAULT_LENS_ORDER = [
     "operability",
     "config_deployment",
 ];
-const VALID_LENSES = new Set(DEFAULT_LENS_ORDER);
 function isRecord(value) {
     return value !== null && typeof value === "object";
 }
-function isLens(value) {
-    return typeof value === "string" && VALID_LENSES.has(value);
-}
 function assertStringArray(value, label) {
     if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
         throw new TypeError(`${label} must be an array of strings.`);

package/dist/quota/index.d.ts

@@ -1,7 +1,7 @@
 import type { ResolvedLimits as _ResolvedLimits, LimitConfidence as _LimitConfidence, LimitSource as _LimitSource, HostConcurrencyLimit as _HostConcurrencyLimit, QuotaUsageSnapshot as _QuotaUsageSnapshot, BackoffState as _BackoffState } from "@audit-tools/shared";
 export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writeQuotaState, computeMaxSafeConcurrency, recordWaveOutcome, getQuotaStatePath, decayWeight, applyDecayToEntry, computeBackoffCooldownMs, computeBackoffFailureWeight, computeRampUpConcurrency, setQuotaStateDir, detectRateLimitError, computeCooldownUntil, acquireLock, releaseLock, withFileLock, FileLockTimeoutError, runSlidingWindow, LearnedQuotaSource, CompositeQuotaSource, GenericErrorParser, ClaudeCodeErrorParser, getErrorParserForProvider, } from "@audit-tools/shared";
 export type { LimitResolutionResult, ResolveLimitsOptions, ProviderType, ResolvedLimits, LimitSource, LimitConfidence, HostConcurrencyLimit, HostConcurrencyLimitSource, QuotaState, QuotaStateEntry, ConcurrencyBucket, WaveSchedule, BackoffState, ObservedWaveOutcome, RateLimitDetectionResult, SlidingWindowResult, QuotaSource, QuotaUsageSnapshot, ErrorParser, } from "@audit-tools/shared";
-export { scheduleWave, buildProviderModelKey } from "@audit-tools/shared";
+export { scheduleWave, buildProviderModelKey, resolveHostModel } from "@audit-tools/shared";
 export type { ScheduleWaveOptions } from "@audit-tools/shared";
 export { detectHostActiveSubagentLimit, resolveHostActiveSubagentLimit, } from "./hostLimits.js";
 export { probeProvider } from "./probe.js";

package/dist/quota/index.js

@@ -3,7 +3,7 @@ export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writ
 // Wave scheduler now lives in @audit-tools/shared (single source of truth for
 // both orchestrators). Auditor passes its discovered-limits via the structural
 // DiscoveredRateLimitsInput the shared scheduler accepts.
-export { scheduleWave, buildProviderModelKey } from "@audit-tools/shared";
+export { scheduleWave, buildProviderModelKey, resolveHostModel } from "@audit-tools/shared";
 // Auditor-specific: probe, discovered limits, header extraction
 export { detectHostActiveSubagentLimit, resolveHostActiveSubagentLimit, } from "./hostLimits.js";
 export { probeProvider } from "./probe.js";

package/dist/types/workerSession.d.ts

@@ -23,10 +23,8 @@ export interface WorkerTask {
     runtime_updates_path?: string;
     external_analyzer_results_path?: string;
     worker_command_mode?: WorkerCommandMode;
-    /** @deprecated Prefer worker_command_mode: "deferred" for new task files. */
-    skip_worker_command?: boolean;
     timeout_ms?: number;
     max_retries?: number;
     access?: AccessDeclaration;
 }
-export declare function usesDeferredWorkerCommand(task: Pick<WorkerTask, "worker_command_mode" | "skip_worker_command">): boolean;
+export declare function usesDeferredWorkerCommand(task: Pick<WorkerTask, "worker_command_mode">): boolean;

package/dist/types.d.ts

@@ -1,5 +1,11 @@
 import type { Finding as SharedFinding } from "@audit-tools/shared";
 export type Lens = "correctness" | "architecture" | "maintainability" | "security" | "reliability" | "performance" | "data_integrity" | "tests" | "operability" | "config_deployment" | "observability";
+/** Canonical list of every valid {@link Lens}. Single source of truth — import
+ * {@link isLens} / `ALL_LENSES` instead of hand-copying lens lists into local
+ * guards, which drift (a copy omitting "observability" caused it to be wrongly
+ * rejected in flow requeue). */
+export declare const ALL_LENSES: readonly Lens[];
+export declare function isLens(value: unknown): value is Lens;
 export interface FileRecord {
     path: string;
     language: string;

package/dist/types.js

@@ -1 +1,20 @@
-export {};
+/** Canonical list of every valid {@link Lens}. Single source of truth — import
+ * {@link isLens} / `ALL_LENSES` instead of hand-copying lens lists into local
+ * guards, which drift (a copy omitting "observability" caused it to be wrongly
+ * rejected in flow requeue). */
+export const ALL_LENSES = [
+    "correctness",
+    "architecture",
+    "maintainability",
+    "security",
+    "reliability",
+    "performance",
+    "data_integrity",
+    "tests",
+    "operability",
+    "config_deployment",
+    "observability",
+];
+export function isLens(value) {
+    return (typeof value === "string" && ALL_LENSES.includes(value));
+}

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.