auditor-lambda 0.3.12 → 0.3.14

package/docs/supervisor.md

@@ -1,100 +0,0 @@
-# supervisor and provider adapters
-
-This document describes backend infrastructure.
-
-The primary product contract is `/audit-code` in conversation.
-
-Everything here is fallback and implementation detail guidance for the repo-local backend surface.
-
-In the intended workflow, the conversation agent owns orchestration and
-ingestion control, but bounded subagents own semantic review whenever the host
-can dispatch them. If subagents are unavailable, the conversation agent reviews
-one assigned task and stops so `/audit-code` can be rerun from fresh context.
-
-Provider adapters are compatibility bridges for backend fallback mode, not the
-default review owner.
-
-## Repo-local backend surface
-
-From the target repository root:
-
-```bash
-audit-code
-```
-
-Debug one-step mode:
-
-```bash
-audit-code --single-step
-```
-
-Explicit root override:
-
-```bash
-audit-code --root /path/to/repo
-```
-
-## Provider mode summary
-
-If provider is omitted entirely, the backend defaults to the safest mode:
-
-```json
-{
-  "provider": "local-subprocess"
-}
-```
-
-If you want best-effort routing across available or configured backends, opt into:
-
-```json
-{
-  "provider": "auto",
-  "ui_mode": "visible"
-}
-```
-
-Explicit backend selection remains available:
-
-```bash
-audit-code --provider local-subprocess
-audit-code --provider claude-code
-audit-code --provider opencode
-audit-code --provider subprocess-template
-audit-code --provider vscode-task
-```
-
-Those `--provider` invocations are an explicit bridge handoff point.
-Without an explicit `--provider` flag or a non-local provider in
-`.audit-artifacts/session-config.json`, the backend stops at the
-semantic-review boundary and exposes scoped task artifacts for the
-slash-command orchestrator.
-
-## Auto resolution rule
-
-When `provider` is set to `auto`, the backend resolves in this order:
-
-1. `vscode-task` when running under VS Code and a `vscode_task.command_template` is configured
-2. `subprocess-template` when a generic template bridge is configured
-3. `claude-code` when Claude Code is available and preferred by config or when it is the only detected external CLI
-4. `opencode` when OpenCode is available and preferred by config or when it is the only detected external CLI
-5. `local-subprocess` otherwise
-
-## Session config
-
-Optional backend config file:
-
-`.audit-artifacts/session-config.json`
-
-See:
-
-- `docs/session-config.md`
-- `docs/agent-integrations.md`
-- `docs/model-selection.md`
-- `docs/windows-setup.md`
-
-## Note
-
-Provider adapters are backend integrations, not the primary product concept.
-Session config defines bridge settings. An explicit `provider: "auto"` or
-`--provider` bridge selection is what opts the backend into provider-mediated
-review dispatch.

package/docs/usage.md

@@ -1,215 +0,0 @@
-# Backend CLI Usage
-
-This document covers the backend fallback CLI and low-level development entrypoints.
-
-The primary product remains `/audit-code` in conversation.
-
-## Stable installed helpers
-
-Install the package once for the current user:
-
-```bash
-npm install -g auditor-lambda
-```
-
-Then invoke `/audit-code` in a supported host. The prompt runs this idempotent
-bootstrap helper before advancing the audit:
-
-```bash
-audit-code ensure --quiet
-```
-
-Run the same helper manually when you want to create or refresh the repo-local
-host assets without starting an audit:
-
-```bash
-audit-code ensure
-```
-
-Explicitly rewrite the supported repo-local `/audit-code` surfaces for the
-current repository:
-
-```bash
-audit-code install
-```
-
-Locate the canonical prompt asset shipped with the package:
-
-```bash
-audit-code prompt-path
-```
-
-Run the repo-local backend fallback from the target repository root:
-
-```bash
-audit-code
-```
-
-Validate the current fallback artifact bundle:
-
-```bash
-audit-code validate
-```
-
-This reports artifact issues, `session-config.json` issues, and explicit provider readiness issues in one machine-readable response.
-
-Pass additional evidence back into the same fallback wrapper when needed:
-
-```bash
-audit-code --results /path/to/audit_results.json
-audit-code --batch-results /path/to/audit-results-dir
-audit-code --updates /path/to/runtime_validation_update.json
-audit-code --external-analyzer-results /path/to/external_analyzer_results.json
-```
-
-Inspect the resolved scope of a task id without reverse-engineering `coverage_matrix.json` manually:
-
-```bash
-audit-code explain-task src-api-auth:security
-```
-
-Each wrapper run also refreshes:
-
-- `.audit-artifacts/operator-handoff.json`
-- `.audit-artifacts/operator-handoff.md`
-
-Use those companion files when you want a stable summary of pending obligations, suggested import paths, and session-config guidance for interactive-provider continuation.
-
-## Low-level development entrypoints
-
-These `dist/index.js` commands are backend and development interfaces.
-
-They are useful for debugging, smoke coverage, and harness-level integration work.
-
-## Sample run
-
-```bash
-npm run build
-node dist/index.js sample-run --artifacts-dir .artifacts
-```
-
-## Advance the backend state machine
-
-```bash
-node dist/index.js advance-audit --root /path/to/repo --artifacts-dir .artifacts
-```
-
-Optional inputs for the same bounded step:
-
-```bash
-node dist/index.js advance-audit --root /path/to/repo --artifacts-dir .artifacts --results /path/to/audit_results.json
-node dist/index.js advance-audit --root /path/to/repo --artifacts-dir .artifacts --batch-results /path/to/audit-results-dir
-node dist/index.js advance-audit --root /path/to/repo --artifacts-dir .artifacts --updates /path/to/runtime_validation_update.json
-node dist/index.js advance-audit --root /path/to/repo --artifacts-dir .artifacts --external-analyzer-results /path/to/external_analyzer_results.json
-```
-
-## Import normalized external analyzer results
-
-```bash
-node dist/index.js import-external-analyzer --root /path/to/repo --artifacts-dir .artifacts --external-analyzer-results /path/to/external_analyzer_results.json
-```
-
-This writes:
-
-- `external_analyzer_results.json`
-- refreshed `audit_state.json`
-
-## Real repository intake
-
-```bash
-node dist/index.js intake --root /path/to/repo --artifacts-dir .artifacts
-```
-
-This writes:
-
-- `repo_manifest.json`
-- `file_disposition.json`
-
-## Planning helper
-
-```bash
-node dist/index.js plan --root /path/to/repo --artifacts-dir .artifacts
-```
-
-This command is a backend helper, not a stable end-user planning pipeline.
-
-It invokes the current bounded advance logic and reports the next backend step.
-
-## Ingest audit results
-
-```bash
-node dist/index.js ingest-results --artifacts-dir .artifacts --results /path/to/audit_results.json
-node dist/index.js ingest-results --artifacts-dir .artifacts --batch-results /path/to/audit-results-dir
-```
-
-This updates:
-
-- `coverage_matrix.json`
-- `flow_coverage.json`
-- `runtime_validation_tasks.json`
-- `runtime_validation_report.json`
-- `audit_results.jsonl`
-- `audit_tasks.json`
-- `requeue_tasks.json`
-- `merged_findings.json`
-- `root_cause_clusters.json`
-- `synthesis_report.json`
-
-The batch form processes every `*.json` file in the target directory in lexical order.
-
-## Explain a task id
-
-```bash
-node dist/index.js explain-task src-api-auth:security --artifacts-dir .artifacts
-```
-
-This prints the resolved task payload, matching `coverage_matrix.json` entries, pending coverage by file, and any already-ingested matching findings.
-
-## Update runtime validation report with real evidence
-
-Prepare a JSON file shaped like `examples/runtime_validation_update.example.json`, then run:
-
-```bash
-node dist/index.js update-runtime-validation --artifacts-dir .artifacts --updates /path/to/runtime_validation_update.json
-```
-
-This merges the updates into:
-
-- `runtime_validation_report.json`
-- `synthesis_report.json`
-
-## Validate artifacts
-
-```bash
-node dist/index.js validate --artifacts-dir .artifacts
-```
-
-This checks artifact shape, cross-artifact consistency, backend session-config validity, and explicit provider readiness.
-
-It is intended for backend operators and automation, not for the normal conversation route.
-
-## Requeue helper
-
-```bash
-node dist/index.js requeue --artifacts-dir .artifacts
-```
-
-This command currently reports the current requeue task count from the existing artifact bundle.
-
-Treat it as an inspection helper rather than a stable artifact-building command.
-
-## Synthesize findings
-
-```bash
-node dist/index.js synthesize --artifacts-dir .artifacts --results /path/to/audit_results.json
-```
-
-This writes:
-
-- `merged_findings.json`
-- `root_cause_clusters.json`
-- `synthesis_report.json`
-
-## Ignore file
-
-Create a `.auditorignore` file at repository root to add extra ignored paths, one per line.

package/docs/windows-setup.md

@@ -1,146 +0,0 @@
-# Windows setup
-
-This document covers Windows setup for the backend fallback `audit-code` wrapper.
-
-The canonical product route is still `/audit-code` in conversation.
-
-## Simplest path
-
-From the target repository root in PowerShell:
-
-```powershell
-audit-code
-```
-
-This is the lowest-friction path.
-
-Use it with the default backend:
-
-```json
-{
-  "provider": "local-subprocess",
-  "ui_mode": "visible"
-}
-```
-
-## Claude Code on Windows
-
-If `claude` is on `PATH`, use:
-
-```json
-{
-  "provider": "claude-code",
-  "ui_mode": "visible",
-  "claude_code": {
-    "command": "claude",
-    "extra_args": []
-  }
-}
-```
-
-If you want to force a model:
-
-```json
-{
-  "provider": "claude-code",
-  "ui_mode": "visible",
-  "claude_code": {
-    "command": "claude",
-    "extra_args": ["--model", "sonnet"]
-  }
-}
-```
-
-## OpenCode on Windows
-
-If `opencode` is on `PATH`, use:
-
-```json
-{
-  "provider": "opencode",
-  "ui_mode": "visible",
-  "opencode": {
-    "command": "opencode",
-    "extra_args": []
-  }
-}
-```
-
-If you want to force a provider/model pair:
-
-```json
-{
-  "provider": "opencode",
-  "ui_mode": "visible",
-  "opencode": {
-    "command": "opencode",
-    "extra_args": ["--model", "anthropic/claude-sonnet-4.5"]
-  }
-}
-```
-
-## Generic PowerShell bridge
-
-When you need a provider-neutral launcher from Windows, use a PowerShell template bridge.
-
-Example:
-
-```json
-{
-  "provider": "subprocess-template",
-  "ui_mode": "visible",
-  "subprocess_template": {
-    "command_template": [
-      "pwsh",
-      "-NoProfile",
-      "-ExecutionPolicy",
-      "Bypass",
-      "-Command",
-      "& { {workerCommandShell} }"
-    ]
-  }
-}
-```
-
-If `pwsh` is not installed, replace it with `powershell`.
-
-## VS Code on Windows
-
-The simplest VS Code path is still the integrated terminal.
-
-Open the target repository in VS Code and run:
-
-```powershell
-audit-code
-```
-
-Use a `vscode-task` template only if you specifically need a task-oriented launcher boundary.
-
-Example:
-
-```json
-{
-  "provider": "vscode-task",
-  "ui_mode": "visible",
-  "vscode_task": {
-    "command_template": [
-      "pwsh",
-      "-NoProfile",
-      "-ExecutionPolicy",
-      "Bypass",
-      "-Command",
-      "& { {workerCommandShell} }"
-    ]
-  }
-}
-```
-
-## Antigravity on Windows
-
-There is no dedicated Antigravity provider adapter in this repository today.
-
-The recommended practical path is:
-
-- run `audit-code` from an Antigravity terminal
-- use `local-subprocess` first
-- move to `subprocess-template` only if a launcher bridge is actually needed

package/docs/workflow-refactor-brief.md

@@ -1,124 +0,0 @@
-# Workflow Refactor Status
-
-This document records the packet-dispatch refactor that replaced the older
-one-agent-per-small-task review plan.
-
-## Goal
-
-Reduce token and quota usage for `/audit-code` while preserving deterministic
-validation, ingestion, coverage tracking, and report synthesis.
-
-The implemented design is a compatibility-preserving packet layer:
-
-- keep `AuditTask` as the backend planning and coverage identity
-- keep `AuditResult[]` as the ingestion contract
-- group related task records into worker-facing review packets
-- make each worker read a coherent file set once and review multiple lenses in
-  one pass
-- submit packet results through the backend so only assigned result files are
-  written
-
-## Current Product Model
-
-The canonical workflow is still conversation-first:
-
-1. The active conversation agent owns orchestration and ingestion control.
-2. Bounded subagents own semantic packet review when the host supports them.
-3. If subagents are unavailable, the conversation agent completes one assigned
-   fallback review task and stops so `/audit-code` can be rerun from fresh
-   context.
-4. Backend provider adapters remain explicit compatibility bridges, not the
-   default semantic-review owner.
-
-Session config remains backend fallback configuration. It should not be treated
-as the normal way to redirect semantic review into a second external LLM.
-
-## Implemented Changes
-
-The refactor now includes:
-
-- deterministic `review_packets.json` derived from current `AuditTask` records
-- `audit_plan_metrics.json` with packet counts, repeated reference estimates,
-  largest packet details, and estimated agent reduction
-- packet-first pending-task ordering for provider-assisted batches
-- tiny homogeneous test-file batching before dispatch
-- graph-edge expansion from import, call, and reference edges
-- packet prompts that assign multiple task results to one worker
-- backend-owned packet submission that validates before writing result files
-- isolated large-file packet mode with mechanical anchors for targeted review
-- validation and merge checks for missing, duplicate, unknown, malformed, or
-  out-of-scope task results, including swapped result files
-- compact `prepare-dispatch` and `merge-and-ingest` JSON envelopes
-- terse worker completion convention:
-  `valid: <packet_id>, findings=<n>`
-- selective deepening for high-severity, low-confidence, conflicting,
-  high-risk clean, and runtime-disagreement cases
-- refreshed packet metrics whenever selective deepening adds follow-up tasks
-
-## Dispatch Contract
-
-`prepare-dispatch` writes a small `dispatch-plan.json`. Each entry points to a
-packet prompt under the run-scoped `task-results/` directory.
-
-The conversation orchestrator should:
-
-- read only `dispatch-plan.json`
-- launch one subagent per packet entry
-- tell the subagent to read and follow `entry.prompt_path`
-- wait for terse success replies
-- run `merge-and-ingest`
-
-The parent should not read source files, prompt bodies, result payloads, or
-large task manifests during the normal packet route.
-
-## Artifacts
-
-Packet mode adds or updates these artifacts:
-
-- `review_packets.json`
-- `audit_plan_metrics.json`
-- `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`
-- `<artifacts_dir>/runs/<run_id>/dispatch-result-map.json`
-- `<artifacts_dir>/runs/<run_id>/task-results/*.prompt.md`
-- `<artifacts_dir>/runs/<run_id>/task-results/*.anchors.json`, only for
-  isolated large-file packets
-- `<artifacts_dir>/runs/<run_id>/task-results/*.json`
-- `<artifacts_dir>/runs/<run_id>/dispatch-warnings.json`, only when needed
-
-The existing coverage, runtime validation, requeue, and synthesis artifacts
-remain backend-owned.
-
-## Verification
-
-Current in-repo verification:
-
-- `npm test` passes with 148 tests.
-
-Relevant test coverage:
-
-- packet construction and metrics
-- packet ordering
-- graph-connected packet merging
-- tiny test-file batching
-- packet prompt generation
-- packet submission and merge compatibility with the legacy result array
-- missing-result blocking
-- swapped-result blocking
-- collision-proof assigned result paths
-- isolated large-file anchor generation
-- path-heuristic regressions
-- graph extraction from source contents
-- selective deepening triggers and packet refresh
-
-## Remaining Follow-Up
-
-The main remaining work is operational, not structural:
-
-- run `/audit-code` against at least one nontrivial external repository and
-  compare packet counts, warning counts, worker completion summaries, and
-  observed token/quota behavior against the legacy baseline
-- keep host-specific smoke testing current for Codex, Claude Desktop, OpenCode,
-  VS Code, and Antigravity guidance
-
-For the detailed packet dispatch reference, see
-`docs/dispatch-implementation-plan.md`.