auditor-lambda 0.3.13 → 0.3.15

package/docs/architecture.md

@@ -1,90 +0,0 @@
-# Architecture
-
-## Objective
-
-`auditor-lambda` is a portable code-auditing framework for arbitrary repositories. It separates deterministic extraction from bounded LLM judgment so that large or mixed-language codebases can be audited systematically.
-
-## Design principles
-
-1. Tool outputs first
-2. Artifact-driven orchestration
-3. Bounded LLM tasks
-4. Explicit coverage accounting
-5. Multi-pass review for critical code
-6. Strict schemas for interoperability
-
-## System layers
-
-### 1. Intake
-
-- file discovery
-- stack detection
-- ignore handling
-- normalization
-
-### 2. Extractors
-
-- service and package detection
-- route, job, command, workflow extraction
-- file bucketing
-- graph extraction
-
-### 3. Mechanical analyzers
-
-- lint
-- typecheck
-- tests
-- test coverage
-- secret scanning
-- dependency scanning
-- static security scanning
-- complexity and duplication metrics
-
-### 4. Orchestrator
-
-- builds audit units
-- assigns passes and lenses
-- chunks large files
-- tracks line coverage and pass overlap
-- requeues uncovered ranges
-
-### 5. LLM agents
-
-- ambiguous classification
-- blind-spot mapping
-- per-lens audits
-- cross-cutting audits
-- synthesis
-
-### 6. Validation
-
-- targeted runtime checks
-- startup/config probes
-- adversarial repros
-
-### 7. Reporting
-
-- normalized findings
-- coverage matrices
-- root-cause clustering
-- remediation planning
-
-## Core pipeline
-
-1. Intake and normalize repository
-2. Extract structure and graph artifacts
-3. Run mechanical analyzers
-4. Build audit units and risk register
-5. Run blind-spot mapping
-6. Run lens-based unit audits
-7. Run cross-cutting audits
-8. Run dynamic validation on targeted cases
-9. Verify file and line coverage
-10. Synthesize findings and remediation plan
-
-## Portability rules
-
-- Tool-specific collectors should write into tool-agnostic JSON artifacts.
-- LLM prompts should consume artifacts, not raw repos by default.
-- All review work should be attributable to files, line ranges, lenses, and passes.
-- Coverage gaps should be machine-detectable.

package/docs/artifacts.md

@@ -1,36 +0,0 @@
-# Core Artifacts
-
-This document follows [audit-goals.md](C:/Code/auditor-lambda/spec/audit-goals.md).
-
-## Incomplete-run artifacts
-
-During an incomplete or blocked audit, `.audit-artifacts/` may contain:
-
-- `repo_manifest.json`
-- `file_disposition.json`
-- `unit_manifest.json`
-- `graph_bundle.json`
-- `surface_manifest.json`
-- `critical_flows.json`
-- `flow_coverage.json`
-- `risk_register.json`
-- `coverage_matrix.json`
-- `runtime_validation_tasks.json` when deterministic runtime validation is planned
-- `runtime_validation_report.json` when runtime validation has executed or been updated
-- `external_analyzer_results.json`
-- `audit_tasks.json`
-- `audit_results.jsonl`
-- `requeue_tasks.json`
-- dispatch files for the currently active worker task
-
-## Scope rule
-
-Excluded files remain visible in deterministic intake/disposition where useful,
-but they must not create audit work. This includes logs, licenses, lockfiles,
-generated artifacts, vendored artifacts, binaries, and trivial non-code files.
-
-## Completion rule
-
-These artifacts are transient implementation state only. When the audit
-completes, `.audit-artifacts/` is removed and only repo-root `audit-report.md`
-remains.

package/docs/bootstrap-install.md

@@ -1,136 +0,0 @@
-# Bootstrap install
-
-The intended user setup is one global package install:
-
-```bash
-npm install -g auditor-lambda
-```
-
-That makes the `audit-code` command available from any repository. Package
-install also seeds user-level command or skill assets for hosts we can update
-safely, including the Claude command file and global Codex skill bundle.
-
-After that, the normal user flow is to invoke `/audit-code` in a supported host.
-The prompt starts by running:
-
-```bash
-audit-code ensure --quiet
-```
-
-`ensure` is idempotent. From the target repository root, it writes the
-repo-local `/audit-code` surfaces only when they are missing or stale.
-
-The explicit repair or compatibility command remains:
-
-```bash
-audit-code install
-```
-
-That command always rewrites the repo-local `/audit-code` surfaces we can
-automate today. `audit-code ensure --force` is the equivalent self-bootstrap
-entrypoint when you want forced refresh semantics.
-The generated manifest records the canonical prompt and skill source paths so
-host surfaces can be checked against one shared source of truth instead of
-drifting independently.
-
-After bootstrap, run:
-
-```bash
-audit-code verify-install
-```
-
-That smoke-tests the generated host assets plus the shared repo-local MCP launcher without waiting for a full editor walkthrough.
-
-## What it writes
-
-Installed shared surfaces:
-
-- `.audit-code/install/audit-code.import.md`
-- `.audit-code/install/SKILL.md`
-- `.audit-code/install/GETTING-STARTED.md`
-- `.audit-code/install/manifest.json`
-- `.audit-code/install/run-mcp-server.mjs`
-- `.audit-artifacts/session-config.json` when no backend fallback config exists yet
-
-Installed host-specific surfaces:
-
-- Codex:
-  - `AGENTS.md` managed fallback block when needed
-- Claude Desktop:
-  - `.audit-code/install/claude-desktop/PROJECT-TEMPLATE.md`
-  - `.audit-code/install/claude-desktop/remote-mcp-connector.json`
-  - `.audit-code/install/claude-desktop/auditor-lambda.dxt`
-  - `.audit-code/install/claude-desktop/auditor-lambda.mcpb`
-- OpenCode:
-  - `.opencode/commands/audit-code.md`
-  - `.opencode/skills/audit-code/*`
-  - `opencode.json`
-  - `AGENTS.md` managed block when needed
-- VS Code:
-  - `.github/prompts/audit-code.prompt.md`
-  - `.github/copilot-instructions.md`
-  - `.github/agents/auditor.agent.md`
-  - `.vscode/mcp.json`
-- Antigravity:
-  - `.audit-code/install/antigravity/PLANNING-MODE.md`
-  - `AGENTS.md` managed block when needed
-
-The generated `GETTING-STARTED.md` now includes dedicated quick-start sections for:
-
-- Codex
-- Claude Desktop
-- OpenCode
-- VS Code
-- Antigravity
-
-## Goal
-
-After bootstrap, the user should be able to open a supported host surface in the repository and invoke:
-
-```text
-/audit-code
-```
-
-without supplying extra root paths, provider flags, or model-selection arguments, or connect through the shared MCP server when the host prefers tool-driven integration.
-
-## What is fully automated today
-
-- global `npm install -g auditor-lambda` seeds user-level Claude command and
-  global Codex skill assets when filesystem permissions allow it
-- `/audit-code` runs `audit-code ensure --quiet` before advancing the audit
-- shared installer output, manifest generation, and repo-local MCP launcher generation
-- default backend fallback session-config creation when no config exists yet
-- Codex global-skill and AGENTS-oriented install output
-- OpenCode command, skill, prompt, and config generation
-- VS Code prompt, custom-agent, instruction, and MCP config generation
-- Claude Desktop project-template, remote-connector, and local bundle generation
-- Antigravity planning-mode guidance generation
-
-## What is not fully automated today
-
-- product-level smoke validation for the generated Codex, Claude Desktop, OpenCode, VS Code, and Antigravity assets
-- one-click proof that the generated Claude Desktop bundle installs cleanly in a real Desktop environment
-- documented Antigravity artifact round-tripping back through `import_results` and `import_runtime_updates`
-
-For those gaps, the bootstrap command now writes the repo-local assets and guidance, but the final operator experience still needs end-to-end host verification.
-
-Use `.audit-code/install/GETTING-STARTED.md` as the low-guess repo-local handoff, and treat `.audit-code/install/manifest.json` as the machine-readable source of truth for what was generated.
-
-## Narrow compatibility alias
-
-The older host-specific helper still exists:
-
-```bash
-audit-code install-host --host copilot
-```
-
-Use it only when you intentionally want the smaller Copilot-only install path instead of the default bootstrap.
-
-## Remaining steps
-
-The installer foundation is now in place. The remaining work is:
-
-1. smoke-test each claimed host in the real product, not only via file-generation tests
-2. tighten `GETTING-STARTED.md` and host-specific setup docs where those smoke tests show friction
-3. prove the Claude Desktop local bundle install path operationally
-4. document Antigravity artifact-import workflows more concretely

package/docs/contract.md

@@ -1,54 +0,0 @@
-# audit-code Response Contract
-
-This document follows [audit-goals.md](C:/Code/auditor-lambda/spec/audit-goals.md).
-
-## Canonical output
-
-The authoritative completed-audit output is repo-root `audit-report.md`.
-
-Until completion, the wrapper response remains a JSON envelope with:
-
-- `contract_version`
-- `audit_state`
-- `selected_obligation`
-- `selected_executor`
-- `progress_made`
-- `artifacts_written`
-- `progress_summary`
-- `next_likely_step`
-- `handoff`
-
-## AuditResult contract
-
-Workers submit `AuditResult[]` shaped by `schemas/audit_result.schema.json`.
-
-Important rules:
-
-- `file_coverage` is required and must include every assigned file.
-- `file_coverage` must not include files outside the assigned task.
-- `file_coverage[].total_lines` must match the current file line count.
-- `task_id`, `unit_id`, `pass_id`, and `lens` must match the assigned task.
-- each finding lens must match the assigned task lens.
-- `findings[].affected_files` must be objects, not strings.
-- `findings[].evidence` must be an array of plain strings.
-- lens steward tasks are tagged `lens_verification`; they must emit
-  `findings: []` plus `verification` metadata. Suggested `verification.followup_tasks`
-  are treated as bounded follow-up requests, not direct findings.
-
-Use `audit-code validate-results --results <file>` before ingestion to validate
-results against the active task manifest.
-
-## Internal artifacts during incomplete runs
-
-The engine may keep resumable artifacts under `.audit-artifacts/`, including:
-
-- intake/structure/planning artifacts
-- `audit_tasks.json`
-- `audit_results.jsonl`
-- `requeue_tasks.json`
-- `runtime_validation_tasks.json`
-- `runtime_validation_report.json` when runtime validation is planned
-- dispatch files for the active worker task
-
-These artifacts are internal and transient. On successful completion, they are
-cleared out and only `audit-report.md` remains.

package/docs/dispatch-implementation-plan.md

@@ -1,302 +0,0 @@
-# Dispatch Automation Reference
-
-This document describes the implemented review-dispatch path for `/audit-code`.
-The original dispatch plan was one agent per audit task. The current path keeps
-the existing `AuditTask` and `AuditResult` contracts, but groups related tasks
-into review packets so a worker can read a coherent file set once and submit
-one validated result for each assigned task through a backend-owned write path.
-
-## Current Workflow
-
-```text
-1. audit-code
-   -> advances deterministic state until semantic review is needed
-   -> emits a blocked handoff with active_review_run.run_id
-
-2. audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
-   -> reads pending-audit-tasks.json and review planning artifacts
-   -> writes a slim dispatch-plan.json
-   -> writes backend-owned dispatch-result-map.json
-   -> writes one packet prompt per dispatch-plan entry
-   -> prints one compact JSON envelope
-
-3. Conversation orchestrator reads only dispatch-plan.json
-   -> launches one subagent per packet
-   -> each subagent reads its packet prompt and assigned files
-   -> each subagent pipes AuditResult[] to the submit-packet command in the prompt
-   -> submit-packet validates and writes only backend-assigned result files
-   -> each subagent replies: valid: <packet_id>, findings=<n>
-
-4. audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
-   -> validates that every assigned task has exactly one valid result
-   -> rejects missing, unknown, duplicate, malformed, or out-of-scope results
-   -> writes audit-results.json as the existing AuditResult[] shape
-   -> ingests accepted results through the normal result_ingestion_executor
-   -> prints one compact JSON envelope
-
-5. Repeat `audit-code` until complete.
-```
-
-The parent orchestrator should not read prompt files, pending tasks, completed
-task result payloads, or source files during the packet dispatch path unless a
-backend command fails and the error requires diagnosis.
-
-## Planning Artifacts
-
-Planning writes two packet-specific artifacts alongside the existing task and
-coverage artifacts:
-
-- `review_packets.json`: deterministic packets derived from current
-  `AuditTask` records.
-- `audit_plan_metrics.json`: task count, packet count, repeated file/line
-  estimates, largest packet, and estimated agent-count reduction.
-
-Packets preserve task identity. They change the worker-facing unit of work, not
-the backend-owned validation or ingestion contract.
-
-## Packet Construction
-
-Packet planning is deterministic and compatibility-preserving:
-
-- tasks sharing the same file set and scope are grouped across lenses
-- tiny homogeneous test files are batched before dispatch
-- graph edges from imports, calls, and references can merge related task groups
-- heuristic container edges do not force packet expansion
-- packet chunking respects task-count and line-budget limits
-- a single file that exceeds the packet target is isolated rather than split
-- high-priority packets sort ahead of lower-priority packets
-
-Generated packets include:
-
-```json
-{
-  "packet_id": "src-auth:security-correctness:packet-1-...",
-  "task_ids": ["src-auth:security", "src-auth:correctness"],
-  "lenses": ["security", "correctness"],
-  "file_paths": ["src/api/auth.ts", "src/lib/session.ts"],
-  "total_lines": 70,
-  "estimated_tokens": 1180
-}
-```
-
-## `prepare-dispatch` Output
-
-Command:
-
-```bash
-audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
-```
-
-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/<packet_id>.prompt.md`
-- `<artifacts_dir>/runs/<run_id>/task-results/<packet_id>.anchors.json`,
-  only for isolated large-file packets
-- `<artifacts_dir>/runs/<run_id>/dispatch-warnings.json`, only when warnings
-  exist
-
-The command prints a compact JSON envelope:
-
-```json
-{
-  "run_id": "run-1",
-  "dispatch_plan_path": ".audit-artifacts/runs/run-1/dispatch-plan.json",
-  "packet_count": 4,
-  "task_count": 18,
-  "largest_packet": {
-    "packet_id": "src-auth:security-correctness:packet-1-...",
-    "total_lines": 1320,
-    "estimated_tokens": 6180
-  },
-  "warning_count": 0,
-  "dispatch_warnings_path": null
-}
-```
-
-`dispatch-plan.json` entries are intentionally small:
-
-```json
-{
-  "packet_id": "src-auth:security-correctness:packet-1-...",
-  "description": "Audit 2 file(s), 2 task(s), 2 lens(es) (~70 lines)",
-  "prompt_path": ".audit-artifacts/runs/run-1/task-results/src-auth_security-correctness_packet-1_ab12cd34ef56.prompt.md",
-  "complexity": {
-    "priority": "high",
-    "task_count": 2,
-    "file_count": 2,
-    "total_lines": 70,
-    "estimated_tokens": 1180,
-    "lenses": ["security", "correctness"],
-    "tags": ["critical_flow"],
-    "large_file_mode": false
-  },
-  "model_hint": {
-    "tier": "deep",
-    "reasons": ["high_priority", "critical_flow"]
-  }
-}
-```
-
-The orchestrator should launch one subagent per entry with the entry
-description and a prompt that tells the subagent to read and follow
-`entry.prompt_path`.
-If the host supports per-subagent model selection, it may map
-`entry.model_hint.tier` (`small`, `standard`, or `deep`) to local model names.
-These hints are provider-neutral; the backend does not hardcode model names or
-require model selection during normal use.
-
-## Large File Mode
-
-The workflow does not impose a hard single-file size limit. When a packet is
-large because it contains one large file, `prepare-dispatch` keeps that file in
-an isolated packet and writes a mechanical anchor summary next to the packet
-prompt. The anchor summary may include:
-
-- file boundaries
-- imports and exports
-- top-level symbols
-- route-like declarations
-- risk keywords
-- graph edges
-- external analyzer signals
-
-The packet prompt points the worker at the anchor file and asks for targeted
-reads/searches within the assigned file. The backend still validates and writes
-results through `submit-packet`. This keeps large-file review bounded by
-mechanically generated structure without slicing files into arbitrary line
-ranges.
-
-## Packet Prompt Contract
-
-Each packet prompt tells the worker to:
-
-- review the packet once
-- read only the listed repo-relative files
-- produce one JSON object per listed task
-- pipe one JSON array to the prompt's `submit-packet` command
-- preserve the existing `AuditResult` fields:
-  `task_id`, `unit_id`, `pass_id`, `lens`, `file_coverage`, `findings`
-- keep `file_coverage[]` as `{ path, total_lines }`
-- keep every finding lens equal to the task lens
-- avoid direct file writes, source edits, remediation, extra task results, and
-  unrelated audits
-- reply exactly `valid: <packet_id>, findings=<total finding count>` after the
-  submit command accepts the packet
-
-This keeps packet review efficient while leaving merge and ingestion
-mechanically deterministic.
-
-## Submission and Validation
-
-Packet submission is exposed through:
-
-```bash
-audit-code submit-packet --run-id <run_id> --packet-id <packet_id> --artifacts-dir <artifacts_dir>
-```
-
-The command reads `AuditResult[]` from stdin, validates the complete assigned
-packet, and writes only the backend-assigned per-task result paths from
-`dispatch-result-map.json`. This keeps result writes out of the LLM prompt and
-prevents swapped or unknown task result files from being ingested.
-
-Per-task validation is exposed through:
-
-```bash
-audit-code validate-result --run-id <run_id> --task-id <task_id> --artifacts-dir <artifacts_dir>
-```
-
-Generated packet prompts may pass run ids, packet ids, task ids, and artifact paths through
-base64url flags such as `--run-id-b64`, `--packet-id-b64`, `--task-id-b64`, and
-`--artifacts-dir-b64` when raw values could contain shell-sensitive characters.
-
-The validator checks the result against the assigned task set and enforces the
-mechanical constraints that matter for ingestion:
-
-- required `AuditResult` and finding fields
-- finding lens matches the task lens
-- cited and affected paths are in assigned coverage
-- line spans do not exceed known `total_lines`
-- result fields conform to the shipped schemas
-
-Workers should retry rejected submissions up to the bounded retry count in the prompt.
-
-## `merge-and-ingest` Output
-
-Command:
-
-```bash
-audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
-```
-
-Merge behavior:
-
-- validates every backend-assigned result-map path
-- rejects unexpected JSON files under `task-results/`
-- rejects task IDs that appear in the wrong assigned result path
-- rejects duplicate task results
-- rejects unknown task IDs
-- rejects missing assigned task results
-- writes `failed-tasks.json` and exits non-zero when any assigned result is
-  missing or invalid
-- writes `audit-results.json` only from passing results
-- invokes the normal result ingestion path only after the assigned set is clean
-
-On success the command prints one compact JSON envelope:
-
-```json
-{
-  "run_id": "run-1",
-  "status": "completed",
-  "accepted_count": 18,
-  "rejected_count": 0,
-  "finding_count": 3,
-  "audit_results_path": ".audit-artifacts/runs/run-1/audit-results.json",
-  "selected_executor": "result_ingestion_executor",
-  "progress_made": true,
-  "progress_summary": "Ingested 18 audit result entries and refreshed dependent artifacts.",
-  "next_likely_step": "runtime_validation"
-}
-```
-
-If the command exits non-zero, the orchestrator should stop and report the exact
-error instead of manually editing task results or audit state.
-
-## Selective Deepening
-
-Result ingestion may add follow-up `AuditTask` records for bounded selective
-deepening. Triggers include:
-
-- high-severity findings
-- low-confidence or ambiguous findings
-- conflicting conclusions across related results
-- high-risk no-finding sampling unless explicitly marked unnecessary
-- runtime-validation disagreement
-
-When follow-up tasks are added, the backend refreshes `review_packets.json` and
-`audit_plan_metrics.json`. The next dispatch cycle handles those tasks through
-the same packet contract.
-
-## Compatibility Notes
-
-- `AuditTask` remains the planning and coverage identity.
-- `AuditResult[]` remains the ingestion shape.
-- The older `.audit-artifacts/dispatch/current-*` files still exist for
-  repo-local backend fallback and single-task handoff flows.
-- Backend provider adapters remain compatibility bridges. The canonical
-  `/audit-code` flow expects the active conversation orchestrator to dispatch
-  packet subagents when the host supports them.
-- The `dispatch/` directory is packaged because `lens-definitions.json` and
-  validation support are part of the installed packet workflow.
-
-## Verification
-
-Run the normal project gate:
-
-```bash
-npm test
-```
-
-Focused packet coverage lives in `tests/review-packets.test.mjs` and
-`tests/audit-code-wrapper.test.mjs`.