audit-tools 0.28.0

package/dist/shared/validation/findingGrounding.js

@@ -0,0 +1,103 @@
+/**
+ * Finding grounding primitives — single source for both orchestrators.
+ *
+ * Quote-and-verify grounding (S7 anti-hallucination): a finding cites a verbatim
+ * span (`affected_files[].quoted_text`); the tool re-reads that span from disk
+ * and content-matches it. The confirmed bit is the tool's re-check, never the
+ * model's word. A finding whose quote does not re-verify — or that carries no
+ * quote at all — is `ungrounded`: surfaced, never silently admitted as a
+ * confirmed finding.
+ *
+ * Matching is on *content*, normalized for whitespace/CRLF, not on line numbers
+ * — later edits that shift line numbers do not false-fail a still-valid quote,
+ * while a quote naming code that does not exist cannot match.
+ *
+ * Before this module the auditor (`quoteGrounding.ts`) and the conceptual-review
+ * grounding (`designFindingGrounding.ts`) each carried their own copy of
+ * `normalizeForMatch` / `quoteMatches` / `verifyFindingGrounding` and a near-
+ * identical path normalizer; this is the one authority both consume (drift-plan
+ * E3 + P7).
+ */
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+/** Normalize text for content-matching: drop CR, collapse whitespace, trim. */
+export function normalizeForMatch(text) {
+    return text.replace(/\r/g, "").replace(/\s+/g, " ").trim();
+}
+/**
+ * Repo-relative, separator- and case-normalized path for matching against a
+ * known-paths set: trim, backslash→slash, strip a leading `./`, lowercase.
+ *
+ * The single path normalizer (drift-plan P7) shared by the conceptual-review
+ * grounding and any other consumer that matches a cited `affected_files` path
+ * against a repo manifest. (Quote-and-verify resolves a cited path against the
+ * filesystem instead, so it does not lowercase — see `verifyFindingGrounding`.)
+ */
+export function normalizeRepoPath(p) {
+    return p.trim().replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
+}
+/**
+ * True when the (normalized) quoted span appears anywhere in the (normalized)
+ * file content. An empty quote never matches (an empty quote grounds nothing).
+ */
+export function quoteMatches(fileContent, quotedText) {
+    const needle = normalizeForMatch(quotedText);
+    if (needle.length === 0)
+        return false;
+    return normalizeForMatch(fileContent).includes(needle);
+}
+const defaultSourceReader = (absolutePath) => readFile(absolutePath, "utf8");
+/**
+ * Re-verify a finding's cited verbatim span(s) against disk. A finding is
+ * `grounded` as soon as ONE of its `affected_files[].quoted_text` spans matches
+ * its cited file; it is `ungrounded` when it carries no quote at all, or when no
+ * cited quote can be found on disk (with a reason naming the failed spans).
+ */
+export async function verifyFindingGrounding(repoRoot, finding, readSource = defaultSourceReader) {
+    const quoted = (finding.affected_files ?? []).filter((loc) => typeof loc.quoted_text === "string" && loc.quoted_text.trim().length > 0);
+    if (quoted.length === 0) {
+        return {
+            status: "ungrounded",
+            reason: "no affected_files entry carries a verbatim quoted_text span to re-verify",
+        };
+    }
+    const misses = [];
+    for (const loc of quoted) {
+        const absolutePath = isAbsolute(loc.path) ? loc.path : join(repoRoot, loc.path);
+        let content;
+        try {
+            content = await readSource(absolutePath);
+        }
+        catch {
+            misses.push(`${loc.path}: file could not be read on disk`);
+            continue;
+        }
+        if (quoteMatches(content, loc.quoted_text)) {
+            return { status: "grounded" };
+        }
+        misses.push(`${loc.path}: quoted_text not found on disk`);
+    }
+    return { status: "ungrounded", reason: misses.join("; ") };
+}
+/**
+ * INV-GND-02 (total function): classify a finding's grounding as a verdict that
+ * is ALWAYS defined. A finding whose `grounding` is undefined/absent is treated
+ * as **ungrounded** — it was never re-verified, so it must be verified before a
+ * fix is applied, never silently trusted. This is the single authority the
+ * remediator consults on the structured-audit path so a missing verdict can
+ * never be mistaken for a passing one.
+ */
+export function findingIsGrounded(finding) {
+    return finding.grounding?.status === "grounded";
+}
+/**
+ * True when a finding must be verified-before-fix because it was NOT positively
+ * grounded: `ungrounded` (quote didn't re-verify), `refuted` (anchor disproved —
+ * normally already quarantined-excluded upstream), or no verdict at all
+ * (undefined → treated as ungrounded, INV-GND-02). The remediator uses this to
+ * flag such findings for a verify-first pass rather than blindly applying the fix.
+ */
+export function findingNeedsVerificationBeforeFix(finding) {
+    return !findingIsGrounded(finding);
+}
+//# sourceMappingURL=findingGrounding.js.map

package/dist/shared/validation/findingGrounding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findingGrounding.js","sourceRoot":"","sources":["../../../src/shared/validation/findingGrounding.ts"],"names":[],"mappings":"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"}

package/dist/shared/validation/findingsReport.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Validation utilities for AuditFindingsReport — the canonical
+ * audit-findings.json contract.
+ *
+ * INV-shared-core-06: AuditFindingsReport.contract_version must be validated
+ * on ingestion (presence + expected value), not read blindly. This module is
+ * the single place that performs that check so both orchestrators stay in sync.
+ */
+import type { AuditFindingsReport } from "../types/finding.js";
+import type { ValidationIssue } from "./basic.js";
+/**
+ * The expected contract_version value for audit-findings.json.
+ * Ingestion must check this; absent or mismatched values are flagged.
+ */
+export declare const AUDIT_FINDINGS_CONTRACT_VERSION: "audit-tools/audit-findings/v1alpha1";
+/**
+ * Validate an unknown value as an AuditFindingsReport.
+ *
+ * Returns a list of ValidationIssues. An empty list means the value is a
+ * structurally valid AuditFindingsReport. Issues with severity "error" mean
+ * the value cannot be used safely; severity "warning" means the value can be
+ * used but callers should surface the concern.
+ *
+ * INV-shared-core-06 / OBL-C002-VERSION-TRUST: contract_version absence OR
+ * mismatch is flagged as a severity="error". A mismatched version is treated
+ * identically to an absent version — the report must be rejected, not
+ * processed with a warning. This ensures isValidAuditFindingsReport returns
+ * false for any version that is not exactly AUDIT_FINDINGS_CONTRACT_VERSION.
+ */
+export declare function validateAuditFindingsReport(value: unknown, path?: string): ValidationIssue[];
+/**
+ * Type-narrowing guard. Returns true only when the value passes structural
+ * validation with no errors. Warnings do not block the guard.
+ *
+ * Unlike the plain `isAuditFindingsReport` in remediate-code/phases/plan.ts,
+ * this guard enforces contract_version presence AND exact match
+ * (INV-shared-core-06 / OBL-C002-VERSION-TRUST). Both absent and mismatched
+ * contract_version produce severity="error" and cause this function to
+ * return false.
+ */
+export declare function isValidAuditFindingsReport(value: unknown): value is AuditFindingsReport;
+//# sourceMappingURL=findingsReport.d.ts.map

package/dist/shared/validation/findingsReport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findingsReport.d.ts","sourceRoot":"","sources":["../../../src/shared/validation/findingsReport.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD;;;GAGG;AACH,eAAO,MAAM,+BAA+B,EAC1C,qCAA8C,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,IAAI,SAAK,GACR,eAAe,EAAE,CAmEnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,mBAAmB,CAG9B"}

package/dist/shared/validation/findingsReport.js

@@ -0,0 +1,76 @@
+/**
+ * Validation utilities for AuditFindingsReport — the canonical
+ * audit-findings.json contract.
+ *
+ * INV-shared-core-06: AuditFindingsReport.contract_version must be validated
+ * on ingestion (presence + expected value), not read blindly. This module is
+ * the single place that performs that check so both orchestrators stay in sync.
+ */
+import { isRecord, pushValidationIssue } from "./basic.js";
+/**
+ * The expected contract_version value for audit-findings.json.
+ * Ingestion must check this; absent or mismatched values are flagged.
+ */
+export const AUDIT_FINDINGS_CONTRACT_VERSION = "audit-tools/audit-findings/v1alpha1";
+/**
+ * Validate an unknown value as an AuditFindingsReport.
+ *
+ * Returns a list of ValidationIssues. An empty list means the value is a
+ * structurally valid AuditFindingsReport. Issues with severity "error" mean
+ * the value cannot be used safely; severity "warning" means the value can be
+ * used but callers should surface the concern.
+ *
+ * INV-shared-core-06 / OBL-C002-VERSION-TRUST: contract_version absence OR
+ * mismatch is flagged as a severity="error". A mismatched version is treated
+ * identically to an absent version — the report must be rejected, not
+ * processed with a warning. This ensures isValidAuditFindingsReport returns
+ * false for any version that is not exactly AUDIT_FINDINGS_CONTRACT_VERSION.
+ */
+export function validateAuditFindingsReport(value, path = "") {
+    const issues = [];
+    if (!isRecord(value)) {
+        pushValidationIssue(issues, path, `Expected an AuditFindingsReport object, got ${typeof value}.`);
+        return issues;
+    }
+    // INV-shared-core-06: contract_version must be present and match the expected value.
+    if (!("contract_version" in value)) {
+        pushValidationIssue(issues, path ? `${path}.contract_version` : "contract_version", `Missing required field: contract_version. Expected "${AUDIT_FINDINGS_CONTRACT_VERSION}".`);
+    }
+    else if (typeof value.contract_version !== "string") {
+        pushValidationIssue(issues, path ? `${path}.contract_version` : "contract_version", `contract_version must be a string, got ${typeof value.contract_version}.`);
+    }
+    else if (value.contract_version !== AUDIT_FINDINGS_CONTRACT_VERSION) {
+        pushValidationIssue(issues, path ? `${path}.contract_version` : "contract_version", `contract_version mismatch: expected "${AUDIT_FINDINGS_CONTRACT_VERSION}", got "${value.contract_version}". Report cannot be processed safely.`);
+    }
+    // findings must be an array.
+    if (!("findings" in value)) {
+        pushValidationIssue(issues, path ? `${path}.findings` : "findings", `Missing required field: findings.`);
+    }
+    else if (!Array.isArray(value.findings)) {
+        pushValidationIssue(issues, path ? `${path}.findings` : "findings", `findings must be an array, got ${typeof value.findings}.`);
+    }
+    // work_blocks must be an array if present.
+    if ("work_blocks" in value && !Array.isArray(value.work_blocks)) {
+        pushValidationIssue(issues, path ? `${path}.work_blocks` : "work_blocks", `work_blocks must be an array, got ${typeof value.work_blocks}.`);
+    }
+    // summary must be an object if present.
+    if ("summary" in value && (typeof value.summary !== "object" || value.summary === null)) {
+        pushValidationIssue(issues, path ? `${path}.summary` : "summary", `summary must be an object, got ${typeof value.summary}.`);
+    }
+    return issues;
+}
+/**
+ * Type-narrowing guard. Returns true only when the value passes structural
+ * validation with no errors. Warnings do not block the guard.
+ *
+ * Unlike the plain `isAuditFindingsReport` in remediate-code/phases/plan.ts,
+ * this guard enforces contract_version presence AND exact match
+ * (INV-shared-core-06 / OBL-C002-VERSION-TRUST). Both absent and mismatched
+ * contract_version produce severity="error" and cause this function to
+ * return false.
+ */
+export function isValidAuditFindingsReport(value) {
+    const issues = validateAuditFindingsReport(value);
+    return issues.filter((i) => i.severity === "error").length === 0;
+}
+//# sourceMappingURL=findingsReport.js.map

package/dist/shared/validation/findingsReport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findingsReport.js","sourceRoot":"","sources":["../../../src/shared/validation/findingsReport.ts"],"names":[],"mappings":"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"}

package/dist/shared/validation/sessionConfig.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SessionConfig validation utilities.
+ *
+ * INV-shared-core-08: ClaudeCodeConfig.dangerously_skip_permissions is a
+ * security-sensitive flag that must be validated/surfaced rather than silently
+ * honored. This module provides the canonical validation pass for SessionConfig
+ * so both orchestrators produce consistent, auditable warnings.
+ */
+import type { ValidationIssue } from "./basic.js";
+/**
+ * Validate a SessionConfig for security-sensitive and misconfiguration issues.
+ *
+ * Returns a (possibly empty) list of ValidationIssues. Severity "error" means
+ * the config cannot be used safely; severity "warning" means the caller should
+ * surface the concern before proceeding.
+ *
+ * INV-shared-core-08: dangerously_skip_permissions=true is flagged as a
+ * high-severity warning so operators are always aware when host permission
+ * checks are being bypassed.
+ */
+export declare function validateSessionConfig(config: unknown, path?: string): ValidationIssue[];
+//# sourceMappingURL=sessionConfig.d.ts.map

package/dist/shared/validation/sessionConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionConfig.d.ts","sourceRoot":"","sources":["../../../src/shared/validation/sessionConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,SAAK,GACR,eAAe,EAAE,CA+BnB"}

package/dist/shared/validation/sessionConfig.js

@@ -0,0 +1,38 @@
+/**
+ * SessionConfig validation utilities.
+ *
+ * INV-shared-core-08: ClaudeCodeConfig.dangerously_skip_permissions is a
+ * security-sensitive flag that must be validated/surfaced rather than silently
+ * honored. This module provides the canonical validation pass for SessionConfig
+ * so both orchestrators produce consistent, auditable warnings.
+ */
+import { pushValidationIssue } from "./basic.js";
+/**
+ * Validate a SessionConfig for security-sensitive and misconfiguration issues.
+ *
+ * Returns a (possibly empty) list of ValidationIssues. Severity "error" means
+ * the config cannot be used safely; severity "warning" means the caller should
+ * surface the concern before proceeding.
+ *
+ * INV-shared-core-08: dangerously_skip_permissions=true is flagged as a
+ * high-severity warning so operators are always aware when host permission
+ * checks are being bypassed.
+ */
+export function validateSessionConfig(config, path = "") {
+    const issues = [];
+    if (config === null || typeof config !== "object") {
+        pushValidationIssue(issues, path, `Expected a SessionConfig object, got ${typeof config}.`);
+        return issues;
+    }
+    const c = config;
+    // INV-shared-core-08: flag dangerously_skip_permissions so it is never
+    // silently honored. This is a security-sensitive flag — bypasses host
+    // permission checks that are the primary guard against unintended writes.
+    if (c["claude_code"] !== null &&
+        typeof c["claude_code"] === "object" &&
+        c["claude_code"]["dangerously_skip_permissions"] === true) {
+        pushValidationIssue(issues, path ? `${path}.claude_code.dangerously_skip_permissions` : "claude_code.dangerously_skip_permissions", "dangerously_skip_permissions is set to true — this bypasses host permission controls and should only be used in fully trusted, isolated environments. Verify this is intentional.", "warning");
+    }
+    return issues;
+}
+//# sourceMappingURL=sessionConfig.js.map

package/dist/shared/validation/sessionConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionConfig.js","sourceRoot":"","sources":["../../../src/shared/validation/sessionConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAe,EACf,IAAI,GAAG,EAAE;IAET,MAAM,MAAM,GAAsB,EAAE,CAAC;IAErC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,mBAAmB,CACjB,MAAM,EACN,IAAI,EACJ,wCAAwC,OAAO,MAAM,GAAG,CACzD,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,CAAC,GAAG,MAAiC,CAAC;IAE5C,uEAAuE;IACvE,sEAAsE;IACtE,0EAA0E;IAC1E,IACE,CAAC,CAAC,aAAa,CAAC,KAAK,IAAI;QACzB,OAAO,CAAC,CAAC,aAAa,CAAC,KAAK,QAAQ;QACnC,CAAC,CAAC,aAAa,CAA6B,CAAC,8BAA8B,CAAC,KAAK,IAAI,EACtF,CAAC;QACD,mBAAmB,CACjB,MAAM,EACN,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,2CAA2C,CAAC,CAAC,CAAC,0CAA0C,EACtG,mLAAmL,EACnL,SAAS,CACV,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/docs/audit-pkg/contracts.md

@@ -0,0 +1,227 @@
+# Contracts
+
+## Versioned surfaces
+
+The public contract is schema-first. Hosts, workers, prompts, and examples
+should point at schemas and validated examples instead of duplicating fragile
+field descriptions.
+
+Important schemas live under `schemas/`, including:
+
+- `audit-code-v1alpha1.schema.json`
+- `audit_result.schema.json`
+- `audit_task.schema.json`
+- `audit_plan_metrics.schema.json`
+- `graph_bundle.schema.json`
+- `runtime_validation_update.example.json` in `examples/`
+
+## Execution envelope (`advance-audit`)
+
+Each `advance-audit` debug step returns a JSON envelope with:
+
+- `contract_version`
+- `audit_state`
+- `selected_obligation`
+- `selected_executor`
+- `progress_made`
+- `artifacts_written`
+- `progress_summary`
+- `next_likely_step`
+- `handoff`
+
+On completion, the canonical outputs are `.audit-tools/audit-report.md` and
+`.audit-tools/audit-findings.json`. Intermediate artifact state is cleaned up
+when the completed report is promoted.
+
+## AuditResult
+
+Workers submit `AuditResult[]` shaped by
+`schemas/audit_result.schema.json`.
+
+Important rules:
+
+- `task_id`, `unit_id`, `pass_id`, and `lens` must match the assigned task
+- every finding lens must match the assigned task lens
+- `file_coverage` is required and must include assigned files only
+- `file_coverage[].total_lines` must match the current file line count
+- finding `affected_files` entries must be objects, not strings
+- finding `evidence` must be an array of plain strings
+- lens steward tasks emit `findings: []` plus `verification` metadata
+
+Validate before ingestion:
+
+```bash
+audit-code validate-results --results /path/to/results.json
+```
+
+## Artifact bundle
+
+The backend stores resumable artifacts under `.audit-artifacts/`, including:
+
+- `repo_manifest.json`
+- `file_disposition.json`
+- `surface_manifest.json`
+- `critical_flows.json`
+- `graph_bundle.json`
+- `unit_manifest.json`
+- `coverage_matrix.json`
+- `risk_register.json`
+- `audit_tasks.json`
+- `audit_plan_metrics.json`
+- `audit_results.jsonl`
+- `runtime_validation_tasks.json`
+- `runtime_validation_report.json`
+- `synthesis_report.json`
+
+Consumers should treat these as versioned JSON artifacts and validate them with
+`audit-code validate` rather than inferring state from filenames alone.
+
+## Step artifacts
+
+The conversation-first `/audit-code` prompt is a loader. It runs
+`audit-code next-step` and then follows only the returned step prompt. The
+backend writes the current step contract to:
+
+- `<artifacts_dir>/steps/current-step.json`
+- `<artifacts_dir>/steps/current-prompt.md`
+
+`current-step.json` uses `contract_version: "audit-code-step/v1alpha1"` and
+includes `step_kind`, `prompt_path`, `status`, `run_id`, `allowed_commands`,
+`stop_condition`, `repo_root`, `artifacts_dir`, and relevant `artifact_paths`.
+
+When semantic review is reached, the backend resolves host dispatch capability
+from `--host-can-dispatch-subagents` (optional boolean flag; bare = true,
+`--no-host-can-dispatch-subagents` = false) → session config
+(`host_can_dispatch_subagents`) → `AUDIT_CODE_HOST_CAN_DISPATCH` → default
+`true`, then renders exactly one review path: packet dispatch (`dispatch_review`)
+or the single-task fallback (`single_task_fallback`). No capability handshake is
+required; pass the flag only to override the resolved default.
+
+`next-step` is the only execution loop; there is no batch entrypoint. Every
+invocation advances one bounded step and renders the actionable step contract
+directly.
+
+## Dispatch packets
+
+Packet dispatch preserves the existing `AuditTask` and `AuditResult`
+contracts. It changes the worker-facing unit of work.
+
+Packets are partitioned just-in-time at dispatch (never persisted); planning
+artifacts are shaped by:
+
+- `schemas/audit_plan_metrics.schema.json`
+- `examples/audit_plan_metrics.example.json`
+
+Normal packet flow:
+
+```text
+audit-code next-step --host-can-dispatch-subagents true
+backend prepares dispatch-plan.json
+conversation launches one worker per dispatch-plan entry
+worker reads entry.prompt_path
+worker submits AuditResult[] through submit-packet
+audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
+```
+
+`audit-code prepare-dispatch --run-id <run_id> --artifacts-dir
+<artifacts_dir>` remains available for compatibility and tests, but generic
+handoff fields point users and prompts to `next-step`.
+
+Packet artifacts:
+
+- `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`
+- `<artifacts_dir>/runs/<run_id>/dispatch-result-map.json`
+- `<artifacts_dir>/runs/<run_id>/task-results/*.prompt.md`
+- `<artifacts_dir>/runs/<run_id>/task-results/*.anchors.json` for isolated
+  large-file packets
+- `<artifacts_dir>/runs/<run_id>/task-results/*.json`
+- `<artifacts_dir>/runs/<run_id>/dispatch-warnings.json` when needed
+
+Workers should reply exactly:
+
+```text
+valid: <packet_id>, findings=<total finding count>
+```
+
+## Graph contract
+
+`graph_bundle.json` is language-neutral. Language-specific extractors may add
+metadata, but consumers should rely on shared edge concepts:
+
+- `from`
+- `to`
+- `kind`
+- optional `direction`
+- optional `confidence` from 0 to 1
+- optional `reason`
+
+Packet planning should use graph edges to explain why files belong together,
+not merely to merge every connected group. Weak or high-fan-in edges should
+become context hints rather than unlimited packet expansion.
+Current deterministic import edges include JS/TS import kinds and Python
+`python-import` / `python-from-import` edges when local modules resolve.
+Current deterministic reference edges also include package entrypoints, package
+script links, workspace/project module links, JSON Schema `$ref` links, schema
+contract test links, bounded JSON Schema suite links, bounded GitHub Actions
+workflow suite links, bounded package script suite links, bounded TypeScript
+type contract suite links, and deterministic test/source naming links.
+
+Consumers should treat graph evidence by authority:
+
+- deterministic directed edges may drive packet expansion when confidence,
+  budget, and fan-in/fan-out guards allow it
+- ownership edges may cluster small bounded groups, but should remain explainable
+  through `key_edges` and packet `quality`
+- semantic-affinity or NLP-style relationships, if added, should default to
+  low-authority context and candidate `boundary_files` unless corroborated by a
+  deterministic edge
+
+Bounded suite links are intentionally narrow: they connect small, same-directory
+contract suites such as `*.schema.json` files, `.github/workflows/*.yml`
+files, package-script-seeded `scripts/` files, or TypeScript files under
+`types/` directories without turning broad directory proximity into packet
+evidence.
+
+Analyzer-supplied ownership roots should use this same graph contract instead
+of requiring packet planners to understand a new language-specific artifact.
+Normalized `external_analyzer_results.json` may include `ownership_roots`;
+structure planning translates each bounded root/path membership into
+`analyzer-ownership-root-link` reference edges. Packet planning then consumes
+those edges through the same bounded `module-ownership-link` clustering path as
+project-file evidence.
+Planner metrics should make it possible to see which edge kinds changed packet
+grouping and which stayed context-only.
+
+`audit_plan_metrics.packet_quality` records that plan-level evidence through
+`merge_edge_kind_counts`, `boundary_edge_kind_counts`, and weak-packet
+diagnostics. Merge counts only include graph edges that joined distinct task
+groups in a final packet; boundary counts include concrete graph edges that
+remained adjacent context instead of internal packet evidence.
+`weakly_explained_gap_counts` summarizes the primary gap type across all weak
+packets, and `weakly_explained_file_extension_counts` summarizes the unique file
+extensions represented by those packets. `weakly_explained_packet_samples` adds
+a bounded snapshot of the weakest packet quality records, including sample file
+paths and the primary gap, so extractor work can be prioritized without scanning
+every packet first.
+
+Review packets may expose graph-derived context for workers:
+
+- `entrypoints` for route or handler context inside the packet
+- `key_edges` for the strongest internal file relationships
+- `boundary_files` for adjacent files that should only be checked when evidence
+  genuinely crosses the packet
+- `quality` metrics for cohesion, internal edges, boundary edges, and
+  unexplained files
+
+## Guided recovery
+
+Failure responses should distinguish:
+
+- rerun the same command
+- import these result/update files
+- fix session config
+- retry a worker submission after schema validation errors
+- perform manual semantic review
+
+Malformed results, invalid config, stale artifacts, and provider failures
+should include field-level or action-level remediation whenever possible.

package/docs/audit-pkg/development.md

@@ -0,0 +1,112 @@
+# Development
+
+## Repository layout
+
+- `src/`: implementation code
+- `schemas/`: JSON schemas for public and internal artifacts
+- `examples/`: validated artifact examples
+- `skills/audit-code/`: canonical prompt and skill-facing instructions
+- `dispatch/`: packet-dispatch support data
+- `tests/`: Node test suite and regression coverage
+- `dist/`: checked-in compiled runtime used by packaged installs
+
+## Agent 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
+
+```bash
+npm install
+npm run check
+npm test
+npm run test:single -- tests/next-step.test.mjs
+npm run verify:release
+```
+
+Run `npm install` from the repository root before running build, check, test, or
+package-scoped workflows in a fresh clone or git worktree. Missing
+`node_modules` can surface as misleading `@audit-tools/shared` export or type
+errors because dependents may resolve stale compiled `dist/` output.
+
+The test suite is intentionally contract-heavy. Update tests when changing
+schema shape, prompt contracts, dispatch behavior, installer output, or release
+workflow semantics.
+
+## Architecture
+
+The system separates deterministic extraction from bounded LLM judgment:
+
+1. intake and file disposition
+2. surface, flow, graph, unit, risk, and coverage artifacts
+3. audit task planning
+4. review packet construction
+5. semantic review through the active conversation or fallback provider bridge
+6. result ingestion, selective deepening, runtime validation, and synthesis
+7. final `audit-report.md`
+
+Portability rules:
+
+- tool-specific collectors write tool-agnostic JSON
+- prompts consume artifacts and bounded source context
+- 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
+artifacts instead of inventing a language-specific planning path.
+
+Avoid adding another bespoke manifest or project-file parser by default. First
+ask whether the signal is common in expected repositories, whether it provides
+direction or ownership that path heuristics cannot, and whether the same value
+could come from a generic analyzer-supplied ownership hint.
+
+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
+  TypeScript type suites when planner metrics show otherwise weak packets
+- external boundary hints
+- line counts and anchor summaries for large files
+
+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 (`eslint.config.*`, `.eslintrc*`,
+`package.json` `eslintConfig`) over executing a globally installed tool and
+parsing its no-config failure.
+
+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.
+
+## 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>