auditor-lambda 0.7.0 → 0.9.0

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.9.0",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",
@@ -23,7 +23,7 @@
     "update-languages": "node scripts/update-languages.mjs",
     "build": "tsc -p tsconfig.json",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test tests/*.test.mjs",
+    "test": "npm run build && node --import tsx/esm --test tests/*.test.mjs",
     "release:patch": "node scripts/release-and-publish.mjs patch --bump-only",
     "release:minor": "node scripts/release-and-publish.mjs minor --bump-only",
     "release:major": "node scripts/release-and-publish.mjs major --bump-only",
@@ -73,6 +73,7 @@
     "ajv": "^8.17.1",
     "linguist-languages": "^9.3.2",
     "tree-sitter-wasms": "^0.1.13",
+    "tsx": "^4.19.0",
     "typescript": "^5.9.2",
     "web-tree-sitter": "^0.25.10"
   }

package/schemas/audit_findings.schema.json

@@ -45,7 +45,8 @@
           "confidence",
           "lens",
           "summary",
-          "affected_files"
+          "affected_files",
+          "evidence"
         ],
         "properties": {
           "id": { "type": "string" },
@@ -56,7 +57,7 @@
             "enum": ["critical", "high", "medium", "low", "info"]
           },
           "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
-          "lens": { "type": "string", "minLength": 1 },
+          "lens": { "type": "string", "enum": ["correctness", "architecture", "maintainability", "security", "reliability", "performance", "data_integrity", "tests", "operability", "config_deployment", "observability"] },
           "summary": { "type": "string" },
           "affected_files": {
             "type": "array",
@@ -76,10 +77,10 @@
           },
           "impact": { "type": "string" },
           "likelihood": { "type": "string" },
-          "evidence": { "type": "array", "items": { "type": "string" } },
-          "reproduction": { "type": "array", "items": { "type": "string" } },
+          "evidence": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "reproduction": { "type": "array", "minItems": 1, "items": { "type": "string" } },
           "systemic": { "type": "boolean" },
-          "related_findings": { "type": "array", "items": { "type": "string" } },
+          "related_findings": { "type": "array", "minItems": 1, "items": { "type": "string" } },
           "theme_id": { "type": "string" }
         },
         "additionalProperties": false

package/schemas/critical_flows.schema.json

@@ -33,8 +33,9 @@
             "items": { "type": "string" }
           },
           "confidence": {
-            "type": "string",
-            "enum": ["high", "low"]
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
           }
         },
         "additionalProperties": false

package/schemas/dispatch_quota.schema.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "audit-code-dispatch-quota/v1alpha2",
   "title": "DispatchQuota",
   "description": "Quota schedule for a prepare-dispatch run. Written beside dispatch-plan.json. Hosts must launch at most wave_size packets per wave, then re-read this file before the next wave to pick up any updated limits.",
@@ -101,6 +101,7 @@
     "quota_source_snapshot": {
       "type": ["object", "null"],
       "description": "Real-time usage snapshot from a QuotaSource, if available.",
+      "additionalProperties": false,
       "properties": {
         "remaining_pct": { "type": ["number", "null"] },
         "reset_at": { "type": ["string", "null"], "format": "date-time" },
@@ -113,6 +114,7 @@
     "backoff_state": {
       "type": ["object", "null"],
       "description": "Exponential backoff state for repeated rate-limit errors.",
+      "additionalProperties": false,
       "properties": {
         "consecutive_429_count": { "type": "integer", "minimum": 0 },
         "current_cooldown_ms": { "type": "integer", "minimum": 0 },

package/schemas/external_analyzer_results.schema.json

@@ -58,8 +58,8 @@
             "enum": ["critical", "high", "medium", "low", "info"]
           },
           "path": { "type": "string" },
-          "line_start": { "type": "integer" },
-          "line_end": { "type": "integer" },
+          "line_start": { "type": "integer", "minimum": 1 },
+          "line_end": { "type": "integer", "minimum": 1 },
           "summary": { "type": "string" },
           "rule": { "type": "string" },
           "raw": {}

package/schemas/graph_bundle.schema.json

@@ -115,7 +115,7 @@
           }
         }
       },
-      "additionalProperties": true
+      "additionalProperties": false
     },
     "analyzers_used": {
       "type": "array",

package/schemas/repo_manifest.schema.json

@@ -15,7 +15,7 @@
       },
       "additionalProperties": false
     },
-    "generated_at": { "type": "string" },
+    "generated_at": { "type": "string", "format": "date-time" },
     "files": {
       "type": "array",
       "items": {

package/schemas/review_packets.schema.json

@@ -29,7 +29,7 @@
     },
     "graphEdge": {
       "type": "object",
-      "required": ["from", "to", "confidence"],
+      "required": ["from", "to"],
       "properties": {
         "from": { "type": "string" },
         "to": { "type": "string" },

package/schemas/step_contract.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "step_contract.schema.json",
+  "title": "Audit Code Step Contract",
+  "description": "The step contract written to steps/current-step.json by audit-code. Describes one bounded step for the host agent to execute.",
+  "type": "object",
+  "required": [
+    "contract_version",
+    "step_kind",
+    "prompt_path",
+    "status",
+    "run_id",
+    "allowed_commands",
+    "stop_condition",
+    "repo_root",
+    "artifacts_dir",
+    "artifact_paths"
+  ],
+  "properties": {
+    "contract_version": { "const": "audit-code-step/v1alpha1" },
+    "step_kind": {
+      "type": "string",
+      "enum": [
+        "dispatch_review",
+        "single_task_fallback",
+        "design_review",
+        "analyzer_install",
+        "edge_reasoning",
+        "edge_reasoning_dispatch",
+        "synthesis_narrative",
+        "present_report",
+        "blocked"
+      ]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["ready", "blocked", "complete"]
+    },
+    "prompt_path": { "type": "string" },
+    "run_id": { "type": ["string", "null"] },
+    "progress": {
+      "type": "object",
+      "required": ["summary"],
+      "properties": {
+        "summary": { "type": "string" },
+        "pending_packets": { "type": "integer" },
+        "pending_tasks": { "type": "integer" },
+        "completed_tasks": { "type": "integer" },
+        "wave_size": { "type": "integer" }
+      },
+      "additionalProperties": false
+    },
+    "allowed_commands": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "allowed_mcp_tools": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "stop_condition": { "type": "string" },
+    "repo_root": { "type": "string" },
+    "artifacts_dir": { "type": "string" },
+    "artifact_paths": {
+      "type": "object",
+      "additionalProperties": { "type": ["string", "null"] }
+    },
+    "access": {
+      "type": "object",
+      "required": ["read_paths", "write_paths"],
+      "properties": {
+        "read_paths": { "type": "array", "items": { "type": "string" } },
+        "write_paths": { "type": "array", "items": { "type": "string" } },
+        "forbidden_patterns": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/scripts/postinstall.mjs

@@ -284,7 +284,6 @@ function mergeOpenCodeGlobalConfig(existing) {
   const parsed = existing ? JSON.parse(existing) : {};
   const auditPermission = renderOpenCodePermissionConfig();
   const existingAuditor = objectValue(objectValue(parsed.agent).auditor);
-  const nodeExecPath = replaceBackslashes(process.execPath);
   const pkgEntrypoint = replaceBackslashes(join(pkgRoot, 'audit-code.mjs'));
   return {
     ...parsed,
@@ -303,7 +302,7 @@ function mergeOpenCodeGlobalConfig(existing) {
       ...objectValue(parsed.mcp),
       auditor: {
         type: 'local',
-        command: [nodeExecPath, pkgEntrypoint, 'mcp'],
+        command: ['node', pkgEntrypoint, 'mcp'],
         enabled: true,
         timeout: 10000,
       },
@@ -380,6 +379,10 @@ if (!promptSource || !skillSource) {
 
 const codexOpenAiAgentSource = readOptionalSource(codexOpenAiAgentSourceFile, 'Codex skill UI metadata');
 
+const postinstallStart = Date.now();
+let succeeded = 0;
+let failed = 0;
+
 const installs = [
   {
     label: 'Claude command',
@@ -415,12 +418,14 @@ for (const install of installs) {
   try {
     const action = writeGeneratedFile(install.path, install.content);
     console.log(`audit-code: ${action} global ${install.label} at ${install.path}`);
+    succeeded++;
   } catch (err) {
     console.warn(`audit-code: could not install global ${install.label} (${err.message})`);
     console.warn(`  To install manually, copy from:`);
     console.warn(`    ${install.sourcePath}`);
     console.warn(`  to:`);
     console.warn(`    ${install.path}`);
+    failed++;
   }
 }
 
@@ -429,8 +434,10 @@ const globalMcpLauncherPath = join(homedir(), '.audit-code', 'run-mcp-server.mjs
 try {
   const action = writeGeneratedFile(globalMcpLauncherPath, Buffer.from(renderGlobalMcpLauncher(pkgRoot)));
   console.log(`audit-code: ${action} global MCP launcher at ${globalMcpLauncherPath}`);
+  succeeded++;
 } catch (err) {
   console.warn(`audit-code: could not install global MCP launcher (${err.message})`);
+  failed++;
 }
 
 // Install OpenCode global command and MCP via merged config
@@ -440,10 +447,12 @@ try {
     mergeOpenCodeGlobalConfig(existing),
   );
   console.log(`audit-code: ${action} global OpenCode config in ${opencodeGlobalConfig}`);
+  succeeded++;
 } catch (err) {
   console.warn(`audit-code: could not install global OpenCode config (${err.message})`);
   console.warn(`  To install manually, add the mcp.auditor and command["audit-code"] entries to:`);
   console.warn(`    ${opencodeGlobalConfig}`);
+  failed++;
 }
 
 // Install Antigravity plugin (global skill for Gemini IDE / Antigravity Hub)
@@ -460,8 +469,10 @@ try {
 
   const skillAction = writeGeneratedFile(antigravityPluginSkillPath, skillSource);
   console.log(`audit-code: ${skillAction} Antigravity plugin skill at ${antigravityPluginSkillPath}`);
+  succeeded++;
 } catch (err) {
   console.warn(`audit-code: could not install Antigravity plugin (${err.message})`);
+  failed++;
 }
 
 // Install Claude Desktop plugin so /audit-code appears in the slash-command menu
@@ -497,9 +508,11 @@ try {
   console.log(`audit-code: ${skillAction} Claude Desktop plugin skill at ${claudePluginSkillPath}`);
 
   console.log(`audit-code: restart Claude Desktop for /audit-code to appear in the slash-command menu`);
+  succeeded++;
 } catch (err) {
   console.warn(`audit-code: could not install Claude Desktop plugin (${err.message})`);
   console.warn(`  Plugin directory: ${claudePluginDir}`);
+  failed++;
 }
 
 // Register auditor MCP server with Claude Desktop so /audit-code appears in its slash-command menu
@@ -511,9 +524,13 @@ try {
   console.log(`audit-code: ${action} Claude Desktop MCP server entry in ${claudeDesktopConfig}`);
   console.log(`audit-code: restart Claude Desktop for /audit-code to appear`);
   console.log(`audit-code: to target a specific repo, set AUDIT_CODE_REPO_ROOT in Claude Desktop's MCP env settings`);
+  succeeded++;
 } catch (err) {
   console.warn(`audit-code: could not update Claude Desktop config (${err.message})`);
   console.warn(`  To register manually, add "mcpServers.auditor" to:`);
   console.warn(`    ${claudeDesktopConfig}`);
   console.warn(`  with command "node" and args ["${replaceBackslashes(globalMcpLauncherPath)}"]`);
+  failed++;
 }
+
+console.log(`audit-code: postinstall complete — ${succeeded} succeeded, ${failed} failed (${Date.now() - postinstallStart}ms)`);

package/skills/audit-code/opencode-command-template.txt

@@ -3,11 +3,11 @@
 Use `audit-code next-step` as the primary interface to the audit workflow.
 
 1. Run `audit-code next-step` directly when shell access is available.
-2. If MCP is your only available interface, call `auditor_start_audit` or `auditor_continue_audit`; both return the same one-step contract.
+2. If MCP is your only available interface, call `start_audit` or `continue_audit`; both return the same one-step contract.
 3. Read `prompt_content` in the response and follow it.
-4. When a step completes (not blocked), run `audit-code next-step` again or call `auditor_continue_audit` as the compatibility adapter.
+4. When a step completes (not blocked), run `audit-code next-step` again or call `continue_audit` as the compatibility adapter.
 5. Stop when the step instructions say to stop.
 
 Use the `task` tool or equivalent for subagent dispatch when the step tells you to fan out review work.
 
-If neither shell access nor `auditor_start_audit` is available, stop and report that no next-step interface is connected.
+If neither shell access nor `start_audit` is available, stop and report that no next-step interface is connected.

package/dist/orchestrator/internalExecutors.d.ts

@@ -1,34 +0,0 @@
-import type { ArtifactBundle } from "../io/artifacts.js";
-import type { AuditResult } from "../types.js";
-import type { RuntimeValidationReport } from "../types/runtimeValidation.js";
-import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
-import type { AuditScopeManifest } from "../types/auditScope.js";
-import type { SynthesisNarrative } from "@audit-tools/shared";
-export interface ExecutorRunResult {
-    updated: ArtifactBundle;
-    artifacts_written: string[];
-    progress_summary: string;
-}
-export declare function resolveRuntimeValidationSpawnCommand(command: string[], platform?: NodeJS.Platform, shellCommand?: string): {
-    command: string;
-    args: string[];
-};
-export declare function runIntakeExecutor(bundle: ArtifactBundle, root: string): Promise<ExecutorRunResult>;
-export declare function runStructureExecutor(bundle: ArtifactBundle, root?: string): Promise<ExecutorRunResult>;
-export declare function runDesignAssessmentExecutor(bundle: ArtifactBundle): ExecutorRunResult;
-export declare function runDesignReviewAutoComplete(bundle: ArtifactBundle): ExecutorRunResult;
-export declare function runPlanningExecutor(bundle: ArtifactBundle, root: string, lineIndex?: Record<string, number>, sizeIndex?: Record<string, number>, scope?: AuditScopeManifest): Promise<ExecutorRunResult>;
-export declare function runResultIngestionExecutor(bundle: ArtifactBundle, results: AuditResult[]): ExecutorRunResult;
-export declare function runRuntimeValidationExecutor(bundle: ArtifactBundle, root: string, options?: {
-    opentoken?: boolean;
-}): Promise<ExecutorRunResult>;
-export declare function runRuntimeValidationUpdateExecutor(bundle: ArtifactBundle, updates: RuntimeValidationReport): ExecutorRunResult;
-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;
-export declare function runExternalAnalyzerImportExecutor(bundle: ArtifactBundle, externalResults: ExternalAnalyzerResults): ExecutorRunResult;