auditor-lambda 0.1.0

package/docs/github-copilot.md

@@ -0,0 +1,50 @@
+# GitHub Copilot setup
+
+This is the first shipped native host integration for the `/audit-code` conversation surface.
+
+It is now a narrower host-specific path. The preferred setup flow is `audit-code install`, which bootstraps all supported repo-local host surfaces in one step.
+
+## Recommended path
+
+From the target repository root:
+
+```bash
+audit-code install
+```
+
+That writes the canonical `/audit-code` prompt and compatibility instructions into:
+
+```text
+.github/prompts/audit-code.prompt.md
+.github/copilot-instructions.md
+```
+
+After that, open GitHub Copilot Chat in the same repository and invoke `/audit-code`.
+
+If you only want the narrower VS Code / Copilot install surface, use:
+
+```bash
+audit-code install --host vscode
+```
+
+## Behavior
+
+- the command copies the canonical prompt payload from `skills/audit-code/audit-code.prompt.md`
+- the generated prompt file explicitly sets `agent: agent` so Copilot Chat runs `/audit-code` with tool-capable agent mode
+- the installer upserts its managed compatibility block into `.github/copilot-instructions.md` instead of clobbering unrelated instructions
+- it prints machine-readable JSON describing the installed targets
+
+## Explicit root override
+
+If you are running from outside the target repository:
+
+```bash
+audit-code install --root /path/to/repo
+```
+
+## Why this exists
+
+The goal is to reduce conversation setup friction without repositioning the backend CLI as the primary product surface.
+
+GitHub Copilot now shares the same repo-native bootstrap path as the other currently automated hosts.
+The older `audit-code install-host --host copilot` alias still exists for compatibility, but it is no longer the recommended setup flow.

package/docs/model-selection.md

@@ -0,0 +1,86 @@
+# model selection
+
+This repository has two distinct model-selection layers.
+
+## 1. Skill-first product rule
+
+The canonical product surface is `/audit-code` in conversation.
+
+For that surface, the default model rule is:
+
+- use the active conversation model by default
+- avoid forcing the user to supply a model in normal usage
+
+That is the intended product contract.
+
+## 2. Backend provider rule
+
+When the local backend delegates bounded worker runs into an external provider, model selection becomes provider-specific.
+
+That means the supervisor should not invent a global model abstraction unless it can be implemented consistently across adapters.
+
+Today the practical rule is:
+
+- no provider-specific model override by default
+- let each provider use its own default model unless explicitly configured otherwise
+- when a model is required, pass it through the provider's own native CLI arguments via `extra_args`
+
+## Current provider behavior
+
+### `local-subprocess`
+
+No external LLM provider is selected here.
+
+The supervisor simply launches the bounded local worker command.
+
+### `claude-code`
+
+The built-in Claude Code adapter supports model overrides through `claude_code.extra_args`.
+
+Example:
+
+```json
+{
+  "provider": "claude-code",
+  "ui_mode": "visible",
+  "claude_code": {
+    "command": "claude",
+    "extra_args": ["--model", "sonnet"]
+  }
+}
+```
+
+Use this only when you want to force a specific Claude Code model instead of relying on the user's normal Claude Code default.
+
+### `opencode`
+
+The built-in OpenCode adapter supports model overrides through `opencode.extra_args`.
+
+Example:
+
+```json
+{
+  "provider": "opencode",
+  "ui_mode": "visible",
+  "opencode": {
+    "command": "opencode",
+    "extra_args": ["--model", "anthropic/claude-sonnet-4.5"]
+  }
+}
+```
+
+Use this only when you want to force a specific OpenCode provider/model pair instead of relying on the user's normal OpenCode default.
+
+### `subprocess-template` and `vscode-task`
+
+These adapters do not define model semantics themselves.
+
+If you need model selection here, include it in the external launcher command template or in the external tool being invoked.
+
+## Recommendation
+
+For the cleanest product behavior:
+
+1. in conversation, let `/audit-code` inherit the active conversation model
+2. for repo-local backend usage, do not force model selection unless the operator has a concrete reason
+3. when needed, set model selection in the provider-native config rather than inventing another repo-level abstraction

package/docs/next-steps.md

@@ -0,0 +1,161 @@
+# Next Implementation Steps
+
+This document tracks the next meaningful implementation work after the current skill-first productionization pass.
+
+As of April 17, 2026, this repository is not yet ready for a public production launch.
+
+See:
+
+- `docs/production-readiness.md`
+
+## Current state
+
+The repository now supports:
+
+- `/audit-code` as the documented canonical product route
+- packaged and repository-local access to `skills/audit-code/audit-code.prompt.md`
+- `audit-code prompt-path` as a stable prompt lookup helper
+- `audit-code install` as a bootstrap installer for the currently automated repo-local host surfaces
+- explicit failures for malformed backend config and corrupted artifact JSON
+- `audit-code validate` as a machine-readable backend operator check
+- an explicit in-repo release gate via `npm run verify:release`
+- structured operator handoff output plus `.audit-artifacts/operator-handoff.{json,md}` for blocked fallback runs
+
+That means the current release is suitable for a controlled alpha or beta skill-first workflow, but it is not yet the final public production end-state.
+
+## Near-term priorities
+
+### 1. Reduce conversation setup friction
+
+The biggest remaining UX gap is that some hosts still lack a verified repo-local install surface.
+
+Near-term work should focus on:
+
+- host-specific setup guides that reduce copy-paste ambiguity
+- preserving `audit-code install` as the default no-guess bootstrap path
+- extending bootstrap coverage to hosts that still need manual prompt import
+- a shorter path from package install to a working `/audit-code` conversation flow
+
+Current emphasis should follow actual operator usage:
+
+- keep VS Code and OpenCode as the primary polished happy path
+- treat Claude Desktop and Antigravity as the highest-priority manual-import surfaces
+- avoid spending near-term effort on lower-priority editor integrations unless they materially improve the shared prompt-import path
+
+### 2. Make the conversation route more native
+
+The product goal is still conversational first, not fallback-CLI first.
+
+Near-term work should focus on:
+
+- first-class integrations for the most important editor or agent hosts
+- removing host-specific manual prompt wiring where practical
+- keeping the active conversation model and attached repo context as the default operating mode
+
+### 3. Improve continuation through assisted review
+
+The repo-local backend fallback still intentionally stops once only manual or provider-assisted review remains.
+
+Near-term work should focus on:
+
+- smoother continuation when an interactive provider is configured
+- clearer evidence handoff for imported results and runtime updates
+- less operator guesswork when the backend reaches a blocked terminal handoff
+
+### 4. Harden publish and release operations
+
+The packaged install story is in place, but release operations still need finishing work.
+
+Near-term work should focus on:
+
+- npm package-name availability and ownership
+- final publication automation and secret management
+- keeping linked-install and packaged-install smoke checks as release gates
+
+## Frictionless-ready checklist
+
+The repository should not be described as frictionless and production-ready until this checklist is substantially true:
+
+### VS Code, OpenCode, and Claude Code
+
+- `audit-code install` remains the default bootstrap path
+- the generated repo-local surfaces are obvious in installer output and in `.audit-code/install/GETTING-STARTED.md`
+- a new user can invoke `/audit-code` without guessing where prompts or commands were written
+- smoke coverage continues to verify the exact repo-local files these hosts consume
+
+### Claude Desktop and Antigravity
+
+- the installed prompt-import path is explicit, repo-local, and easy to discover
+- `.audit-code/install/GETTING-STARTED.md` gives host-specific steps instead of generic manual-import advice
+- docs avoid implying native repo-local slash-command support that is not actually shipped
+- the backend fallback remains a clearly secondary path instead of the default recommendation
+
+### Assisted review continuation
+
+- when an interactive provider is configured, blocked audits continue with less manual result import
+- operator handoff artifacts remain explicit and inspectable even when continuation is smoother
+
+### Release operations
+
+- `npm run verify:release` remains green and authoritative
+- the real publish path is proven with npm ownership, `NPM_TOKEN`, and a real dry-run or pre-release publish
+
+## Probable next steps
+
+These are the most likely next implementation steps based on the current codebase state, but they should still be treated as provisional rather than guaranteed:
+
+### 1. Ship a real bootstrap installer instead of making users pick a host first
+
+Status:
+
+- completed for the currently automated repo-local hosts via `audit-code install`
+
+Practical success bar now met:
+
+- a new user can run one install command and get repo-local `/audit-code` surfaces for VS Code / Copilot, OpenCode, and Claude Code without guessing where the prompt belongs
+
+Follow-on shape:
+
+- keep the shared bootstrap path well-supported instead of growing one-off host installers
+- document the exact install and verification path for hosts that still need extra handling
+- only claim native support for a host once its install surface is equally concrete and testable
+
+### 2. Continue blocked reviews through a configured interactive provider
+
+Most likely shape:
+
+- use the existing provider configuration surface in `.audit-artifacts/session-config.json`
+- make the blocked handoff less manual when `claude-code`, `opencode`, or another bridge is intentionally configured
+- preserve explicit artifact imports and operator visibility instead of hiding state transitions
+
+Practical success bar:
+
+- a blocked audit can continue through the configured provider with fewer manual result-import and handoff steps
+
+### 3. Prove the release path outside the repository
+
+Most likely shape:
+
+- confirm npm package-name ownership and `NPM_TOKEN` availability
+- run a real pre-release or dry-run publish
+- keep `npm run verify:release` as the minimum in-repo gate before publish
+
+Practical success bar:
+
+- the release workflow is demonstrated end to end instead of only being inferred from configuration
+
+### 4. Expand host-specific setup guidance after the first integration lands
+
+Most likely shape:
+
+- keep the generated repo-local guide aligned with the real bootstrap surfaces for VS Code, OpenCode, and Claude Code
+- keep Claude Desktop and Antigravity guidance explicit about prompt import and terminal fallback rather than pretending native repo-local slash-command support
+- avoid broad host promises that the codebase does not yet verify
+
+## Non-goals for the next phase
+
+These should not become the primary focus of the next implementation pass:
+
+- repositioning the CLI as a peer product surface
+- expanding low-level backend helpers into a CLI-first user experience
+- making backend implementation details outrank the conversation contract in docs or product decisions

package/docs/packaging.md

@@ -0,0 +1,88 @@
+# packaged audit-code validation
+
+This repository validates the packaged installation story for both:
+
+1. the canonical conversation prompt asset
+2. the backend fallback `audit-code` entrypoint
+
+It does so in two installation modes:
+
+1. linked local command via `npm link`
+2. clean-room packaged install via `npm pack` followed by `npm install <tarball>`
+
+## Why this exists
+
+The primary product surface is `/audit-code` in conversation.
+
+That means the package needs to ship:
+
+- the canonical prompt asset at `skills/audit-code/audit-code.prompt.md`
+- the backend fallback wrapper exposed as `audit-code`
+
+A linked-command smoke test proves the installed wrapper and prompt lookup work from the working tree.
+A packaged-install smoke test proves the same assets still work when consumed from the packed artifact that a downstream installer would receive.
+
+## Packaged smoke command
+
+From the repository root:
+
+```bash
+npm install
+npm run verify:release
+```
+
+That script:
+
+- creates a tarball with `npm pack`
+- asserts the packed tarball still includes the required shipped assets and runtime entrypoints
+- installs it into a fresh temporary directory
+- verifies the packaged prompt asset is present and discoverable
+- verifies `audit-code install` can write the bootstrap host surfaces from the packaged install
+- invokes the installed `audit-code` binary from `node_modules/.bin`
+- validates emitted JSON against `schemas/audit-code-v1alpha1.schema.json`
+- exercises the same evidence-import and completion flow used by the linked-command smoke test
+
+## CI
+
+The packaged-install path is covered by:
+
+```text
+.github/workflows/packaged-entrypoint.yml
+```
+
+The release publish gate also runs both installed-entrypoint smoke paths before `npm publish`:
+
+```text
+.github/workflows/publish-package.yml
+```
+
+## Publish pipeline state
+
+The repository now includes packaging metadata and lifecycle hooks intended for registry publication:
+
+- `package.json` is no longer marked private
+- package contents are curated with a `files` allowlist that includes the canonical prompt asset
+- `prepack` and `prepare` build the runtime artifact
+- `verify:release` codifies the minimum in-repo release gate
+- `prepublishOnly` now runs that full release gate, including both linked-install and packaged-install smoke validation
+- packaged smoke now verifies the tarball includes `audit-code-wrapper-lib.mjs`, the prompt asset, the response schema, and `dist/` entrypoints before install-time smoke runs
+- the GitHub publish workflow uses the same release gate before `npm publish`
+
+## Remaining external dependency
+
+Actual publication still depends on confirmed npm package-name availability and ownership, plus a configured `NPM_TOKEN` secret for automated publishing.
+
+## Next packaging steps
+
+The next implementation phase should focus on:
+
+- completing npm publication prerequisites
+- preserving the packaged prompt asset and `audit-code prompt-path` as stable release guarantees
+- preserving `audit-code install` as a packaged-install compatibility guarantee
+- keeping linked-install and packaged-install smoke coverage in the publish gate
+- keeping `docs/production-launch-bar.md` aligned with the real release gate
+
+Related roadmap notes:
+
+- `docs/production-readiness.md`
+- `docs/next-steps.md`

package/docs/pipeline.md

@@ -0,0 +1,152 @@
+# Audit pipeline
+
+## Phase 0: intake
+
+Automated:
+
+- enumerate files
+- detect languages and frameworks
+- identify exclusions
+- hash files
+- collect git metadata
+
+Outputs:
+
+- `repo_manifest.json`
+- `file_inventory.json`
+- `stack_profile.json`
+
+## Phase 1: structural extraction
+
+Automated:
+
+- detect services, packages, apps
+- detect routes, jobs, commands, workflows
+- bucket files
+- extract graphs
+- detect data-layer artifacts
+
+Outputs:
+
+- `unit_manifest.json`
+- `surface_manifest.json`
+- `bucket_assignments.json`
+- `graph_bundle.json`
+
+LLM role:
+
+- resolve ambiguous units and suspicious classifications
+
+## Phase 2: mechanical analysis
+
+Automated:
+
+- lint
+- typecheck
+- tests
+- coverage
+- secrets
+- dependencies
+- static security
+- complexity and duplication
+
+Outputs:
+
+- `mechanical_results.json`
+- `hotspot_report.json`
+
+LLM role:
+
+- distinguish signal from noise
+- identify what deserves deeper review
+
+## Phase 3: risk scoring
+
+Automated inputs:
+
+- exposure
+- privilege indicators
+- persistent writes
+- secrets access
+- concurrency signals
+- churn
+- coverage weakness
+
+Outputs:
+
+- `risk_register.json`
+
+LLM role:
+
+- adjust for semantic criticality
+
+## Phase 4: blind-spot mapping
+
+LLM task:
+
+- use manifests, graphs, and bounded source excerpts to identify what tools are likely missing
+
+Outputs:
+
+- `blind_spot_register.json`
+- `runtime_validation_targets.json`
+
+## Phase 5: unit audits
+
+LLM task:
+
+- audit each unit under required lenses
+
+Outputs:
+
+- `audit_results/<unit>/<lens>.json`
+
+## Phase 6: cross-cutting audits
+
+LLM task:
+
+- audit repo-wide concerns such as auth, retries, migrations, config validation, observability, and secrets flow
+
+Outputs:
+
+- `cross_cutting/<theme>.json`
+
+## Phase 7: dynamic validation
+
+Automated + LLM:
+
+- run targeted checks for suspicious cases
+- interpret repro results
+
+Outputs:
+
+- `runtime_validation_report.json`
+
+## Phase 8: coverage verification
+
+Automated:
+
+- verify every file is classified
+- verify every file is audited or explicitly excluded
+- verify reviewed line ranges cover the intended source
+- verify multi-pass overlap for critical units
+
+Outputs:
+
+- `coverage_matrix.json`
+- `line_coverage_map.json`
+- `uncovered_items.json`
+
+## Phase 9: synthesis
+
+LLM task:
+
+- deduplicate findings
+- cluster by root cause
+- prioritize remediation
+
+Outputs:
+
+- `findings.json`
+- `root_cause_clusters.json`
+- `remediation_plan.md`

package/docs/product-direction.md

@@ -0,0 +1,111 @@
+# Product direction
+
+## Source of truth
+
+The primary product is an in-conversation ChatGPT skill:
+
+`/audit-code`
+
+The intended user experience is:
+
+- invoke `/audit-code` in a ChatGPT project conversation
+- use the current conversation model as the primary model
+- use project files and attached repository context as the primary operating context
+- require no manual filesystem paths, provider flags, or model-selection arguments from the user
+- advance the audit automatically until it completes or no further automatic progress is possible, using bounded internal steps only as an implementation detail
+
+## Canonical install asset
+
+The canonical integration asset is:
+
+`skills/audit-code/audit-code.prompt.md`
+
+That asset should be available from both:
+
+- repository checkouts
+- packaged installs
+
+The stable packaged lookup helper is:
+
+```bash
+audit-code prompt-path
+```
+
+That command exists to locate the conversation prompt asset, not to reposition the CLI as the primary user surface.
+
+The preferred bootstrap installer is:
+
+```bash
+audit-code install
+```
+
+That command writes the repo-local `/audit-code` surfaces we can automate today instead of making the user choose one host up front.
+
+## What the CLI is
+
+The CLI in this repository is backend infrastructure, a local development harness, and a repo-local fallback operator surface.
+
+It is not the preferred end-user mental model.
+
+## Repo-local fallback
+
+Repo-local backend wrapper:
+
+```bash
+audit-code
+```
+
+from the target repository root.
+
+Fallback explicit form:
+
+```bash
+audit-code --root /path/to/repo
+```
+
+Debug one-step mode:
+
+```bash
+audit-code --single-step
+```
+
+## Backend mode rule
+
+For repo-local backend usage:
+
+- omitted provider should remain the stable safe default: `local-subprocess`
+- `local-subprocess` should stop cleanly once only manual or provider-assisted review remains
+- `provider: "auto"` is the explicit opt-in mode for best-effort routing across configured or detected backends
+- explicit provider names should remain available for operators who want a specific backend
+
+## Default context & model rules
+
+1. By default, the current ChatGPT project conversation and its files should be treated as the primary context.
+2. The user should not need to supply `--root`, provider names, or backend-specific settings in normal usage.
+3. For backend CLI delegation, let the chosen provider own its own model-selection behavior unless explicitly configured.
+
+## Development rule
+
+Future development should optimize for the native skill UX first:
+
+- `/audit-code` in conversation is the canonical product entrypoint
+- packaged installs should help users reach the prompt asset for that conversation route
+- the CLI and supervisor are implementation details and fallback harnesses
+- provider adapters are backend internals, not the primary product concept
+- docs, tests, and examples should present the skill-first flow before any CLI flow
+
+If documentation or implementation details conflict, prefer the skill-first contract above over the CLI-first backend shape.
+
+## Near-term implementation priorities
+
+The next implementation phase should focus on:
+
+- reducing prompt-import friction for the conversation setup path
+- keeping the bootstrap path stable across supported hosts
+- extending automation to hosts that still lack a verified repo-local slash-command surface
+- improving continuation when review needs an interactive or assisted provider
+- finishing publish and release hardening for packaged installs
+
+For a fuller roadmap summary, see:
+
+- `docs/next-steps.md`