auditor-lambda 0.7.0 → 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/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.

package/docs/product.md

@@ -1,5 +1,9 @@
 # Product
 
+> Normative definition: [`spec/audit-goals.md`](../spec/audit-goals.md) — product
+> identity, invariants, deterministic/LLM boundaries, and completion. This page is
+> the product overview.
+
 ## Canonical surface
 
 The primary product is `/audit-code` in conversation.
@@ -12,8 +16,8 @@ Normal product usage should:
 - keep semantic review with the active conversation agent by default
 - advance the audit automatically until it completes or no further automatic progress is possible
 
-The CLI is backend infrastructure, a local development harness, and a
-repo-local fallback. It is not the preferred end-user mental model.
+The CLI is backend infrastructure, a local development harness, and a repo-local
+fallback. It is not the preferred end-user mental model.
 
 ## Supported surfaces
 
@@ -48,17 +52,14 @@ provider adapters such as `claude-code`, `opencode`, `subprocess-template`, and
 
 ## Language strategy
 
-Packet quality should not depend on one language ecosystem. JavaScript,
-TypeScript, and Python can receive the richest early support because they are
-common in current usage, but every language analyzer must write into the same
-language-neutral graph and artifact contracts.
+Packet quality should not depend on one language ecosystem. Every language
+analyzer must write into the same language-neutral graph and artifact contracts;
+JS/TS and Python get the richest early support only because they are common.
 
 Do not keep expanding support by adding one bespoke parser per ecosystem unless
-there is concrete repository demand or a high-value deterministic signal. The
-current breadth of package and workspace manifest hints is enough to validate
-the packetization approach. The next product goal is to make graph planning
-observable, maintainable, and extensible through generic ownership hints rather
-than through an open-ended list of file-format handlers.
+there is concrete repository demand or a high-value deterministic signal. Prefer
+making graph planning observable and extensible through generic ownership hints
+over an open-ended list of file-format handlers.
 
 The shared graph should model:
 
@@ -71,111 +72,43 @@ The shared graph should model:
   subprocesses
 - edge confidence, direction, and reason
 
-Graph evidence should be treated in tiers:
+Graph evidence is tiered, strongest first:
 
-- deterministic directed edges, such as imports, entrypoints, route handlers,
-  test/source links, and resolved analyzer references
-- deterministic ownership edges, such as package, module, project, or subsystem
-  roots
+- deterministic directed edges (imports, entrypoints, route handlers,
+  test/source links, resolved analyzer references)
+- deterministic ownership edges (package, module, project, or subsystem roots)
 - analyzer-supplied ownership roots, normalized into graph reference edges
-- language-agnostic semantic affinity, such as shared unusual domain terms,
-  nearby paths, identifier overlap, or embeddings
-
-Semantic affinity can help rank `boundary_files`, explain possible context, and
-highlight missing deterministic extraction. It should not merge packets on
-frequency alone because common tokens like `user`, `request`, `client`,
-`config`, and `error` often connect unrelated code.
-
-Language-specific adapters should enrich the graph without changing packet or
-result contracts:
+- language-agnostic semantic affinity (shared unusual domain terms, nearby
+  paths, identifier overlap, embeddings)
 
-- JS/TS: TypeScript compiler API, package manifests, import/export edges, route
-  conventions, test adjacency
-- Python: local import statement parsing, package/module resolution,
-  pytest/unittest adjacency, and future framework route conventions
-- Other ecosystems: prefer analyzer-supplied ownership roots, ctags/tree-sitter,
-  LSP output, or existing external analyzer data before adding new bespoke
-  manifest parsers
+Semantic affinity can rank `boundary_files`, explain possible context, and
+highlight missing extraction — but it must not merge packets on frequency alone,
+because common tokens (`user`, `request`, `client`, `config`, `error`) connect
+unrelated code.
 
-The fallback should remain useful even when a language has no deep analyzer:
-manifest files, path structure, tests, config, and external analyzer output can
-still seed a graph with lower-confidence edges.
-
-Deterministic tool runners should be project-config aware. For example, ESLint
-syntax-resolution should run only when the repository has repo-local ESLint
-configuration, not merely because an ESLint binary is installed.
+The fallback must stay useful even when a language has no deep analyzer:
+manifests, path structure, tests, config, and external analyzer output can seed a
+graph with lower-confidence edges. Deterministic tool runners should be
+project-config aware — e.g. ESLint syntax-resolution runs only when the repo has
+local ESLint configuration, not merely because the binary is installed.
 
 ## Packet planning
 
-`AuditTask` remains the deterministic coverage identity. `ReviewPacket` is the
-worker-facing unit of understanding.
-
-The next packetization phase should:
-
-- use planner observability to tune which edge kinds change grouping, which
-  files stay boundary-only, and which extractor gaps leave weakly explained
-  packets
-- extend and exercise the generic ownership-root input so external analyzers
-  can say "these files belong to module root X" without a new parser for every
-  ecosystem
-- keep graph and manifest parser code modular before broadening it further
-- exercise deterministic Python import, package, and test/source graph support
-  on fixture and real repositories to find the next highest-value gaps
-- use language-agnostic semantic affinity only as low-authority context unless
-  corroborated by deterministic graph evidence
+`AuditTask` is the deterministic coverage identity; `ReviewPacket` is the
+worker-facing unit of understanding. Packetization aims for packets that read as
+coherent code-ownership or execution-flow units, not merely budget-sized bundles:
+
 - build packets around coherent subsystems and execution flows
-- keep shared fan-in files visible as context instead of letting them merge too
-  much of the repository into one packet
-- distinguish strong edges from weak or heuristic edges
-- group tests with the code they verify when that helps review quality
-- include packet rationale, key edges, entrypoints, and boundary files
-- track packet-quality metrics such as cohesion, fan-in/fan-out, boundary
-  crossings, orphan tasks, weak-packet gap and extension counts, risk
-  concentration, and largest unexplained packet
-
-The practical success bar is that packets feel like reviewable code ownership
-or execution-flow units, not merely budget-sized bundles.
-
-## Production readiness
-
-The package publication path is operational. The release gate, packaged install
-smoke tests, and GitHub Actions Trusted Publishing path are routine
-maintenance. The remaining production work is product confidence rather than a
-new contract shape.
-
-Readiness should be judged through three checks:
-
-- field-trial quality: run real repositories through planning, validate
-  artifacts, and use `audit_plan_metrics.json` to track packet count, weak
-  packet count, average cohesion, merge edge kinds, and weak-packet samples
-- full-loop behavior: prove `next-step` capability routing, packet dispatch,
-  worker review, `submit-packet`, `merge-and-ingest`, selective deepening,
-  runtime validation, and final `audit-report.md` promotion in at least one
-  real host flow
-- release hygiene: keep `npm run verify:release`, linked smoke, packaged
-  smoke, tarball preview, and Trusted Publishing green from a clean checkout
-
-Extractor work should follow field-trial evidence. Fix deterministic graph gaps
-when metrics show them, prefer analyzer-supplied ownership roots before new
-manifest parsers, and keep semantic affinity as context unless deterministic
-evidence corroborates it.
-
-The current production-readiness focus is:
-
-- use the remediator packet-dispatch loop and Polar runtime-confirmed loop as
-  regression evidence for Windows runtime execution, runtime follow-up, final
-  synthesis, and report-promotion behavior
-- use the remediator contract-link field trial as regression evidence that
-  small schema, workflow, package script, and type contract suites can become
-  graph evidence without broad directory merges
-- rerun `remediator-lambda` after its Windows `EBUSY` test cleanup issue is
-  fixed
-- keep exercising analyzer ownership roots on real repositories before adding
-  ecosystem-specific manifest parsers
-- keep host setup claims aligned with verified Codex, Claude Desktop, OpenCode,
-  VS Code, and Antigravity behavior
-- split high-concentration implementation files only after the packetization
-  and schema contracts stay easy to review
+- keep shared fan-in files visible as context rather than merging large parts of
+  the repo into one packet
+- distinguish strong (deterministic) edges from weak or heuristic ones
+- group tests with the code they verify when it aids review
+- carry packet rationale, key edges, entrypoints, and boundary files
+- prefer the generic ownership-root contract (analyzers naming module roots) over
+  a new parser per ecosystem, and keep graph/manifest parsing modular
+
+Planner observability (`audit_plan_metrics.json`: cohesion, fan-in/out, boundary
+crossings, weak-packet gaps) is how extraction gaps are found and prioritized.
 
 ## Non-goals
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",