auditor-lambda 0.3.12 → 0.3.14

package/schemas/review_packets.schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "review_packets.schema.json",
+  "title": "Review Packets",
+  "type": "array",
+  "items": {
+    "$ref": "#/$defs/reviewPacket"
+  },
+  "$defs": {
+    "lens": {
+      "type": "string",
+      "enum": [
+        "correctness",
+        "architecture",
+        "maintainability",
+        "security",
+        "reliability",
+        "performance",
+        "data_integrity",
+        "tests",
+        "operability",
+        "config_deployment",
+        "observability"
+      ]
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["high", "medium", "low"]
+    },
+    "graphEdge": {
+      "type": "object",
+      "required": ["from", "to", "confidence"],
+      "properties": {
+        "from": { "type": "string" },
+        "to": { "type": "string" },
+        "kind": { "type": "string" },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "reason": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "quality": {
+      "type": "object",
+      "required": [
+        "cohesion_score",
+        "internal_edge_count",
+        "boundary_edge_count",
+        "unexplained_file_count"
+      ],
+      "properties": {
+        "cohesion_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "internal_edge_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "boundary_edge_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unexplained_file_count": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "reviewPacket": {
+      "type": "object",
+      "required": [
+        "packet_id",
+        "task_ids",
+        "unit_ids",
+        "pass_ids",
+        "lenses",
+        "file_paths",
+        "file_line_counts",
+        "total_lines",
+        "priority",
+        "quality",
+        "rationale",
+        "estimated_tokens"
+      ],
+      "properties": {
+        "packet_id": { "type": "string" },
+        "task_ids": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "unit_ids": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "pass_ids": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "lenses": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/lens" }
+        },
+        "file_paths": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "file_line_counts": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "total_lines": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "priority": { "$ref": "#/$defs/priority" },
+        "tags": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "entrypoints": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "key_edges": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/graphEdge" }
+        },
+        "boundary_files": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "quality": { "$ref": "#/$defs/quality" },
+        "rationale": { "type": "string" },
+        "estimated_tokens": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/skills/audit-code/SKILL.md

@@ -20,6 +20,9 @@ Normal usage should:
 Semantic review should be delegated to bounded subagents whenever the host can
 dispatch them. The conversation orchestrator owns dispatch and ingestion control;
 it should not perform broad review itself when subagents are available.
+Entering `/audit-code` is explicit user authorization to fan out those review
+subagents; do not require a separate delegation request before parallel
+dispatch.
 
 If the host cannot delegate to subagents, the conversation orchestrator may
 complete exactly one assigned review task, ingest it through the provided backend
@@ -52,9 +55,10 @@ current repository before advancing the audit:
 audit-code ensure --quiet
 ```
 
-That idempotent bootstrap writes repo-local host assets for Codex, Claude Desktop,
-OpenCode, VS Code, and Antigravity plus shared MCP setup guidance only when they
-are missing or stale.
+That idempotent bootstrap writes repo-local fallback/guidance assets for
+supported hosts plus shared MCP setup guidance only when they are missing or
+stale. Codex uses the global skill installed by npm rather than a repo-local
+skill bundle.
 
 Use the explicit installer for repair or forced refresh:
 

package/skills/audit-code/audit-code.prompt.md

@@ -28,6 +28,9 @@ and ingest results mechanically.
 - CRITICAL: Do not use your `Read` tool to read `entry.prompt_path` or JSON schemas into your own context window. The subagent will read them. Pass the path literally.
 - Prefer subagent dispatch for semantic review whenever the host exposes an
   Agent/subagent tool.
+- Treat the user's `/audit-code` request as explicit authorization to launch
+  review subagents in parallel. Do not ask for a separate delegation request
+  before using available Agent/subagent tools.
 - Do not use `browser_subagent` for semantic review of source code unless the
   task explicitly requires browser-based validation.
 - If the host cannot dispatch subagents, complete exactly one assigned review
@@ -83,7 +86,7 @@ If status is `"blocked"` for semantic review, continue to Step 2.
 
 ## Step 2 - Dispatch Review Work
 
-When the host supports subagents, prepare a dispatch plan:
+When the host supports subagents, prepare a dispatch plan by default:
 
 ```bash
 audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>

package/docs/agent-integrations.md

@@ -1,317 +0,0 @@
-# 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
-
-## Review ownership rule
-
-Semantic review should stay with the active conversation agent by default.
-
-That means:
-
-- use the current host conversation as the normal owner of review work
-- if the host agent can delegate to subagents in parallel, let the host runtime make that decision
-- do not treat `.audit-artifacts/session-config.json` as the normal way to choose a second LLM for review
-- treat backend provider adapters as compatibility bridges for fallback CLI usage only
-
-## Conversation-first setup
-
-The canonical prompt asset is:
-
-`skills/audit-code/audit-code.prompt.md`
-
-The preferred install path for users is:
-
-```bash
-npm install -g auditor-lambda
-```
-
-That makes `audit-code` available on `PATH` and seeds user-level command/skill
-assets for hosts we can safely update during package installation. Once the
-slash command is available, `/audit-code` self-bootstraps the current repository
-with:
-
-```bash
-audit-code ensure --quiet
-```
-
-`ensure` writes repo-local `/audit-code` surfaces and MCP-oriented support assets
-for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity only when they are
-missing or stale. It also writes `.audit-code/install/GETTING-STARTED.md` with
-dedicated quick-start sections for each host plus `.audit-code/install/manifest.json`
-and a shared repo-local MCP launcher.
-
-Use the explicit installer when you want to repair or force-refresh those
-repo-local assets:
-
-```bash
-audit-code install
-```
-
-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.
-
-### Codex
-
-The global npm install seeds `~/.codex/skills/audit-code/` so the command can be
-available before a repository is bootstrapped. The first `/audit-code` run then
-uses `audit-code ensure --quiet` to create or refresh repo-local Codex support.
-
-Use `audit-code install --host codex` only when you want to repair or force-refresh
-the Codex repo-local files from the target repository root.
-
-That writes a repo-local Codex skill bundle, updates `AGENTS.md` through a managed block when needed, and emits Codex-specific MCP setup guidance plus an automation recipe in `.audit-code/install/codex/`.
-The intended operator flow is still conversational first, with the generated skill and AGENTS guidance steering the active Codex session toward `/audit-code` and the MCP-backed workflow.
-
-The Codex automation recipe should still be treated as optional follow-through after the basic local flow is validated in the real app.
-
-### Claude Desktop
-
-Use `audit-code install --host claude-desktop` or the default `audit-code install` from the target repository root.
-
-This repository now treats Claude Desktop as an MCP-first host. The installer writes:
-
-- `.audit-code/install/claude-desktop/PROJECT-TEMPLATE.md`
-- `.audit-code/install/claude-desktop/remote-mcp-connector.json`
-- generated local bundle artifacts including `auditor-lambda.dxt` and `auditor-lambda.mcpb`
-
-The intended path is to install or reference the generated local MCP bundle, then use the shared prompt and project-template guidance to run `/audit-code` conversationally.
-Manual prompt import remains a fallback, not the primary documented path.
-
-### OpenCode
-
-OpenCode currently relies on repo-local command and MCP config files for the
-cleanest experience. A global `/audit-code` prompt can run `audit-code ensure --quiet`
-first; otherwise run `audit-code install` from the target repository root once.
-
-That writes `.opencode/commands/audit-code.md`, a repo-local OpenCode skill bundle, and `opencode.json` so `/audit-code` is available in the repository with no extra provider flags.
-The generated OpenCode assets also point OpenCode toward the shared auditor MCP server instead of rebuilding backend state ad hoc.
-
-### VS Code
-
-VS Code currently relies on workspace prompt and MCP config files for the
-cleanest experience. A global `/audit-code` prompt can run `audit-code ensure --quiet`
-first; otherwise 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.
-
-That writes `.github/prompts/audit-code.prompt.md`, `.github/copilot-instructions.md`, `.github/agents/auditor.agent.md`, and `.vscode/mcp.json`.
-The expected happy path is still to invoke `/audit-code` from chat, not to start from the backend CLI.
-
-### Antigravity
-
-Run `/audit-code` from a global prompt-capable host and let `audit-code ensure --quiet`
-create the repo-local guidance, or run `audit-code install` from the target
-repository root, then open `.audit-code/install/GETTING-STARTED.md`.
-
-There is still no documented native repo-local saved-workflow surface for Antigravity in this repository today, so the intended path is:
-
-1. use the generated planning-mode and MCP setup guidance
-2. invoke `/audit-code` conversationally inside Antigravity when the host surface allows it
-3. use the shared MCP tools and resources when structured state exchange is needed
-4. 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 Antigravity, or the same MCP-first bundle pattern as Claude Desktop, depending on what the host actually supports.
-
-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 behind the slash command.
-
-It:
-
-- defaults artifacts to `<repo-root>/.audit-artifacts`
-- persists audit continuity there
-- calls `run-to-completion` by default for deterministic work
-- 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 deterministic
-  work and exposed scoped semantic-review task artifacts for the slash-command
-  orchestrator.
-
-Current implementation note:
-
-- the backend fallback still supports explicit provider bridges such as `claude-code`, `opencode`, `subprocess-template`, and `vscode-task`
-- those bridges are compatibility modes, not the intended default review owner
-- the intended workflow is documented in [docs/workflow-refactor-brief.md](/C:/Code/auditor-lambda/docs/workflow-refactor-brief.md)
-
-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.
-Use it when the current host cannot keep review inside the active conversation, not as the first choice for semantic-review ownership.
-
-## Provider matrix
-
-### local-subprocess
-
-Use when you want the supervisor to stay entirely local.
-
-This requires no external agent CLI. Deterministic executors run in-process
-during normal wrapper runs, and the supervisor only stops once the remaining
-work is genuinely semantic review.
-
-When that review boundary is reached, `local-subprocess` stops in a terminal
-blocked handoff instead of pretending more automatic progress is available.
-The slash-command orchestrator should dispatch subagents from the handoff when
-available; otherwise it should review exactly one task, write results, run the
-provided worker command, and stop.
-
-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 current implementation can launch a fresh Claude Code print-mode session for each worker run.
-
-Treat this as a compatibility bridge only, not as the intended default review owner.
-
-### opencode
-
-Use when OpenCode is installed and authenticated on the machine.
-
-The current implementation can launch a fresh `opencode run ...` session for each worker run.
-
-Treat this as a compatibility bridge only, not as the intended default review owner.
-
-### 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.
-For provider-assisted review stages, that bridge should write `task.audit_results_path` and then execute `task.worker_command`.
-
-### 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 `/audit-code` in the active conversation as the primary path.
-
-Only use the repo-local `audit-code` wrapper with `provider: "claude-code"` in `.audit-artifacts/session-config.json` when you intentionally want backend fallback bridging into Claude Code.
-
-### OpenCode
-
-Use `/audit-code` in the active conversation as the primary path.
-
-Only use the repo-local `audit-code` wrapper with `provider: "opencode"` when you intentionally want backend fallback bridging into OpenCode.
-
-### VS Code
-
-Use `/audit-code` from chat and let the prompt run `audit-code ensure --quiet`.
-Run `audit-code install` manually only when VS Code has not yet discovered the
-workspace prompt/MCP files or you want to force-refresh them.
-
-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 (note: do NOT use `browser_subagent` for semantic review of code unless explicitly required by the task)
-- let `/audit-code` run `audit-code ensure --quiet`, or run `audit-code install` manually 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.
-
-## Remaining steps
-
-The current implementation shipped the shared installer and MCP substrate. The remaining work is operational validation and fit-and-finish, not a fresh redesign.
-
-Highest-value follow-through:
-
-1. validate the generated Codex, Claude Desktop, OpenCode, VS Code, and Antigravity assets inside the real products they target
-2. tighten generated quick-start guidance anywhere those host smoke tests expose ambiguity
-3. document exactly how Antigravity artifacts should map into `import_results` and `import_runtime_updates`
-4. keep host claims conservative until those end-to-end product checks are complete
-
-## Model-selection rule
-
-The product direction remains skill-first:
-
-- in conversation, keep orchestration in the active model and delegate semantic
-  review to bounded subagents when the host supports them
-- 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. install once with `npm install -g auditor-lambda`, then let `/audit-code` run `audit-code ensure --quiet` in each repository
-3. use `audit-code` as the repo-local backend fallback
-4. prefer `local-subprocess` unless you explicitly want a backend provider bridge
-5. use `subprocess-template` only when integrating a non-native editor or launcher surface
-
-If you intentionally want the backend fallback to bridge semantic review into
-another process, set the matching provider in
-`.audit-artifacts/session-config.json` or re-run with an explicit `--provider`
-flag after configuring the matching provider section.

package/docs/agent-roles.md

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

@@ -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.