auditor-lambda 0.1.0

package/docs/agent-integrations.md

@@ -0,0 +1,237 @@
+# Agent integrations
+
+This document explains how `auditor-lambda` fits into AI coding agent workflows across editors and provider surfaces.
+
+## Primary product contract
+
+The canonical product surface is the in-conversation `/audit-code` skill.
+
+The repo-local backend fallback is the zero-argument wrapper:
+
+Normal product usage should:
+
+- use the current conversation or editor context as the working context
+- avoid manual `--root`, provider flags, and model selection in normal use
+- let the supervisor advance the audit automatically until it completes or no further automatic progress is possible
+
+## Conversation-first setup
+
+The canonical prompt asset is:
+
+`skills/audit-code/audit-code.prompt.md`
+
+The preferred bootstrap path is:
+
+```bash
+audit-code install
+```
+
+That installs repo-local `/audit-code` surfaces for VS Code / Copilot, OpenCode, Claude Code, and compatibility instruction files such as `AGENTS.md` and `CLAUDE.md`.
+It also writes `.audit-code/install/GETTING-STARTED.md` with dedicated quick-start sections for VS Code, OpenCode, Claude Code, Claude Desktop, and Antigravity.
+
+Use one of these supported ways to obtain the raw prompt asset directly when you need prompt import instead:
+
+1. install the package and run `audit-code prompt-path`
+2. check out the repository and read the file directly from `skills/audit-code/audit-code.prompt.md`
+
+Import that prompt into your editor or conversation environment, or use the bootstrap installer above, then use `/audit-code` in conversation.
+
+## Editor guidance
+
+### ChatGPT project conversations
+
+This is the intended product surface.
+
+Use `/audit-code` in conversation, treat the active conversation model as the default model, and treat project files plus attached repository context as the default context.
+
+### GitHub Copilot
+
+Use `audit-code install` from the target repository root.
+
+That writes `.github/prompts/audit-code.prompt.md` and `.github/copilot-instructions.md` so the repository carries the canonical `/audit-code` instructions instead of relying on manual copy-paste.
+The generated prompt file explicitly sets `agent: agent` so `/audit-code` lands in the tool-capable Copilot agent flow.
+
+The narrower `audit-code install-host --host copilot` alias still exists, but it is no longer the preferred setup path.
+
+### OpenCode
+
+Use `audit-code install` from the target repository root.
+
+That writes `.opencode/commands/audit-code.md` plus `AGENTS.md` and compatibility skills so `/audit-code` is available in the repository with no extra provider flags.
+The generated OpenCode command now sets `agent: build` and keeps the current model selection, which makes the slash command behave more like the intended autonomous editing flow.
+The generated `.audit-code/install/GETTING-STARTED.md` file also includes an OpenCode-specific quick start so the repo-local command path is obvious after bootstrap.
+
+### Claude Code
+
+Use `audit-code install` from the target repository root.
+
+That writes `.claude/commands/audit-code.md`, `CLAUDE.md`, and compatibility skills so `/audit-code` is available in the repository with no extra provider flags.
+The generated `.audit-code/install/GETTING-STARTED.md` file also includes a Claude Code-specific quick start so the repo-local command path is obvious after bootstrap.
+
+### VS Code
+
+Run `audit-code install` from the target repository root, then open `.audit-code/install/GETTING-STARTED.md` if you want the exact repo-local path that bootstrap created for VS Code chat surfaces.
+
+The expected happy path is still to invoke `/audit-code` from chat, not to start from the backend CLI.
+
+### Claude Desktop
+
+Run `audit-code install` from the target repository root, then open `.audit-code/install/GETTING-STARTED.md`.
+
+There is no verified project-local slash-command install surface for Claude Desktop in this repository today, so the intended path is:
+
+1. import `.audit-code/install/audit-code.prompt.md` into Claude Desktop's prompt or instruction surface
+2. invoke `/audit-code` conversationally inside Claude Desktop
+
+### Antigravity
+
+Run `audit-code install` from the target repository root, then open `.audit-code/install/GETTING-STARTED.md`.
+
+There is no verified repo-local slash-command install surface for Antigravity in this repository today, so the intended path is:
+
+1. import `.audit-code/install/audit-code.prompt.md` into Antigravity's prompt or instruction surface when available
+2. invoke `/audit-code` conversationally inside Antigravity
+3. fall back to `audit-code` from an Antigravity-managed terminal only when you intentionally need the repo-local backend wrapper
+
+### Similar manual-import hosts
+
+Use the same installed prompt asset and repo-local guide pattern as Claude Desktop and Antigravity.
+
+The backend CLI remains optional fallback infrastructure.
+
+## Repo-local backend fallback
+
+From the target repository root:
+
+```bash
+audit-code
+```
+
+Use the backend wrapper only when you intentionally need the repo-local fallback, automation harness, or provider-adapter workflow.
+
+## What the wrapper actually does
+
+`audit-code` is the stable backend entrypoint.
+
+It:
+
+- defaults artifacts to `<repo-root>/.audit-artifacts`
+- persists audit continuity there
+- calls `run-to-completion` by default
+- creates fresh worker runs behind the scenes
+- returns a stable top-level JSON contract with `contract_version: "audit-code/v1alpha1"`
+
+## Minimal repo-local flow
+
+From the target repository root:
+
+```bash
+audit-code
+```
+
+Inspect the returned JSON and continue invoking the same entrypoint until either:
+
+- `next_likely_step === null`
+
+Terminal interpretation:
+
+- `audit_state.status === "complete"` means the audit finished end to end.
+- `audit_state.status === "blocked"` means the wrapper exhausted automatic work and the remaining review needs imported results or an interactive provider.
+
+When additional evidence exists, pass it into the same wrapper:
+
+```bash
+audit-code --results /path/to/audit_results.json
+audit-code --updates /path/to/runtime_validation_report.json
+audit-code --external-analyzer-results /path/to/external_analyzer_results.json
+```
+
+Each response also refreshes `.audit-artifacts/operator-handoff.json` and `.audit-artifacts/operator-handoff.md` so operators can see the pending obligations, suggested import paths, and session-config continuation hint without reconstructing the state manually.
+
+Everything below is backend fallback guidance, not the primary product path.
+
+## Provider matrix
+
+### local-subprocess
+
+Use when you want the supervisor to stay entirely local.
+
+This requires no external agent CLI. The supervisor launches fresh worker subprocesses that call the bounded `worker-run` entrypoint for deterministic stages.
+
+When the remaining work is genuinely audit-task review, `local-subprocess` stops in a terminal blocked handoff instead of pretending more automatic progress is available.
+
+This is the safest default backend when the repository is already available locally.
+
+### claude-code
+
+Use when Claude Code is installed and authenticated on the machine.
+
+The built-in adapter launches a fresh Claude Code print-mode session for each worker run.
+
+Recommended when you want the audit supervisor to delegate bounded tasks into Claude Code without manually driving each step.
+
+### opencode
+
+Use when OpenCode is installed and authenticated on the machine.
+
+The built-in adapter launches a fresh `opencode run ...` session for each worker run.
+
+Recommended when OpenCode is the preferred local agent surface.
+
+### subprocess-template
+
+Use when you need a generic bridge.
+
+This is the escape hatch for editors, launchers, or agent shells that do not yet have a dedicated provider adapter. The supervisor renders a templated command and executes it as a fresh worker run.
+
+### vscode-task
+
+Use when you already have a repository-local or machine-local task bridge and want the supervisor to call that bridge through a command template.
+
+Treat this as an advanced backend adapter rather than the default path.
+
+### Claude Code
+
+Use the repo-local `audit-code` wrapper from the target repository root, or set `provider` to `claude-code` in `.audit-artifacts/session-config.json` so the supervisor delegates bounded worker runs into Claude Code.
+
+### OpenCode
+
+Use the same repo-local `audit-code` wrapper, or set `provider` to `opencode` so the supervisor delegates bounded worker runs into OpenCode.
+
+### VS Code
+
+Run `audit-code install` once from the target repository root, then use `/audit-code` from chat.
+
+The backend fallback is still available from the integrated terminal and should keep `local-subprocess` unless you specifically need a task bridge.
+
+If you already have a launcher or task surface that should own fresh worker windows, use `vscode-task` or `subprocess-template`.
+
+### Google Antigravity
+
+No dedicated Antigravity provider adapter is shipped today.
+
+Current recommended usage is one of these:
+
+- use the skill-first conversational contract as the primary surface
+- run `audit-code install` first so compatibility files are present
+- run `audit-code` from an Antigravity-managed terminal with `local-subprocess`
+- use `subprocess-template` if you have a reliable Antigravity-side launcher bridge
+
+That keeps the product usable in Antigravity now without pretending that a native adapter already exists.
+
+## Model-selection rule
+
+The product direction remains skill-first:
+
+- in conversation, use the active conversation model by default
+- for backend CLI delegation, let the chosen provider own its own model-selection behavior unless explicitly configured otherwise
+
+## Practical recommendation
+
+For a polished operator experience today:
+
+1. treat `/audit-code` as the canonical user-facing contract
+2. use `audit-code install` first, and fall back to `audit-code prompt-path` only for hosts that still require manual prompt import
+3. use `audit-code` as the repo-local backend fallback
+4. prefer `local-subprocess` unless you need interactive review to continue through agent tasks
+5. use `subprocess-template` only when integrating a non-native editor or launcher surface

package/docs/agent-roles.md

@@ -0,0 +1,69 @@
+# Agent roles
+
+## Principles
+
+Each agent should consume bounded artifacts and return structured outputs. Agents should not invent process rules.
+
+## Roles
+
+### intake-normalizer
+
+- validates repository intake artifacts
+- flags suspicious exclusions
+- confirms stack profile
+
+### structural-mapper
+
+- reviews extracted units, surfaces, and graph artifacts
+- resolves ambiguous file classifications
+- flags missing boundaries
+
+### blind-spot-mapper
+
+- identifies repo-specific blind spots tools may miss
+- flags hidden operational or security-critical surfaces
+- proposes additional lenses or dynamic checks
+
+### correctness-auditor
+
+- checks whether code behavior appears to match intent
+- focuses on edge cases, defaults, assumptions, and branch handling
+
+### architecture-auditor
+
+- inspects layering, boundaries, coupling, abstraction fit, and dependency direction
+
+### security-auditor
+
+- inspects trust boundaries, auth/authz, validation, secret handling, risky sinks, and exploitability
+
+### reliability-auditor
+
+- inspects retries, timeouts, idempotency, partial failures, crash consistency, and concurrency risk
+
+### performance-auditor
+
+- inspects hot paths, repeated work, query inefficiency, algorithmic issues, memory pressure, and scalability risk
+
+### data-integrity-auditor
+
+- inspects invariants, migrations, transactional boundaries, schema drift, consistency, and race conditions
+
+### test-auditor
+
+- inspects test adequacy, missing negative-path coverage, brittle tests, and false confidence
+
+### operability-auditor
+
+- inspects logging, metrics, tracing, debuggability, startup validation, and runtime observability
+
+### cross-cutting-auditor
+
+- audits repo-wide themes such as auth, retries, migrations, config validation, feature flags, and secrets flow
+
+### synthesizer
+
+- merges duplicate findings
+- clusters root causes
+- prioritizes fixes
+- identifies quick wins vs structural work

package/docs/architecture.md

@@ -0,0 +1,90 @@
+# 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

@@ -0,0 +1,69 @@
+# Core artifacts
+
+These JSON artifacts are the stable contract between deterministic tooling and LLM audit passes.
+
+## Core files
+
+- `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`
+- `runtime_validation_report.json`
+- `external_analyzer_results.json`
+- `audit_results.json`
+- `requeue_tasks.json`
+- `merged_findings.json`
+- `root_cause_clusters.json`
+- `synthesis_report.json`
+
+## Design rule
+
+Tool-specific collectors should write into these normalized formats so that the agent layer can remain portable across runtimes.
+
+## Coverage rule
+
+Coverage is not based only on test instrumentation. It is based on explicit audit accounting:
+
+- file classification
+- file disposition
+- unit assignment
+- required lenses
+- reviewed source ranges
+- completed passes
+- requeue targets for missing review
+- critical-flow coverage state
+
+## Excluded artifact behavior
+
+Files marked as generated, vendor, binary, doc-only, or explicitly excluded should remain visible in manifests and disposition tracking, but should not receive normal audit-unit assignment or requeue tasks.
+
+## Critical flow role
+
+`critical_flows.json` is intended to bridge deterministic planning and higher-order semantic review. It gives LLM agents a bounded way to inspect important end-to-end paths without reading the entire repository at once.
+
+`flow_coverage.json` tracks whether those important paths have received the intended lenses, which allows the planner to treat critical-flow review as a first-class coverage requirement rather than a loose advisory layer.
+
+## Runtime validation role
+
+`runtime_validation_tasks.json` turns unresolved high-risk units and incomplete critical flows into explicit dynamic follow-up work.
+
+`runtime_validation_report.json` is where evidence from those checks should land so that later synthesis can distinguish confirmed, not-confirmed, and inconclusive concerns.
+
+## External analyzer role
+
+`external_analyzer_results.json` is the normalized landing zone for third-party tools such as SAST analyzers, coverage summaries, lint diagnostics, dependency scanners, and similar sources. Downstream prompts should prefer this normalized form over raw tool-native payloads.
+
+External analyzer results now also influence:
+
+- risk scoring
+- required lenses in coverage
+- task priority
+- dedicated analyzer follow-up tasks
+- requeue priority
+- synthesis evidence and summaries

package/docs/bootstrap-install.md

@@ -0,0 +1,79 @@
+# Bootstrap install
+
+The intended setup flow is a single bootstrap step from the target repository root:
+
+```bash
+audit-code install
+```
+
+That command installs the repo-local `/audit-code` surfaces we can automate today.
+
+## What it writes
+
+Installed command surfaces:
+
+- `.github/prompts/audit-code.prompt.md` for VS Code chat prompt files, with `agent: agent`
+- `.opencode/commands/audit-code.md` for OpenCode custom commands, with `agent: build`
+- `.claude/commands/audit-code.md` for Claude Code custom slash commands
+
+Installed always-on compatibility surfaces:
+
+- `.github/copilot-instructions.md`
+- `AGENTS.md`
+- `CLAUDE.md`
+
+Installed repo-local canonical assets:
+
+- `.audit-code/install/audit-code.prompt.md`
+- `.audit-code/install/SKILL.md`
+- `.audit-code/install/GETTING-STARTED.md`
+
+The generated `GETTING-STARTED.md` now includes dedicated quick-start sections for:
+
+- VS Code
+- OpenCode
+- Claude Code
+- Claude Desktop
+- Antigravity
+
+Installed compatibility skill bundles:
+
+- `.opencode/skills/audit-code/*`
+- `.claude/skills/audit-code/*`
+- `.agents/skills/audit-code/*`
+
+## Goal
+
+After bootstrap, the user should be able to open a supported conversation surface in the repository and invoke:
+
+```text
+/audit-code
+```
+
+without supplying extra root paths, provider flags, or model-selection arguments.
+
+## What is fully automated today
+
+- VS Code and GitHub Copilot repo-local prompt surfaces
+- OpenCode project command surfaces
+- Claude Code project command surfaces
+- tool-agnostic compatibility instruction files for hosts that honor `AGENTS.md` or `CLAUDE.md`
+
+## What is not fully automated today
+
+- Claude Desktop does not currently have a verified project-local slash-command install surface in this repository
+- Antigravity does not currently have a verified repo-local slash-command install surface in this repository
+
+For those hosts, the bootstrap command still installs compatibility assets, but the final `/audit-code` discovery behavior remains host-dependent.
+
+Use `.audit-code/install/GETTING-STARTED.md` as the low-guess repo-local handoff for those manual prompt-import paths and for the exact VS Code, OpenCode, and Claude Code bootstrap surfaces that were 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.

package/docs/contract.md

@@ -0,0 +1,140 @@
+# audit-code response contract
+
+This document describes the backend fallback JSON response contract for the `audit-code` wrapper.
+
+The canonical product remains `/audit-code` in conversation.
+
+## Backend fallback commands
+
+Repo-local fallback command from the target repository root:
+
+```bash
+audit-code
+```
+
+Installed helper for locating the packaged conversation prompt asset:
+
+```bash
+audit-code prompt-path
+```
+
+Installed helper for validating the current backend artifact bundle:
+
+```bash
+audit-code validate
+```
+
+Repository-local wrapper equivalent:
+
+```bash
+node audit-code.mjs
+```
+
+## Contract version
+
+Every canonical wrapper response includes:
+
+```text
+contract_version: audit-code/v1alpha1
+```
+
+Consumers should verify this value before assuming the response shape.
+
+## Source of truth
+
+The versioned JSON schema is:
+
+```text
+schemas/audit-code-v1alpha1.schema.json
+```
+
+Product tests validate live wrapper output against that schema.
+
+## Reproducible installed-command smoke check
+
+From the repository root:
+
+```bash
+npm install
+npm run build
+npm link
+npm run smoke:linked-audit-code
+```
+
+This exercises the installed backend fallback command end-to-end and validates the emitted JSON against the versioned schema.
+
+## Top-level fields
+
+The current v1alpha1 contract includes these top-level fields:
+
+- `contract_version`
+- `audit_state`
+- `selected_obligation`
+- `selected_executor`
+- `progress_made`
+- `artifacts_written`
+- `progress_summary`
+- `next_likely_step`
+- `handoff`
+
+`handoff` is a companion operator-context object. It includes:
+
+- current top-level status
+- repo and artifacts paths
+- pending obligations
+- suggested evidence-import paths and commands when manual continuation is required
+- stable paths to companion handoff files under `.audit-artifacts`
+
+## Terminal states
+
+Consumers should continue invoking the same wrapper until:
+
+1. `next_likely_step == null`
+
+Terminal interpretation:
+
+- `audit_state.status == "complete"` means the audit finished end to end.
+- `audit_state.status == "blocked"` means no further automatic progress is available and the remaining work needs imported results or an interactive provider.
+- `progress_made` tells you whether the current invocation wrote additional artifacts before it reached that terminal state.
+
+When the wrapper emits a response, it also refreshes:
+
+- `.audit-artifacts/operator-handoff.json`
+- `.audit-artifacts/operator-handoff.md`
+
+Those files mirror the structured `handoff` guidance in machine-readable and human-readable forms.
+
+## Audit state shape
+
+`audit_state` includes:
+
+- `status`
+- `obligations`
+- optional `last_executor`
+- optional `last_obligation`
+- optional `blockers`
+
+`status` is one of:
+
+- `not_started`
+- `active`
+- `blocked`
+- `complete`
+
+Each obligation includes:
+
+- `id`
+- `state`
+- optional `reason`
+
+Obligation `state` is one of:
+
+- `missing`
+- `present`
+- `stale`
+- `blocked`
+- `satisfied`
+
+## Compatibility note
+
+This contract is versioned as `v1alpha1` deliberately. It is stable enough for current product use, but it should still be treated as pre-v1.