auditor-lambda 0.1.0

package/docs/production-launch-bar.md

@@ -0,0 +1,83 @@
+# Production Launch Bar
+
+This document defines the minimum bar this repository should meet before a version is described as production-ready.
+
+It is intentionally narrower than the broader product roadmap in `docs/next-steps.md`.
+
+## Supported product surfaces
+
+The current product surfaces are:
+
+1. `/audit-code` in conversation as the canonical user-facing route
+2. `audit-code prompt-path` as the stable way to locate the packaged prompt asset
+3. `audit-code install` as the preferred repo-local bootstrap installer
+4. `audit-code` as the repo-local backend fallback wrapper
+
+Anything below `dist/index.js` remains a backend or development interface rather than the primary end-user contract.
+
+## Supported backend expectations
+
+### Node and package runtime
+
+- Node `>=20` is the minimum supported runtime from `package.json`
+- packaged installs must include:
+  - `audit-code`
+  - `audit-code-wrapper-lib.mjs`
+  - `skills/audit-code/audit-code.prompt.md`
+  - `schemas/audit-code-v1alpha1.schema.json`
+- the checked-in `dist/` output is part of the shipped runtime contract for installed usage
+
+### Backend providers
+
+- `local-subprocess` is the safest default fallback and must keep working without extra provider setup
+- `claude-code`, `opencode`, `subprocess-template`, and `vscode-task` are supported backend adapters when configured correctly
+- `provider: "auto"` is best-effort routing, not a stronger support guarantee than the underlying resolved provider
+
+### Host surfaces
+
+- ChatGPT-style project conversations are the intended `/audit-code` product surface
+- VS Code / GitHub Copilot, OpenCode, and Claude Code repositories are supported through `audit-code install`
+- editor integrations that import `skills/audit-code/audit-code.prompt.md` are supported as prompt-based integrations
+- no editor-specific native install surface should be called production-ready until it has explicit documentation and a repeatable verification path
+
+## Required verification before calling a release production-ready
+
+Run this from the repository root:
+
+```bash
+npm ci
+npm run verify:release
+```
+
+`npm run verify:release` is the in-repo minimum release gate. It currently covers:
+
+- TypeScript typecheck
+- full automated test suite
+- linked-install `audit-code` smoke coverage
+- packaged-install `audit-code` smoke coverage
+- tarball contract verification for required shipped assets and runtime entrypoints
+- packaged and linked verification of the bootstrap install path
+
+In addition to the in-repo gate, production readiness still requires these external checks:
+
+1. confirm npm package-name ownership and intended publish target
+2. confirm `NPM_TOKEN` availability for the publish workflow
+3. run a real pre-release or dry-run publish from the release path you intend to use
+
+## Operator validation expectations
+
+Before treating the backend fallback as healthy for a repository, `audit-code validate` should pass with zero issues.
+
+That validation now covers:
+
+- artifact-bundle consistency
+- `session-config.json` shape
+- explicit provider readiness for configured external CLIs
+
+## Current residual risk
+
+This repository has a clear backend release gate, but it still should not be called fully production-ready until:
+
+1. hosts without a verified repo-local slash-command surface still have a comparably low-friction bootstrap path
+2. interactive continuation is smoother when assisted review must continue through a provider
+3. external publish operations are proven end to end

package/docs/production-readiness.md

@@ -0,0 +1,52 @@
+# Production Readiness
+
+## Verdict
+
+As of April 17, 2026, this repository is not yet ready for a public production launch.
+
+It is in good shape for a controlled alpha or beta release:
+
+- TypeScript build passes
+- automated test suite passes
+- linked-install smoke coverage passes
+- packaged-install smoke coverage passes
+- packaged tarball contract verification passes
+- malformed config and corrupted artifact handling are explicit
+- blocked fallback runs now emit structured operator handoff guidance
+- supported repo-local hosts now share a bootstrap install path via `audit-code install`
+
+## Why It Is Not Yet Production-Ready
+
+The biggest remaining gaps are product and release-operational, not core wrapper correctness:
+
+1. npm publication is not fully proven end to end.
+   The repo has publish automation, but package-name ownership and registry credentials still need to be confirmed outside the codebase.
+2. The primary conversation-first product still has setup friction on hosts without a verified repo-local slash-command surface.
+   VS Code / Copilot, OpenCode, and Claude Code now share a bootstrap path, but Claude Desktop, Antigravity, and other hosts still need more work.
+3. Assisted-review continuation is still only partially solved.
+   The fallback wrapper now explains blocked states much better, but the smoothest path is still missing when an interactive provider should continue the review directly.
+
+The explicit launch bar is now documented in `docs/production-launch-bar.md`, and the in-repo release gate is codified as `npm run verify:release`.
+
+## Required Next Steps
+
+1. Confirm release operations externally.
+   Validate npm package-name availability and ownership for `auditor-lambda`, confirm `NPM_TOKEN` access in GitHub Actions, and run a real pre-release or dry-run publish from the release workflow path.
+2. Extend bootstrap coverage beyond the currently automated hosts.
+   Keep `audit-code install` stable for VS Code / Copilot, OpenCode, and Claude Code, and close the remaining friction gap for hosts that still lack a verified repo-local install surface.
+3. Improve interactive continuation.
+   When an interactive provider is configured, continue through provider-assisted review with less operator handoff and less manual evidence re-import.
+
+## Nice-To-Have Follow-On Work
+
+- expand host-specific setup guides once the first native integration lands
+- keep release smoke coverage and contract tests fast enough to stay in the publish gate
+- keep `docs/production-launch-bar.md` aligned with the real verification and support surface
+- preserve the packaged prompt asset and `audit-code prompt-path` as hard compatibility guarantees
+
+## Related Docs
+
+- `docs/next-steps.md`
+- `docs/packaging.md`
+- `docs/agent-integrations.md`
+- `docs/production-launch-bar.md`

package/docs/repo-layout.md

@@ -0,0 +1,30 @@
+# Repository layout
+
+## Top-level purpose
+
+- `docs/`: architecture, pipeline, layout, and design notes
+- `schemas/`: JSON schemas for stable intermediate artifacts
+- `skills/audit-code/`: portable prompt assets and skill-facing product instructions
+- `src/`: implementation code for extraction, orchestration, coverage, and reporting
+- `examples/`: example artifacts demonstrating expected shapes
+- `.audit-artifacts/`: runtime-generated local artifact bundle for fallback wrapper runs; do not commit it
+- `dist/`: checked-in compiled runtime output used by the packaged entrypoint
+- `docs/next-steps.md`: current roadmap and next implementation notes
+- `docs/production-launch-bar.md`: explicit minimum launch criteria and release verification bar
+- `docs/production-readiness.md`: current production-readiness verdict and launch blockers
+
+## Near-term code layout
+
+- `src/extractors/`: deterministic collectors and heuristic classifiers
+- `src/orchestrator/`: task construction, chunking, pass logic, and requeue support
+- `src/coverage/` or `src/coverage.ts`: coverage accounting helpers
+- `src/reporting/`: result merging and remediation views
+- `src/types.ts`: shared TypeScript interfaces mirroring the JSON schemas as closely as practical
+
+## Skill portability rule
+
+The repo should be usable even when the host environment changes. For that reason:
+
+- prompts should remain plain markdown
+- artifacts should remain plain JSON
+- orchestration logic should not depend on one editor or one agent runtime

package/docs/run-flow.md

@@ -0,0 +1,49 @@
+# Run flow
+
+The canonical product route is `/audit-code` in conversation.
+
+This document describes the backend execution flow that supports that conversational route and the repo-local fallback wrapper.
+
+## Current backend execution path
+
+1. Build or import a repository manifest.
+2. Build audit units from the repository manifest.
+3. Initialize a coverage matrix from the file list.
+4. Apply unit-to-file coverage requirements.
+5. Build initial audit tasks.
+6. Dispatch those tasks to LLM agents or other runtimes.
+7. Ingest structured audit results.
+8. Apply reviewed ranges and completed lenses to the coverage matrix.
+9. Build requeue tasks for missing lenses or uncovered ranges.
+10. Repeat until coverage rules are satisfied.
+11. Synthesize findings into merged outputs.
+
+## Current backend capability
+
+The current TypeScript implementation already covers:
+
+- repo intake and ignore handling
+- structure and planning artifact generation
+- reviewed-range ingestion from audit results
+- runtime validation update ingestion
+- synthesis and completion tracking
+- backend provider handoff for interactive or assisted review
+
+## Product interpretation
+
+- the conversation route should hide this state machine behind `/audit-code`
+- the repo-local `audit-code` wrapper is fallback infrastructure for operators and local harnesses
+- provider adapters and artifact plumbing are backend details, not the primary product story
+- when fallback execution blocks, the wrapper should still leave behind explicit operator handoff files and suggested evidence-import paths
+
+## Next backend implementation steps
+
+The next backend-focused work should support the conversation route more directly by:
+
+- reducing operator friction when the backend reaches a blocked handoff
+- improving continuation when interactive providers are configured
+- keeping evidence import and runtime-update handoff paths explicit and easier to follow
+
+Broader product priorities are tracked in:
+
+- `docs/next-steps.md`

package/docs/session-config.md

@@ -0,0 +1,232 @@
+# session-config
+
+This file only applies to the backend fallback CLI.
+
+The canonical `/audit-code` conversation route should not require users to touch it.
+
+Backend provider configuration lives at:
+
+```text
+.audit-artifacts/session-config.json
+```
+
+This file is optional.
+
+If it does not exist, the backend defaults to its built-in behavior.
+
+If it exists but contains invalid values, the backend now fails loudly before starting worker runs.
+You can also check it explicitly with:
+
+```bash
+audit-code validate
+```
+
+## Supported fields
+
+```json
+{
+  "provider": "local-subprocess",
+  "timeout_ms": 1800000,
+  "ui_mode": "headless"
+}
+```
+
+### `provider`
+
+Supported values:
+
+- `auto`
+- `local-subprocess`
+- `subprocess-template`
+- `claude-code`
+- `opencode`
+- `vscode-task`
+
+### `timeout_ms`
+
+Worker-run timeout in milliseconds.
+
+### `ui_mode`
+
+Supported values:
+
+- `headless`
+- `visible`
+
+Use `visible` when you want stdout and stderr mirrored into the current terminal while the provider runs.
+
+## Auto provider mode
+
+`auto` is an explicit opt-in mode.
+
+If `provider` is omitted entirely, the backend still defaults to `local-subprocess`.
+
+When `provider` is set to `auto`, resolution works like this:
+
+1. use `vscode-task` when running under VS Code and a `vscode_task.command_template` is configured
+2. otherwise use `subprocess-template` when `subprocess_template.command_template` is configured
+3. otherwise use `claude-code` when Claude Code is available and preferred by config or when it is the only detected external CLI
+4. otherwise use `opencode` when OpenCode is available and preferred by config or when it is the only detected external CLI
+5. otherwise fall back to `local-subprocess`
+
+This keeps the current default stable while still allowing best-effort cross-editor/provider routing when you explicitly want it.
+
+## Provider-specific sections
+
+### `local-subprocess`
+
+No extra config is required.
+
+This mode covers deterministic worker runs locally and stops in a terminal blocked state once the remaining work requires imported audit results or an interactive provider.
+
+### `claude_code`
+
+```json
+{
+  "provider": "claude-code",
+  "ui_mode": "visible",
+  "claude_code": {
+    "command": "claude",
+    "extra_args": []
+  }
+}
+```
+
+Fields:
+
+- `command`: optional override for the Claude Code executable
+- `extra_args`: optional extra arguments appended before the built-in permission-skipping flag
+
+### `opencode`
+
+```json
+{
+  "provider": "opencode",
+  "ui_mode": "visible",
+  "opencode": {
+    "command": "opencode",
+    "extra_args": []
+  }
+}
+```
+
+Fields:
+
+- `command`: optional override for the OpenCode executable
+- `extra_args`: optional additional arguments for `opencode run ...`
+
+### `subprocess_template`
+
+```json
+{
+  "provider": "subprocess-template",
+  "ui_mode": "visible",
+  "subprocess_template": {
+    "command_template": ["bash", "-lc", "{workerCommandShell}"],
+    "env": {}
+  }
+}
+```
+
+Fields:
+
+- `command_template`: required command array
+- `env`: optional environment-variable overlay
+
+### `vscode_task`
+
+```json
+{
+  "provider": "vscode-task",
+  "ui_mode": "visible",
+  "vscode_task": {
+    "command_template": ["bash", "-lc", "{workerCommandShell}"],
+    "env": {}
+  }
+}
+```
+
+This adapter is intentionally thin. It uses the same template expansion model as `subprocess-template`, but is named separately so the operator intent is explicit.
+
+## Template placeholders
+
+`subprocess-template` and `vscode-task` support these placeholders inside each `command_template` entry:
+
+- `{repoRoot}`
+- `{runId}`
+- `{obligationId}`
+- `{promptPath}`
+- `{taskPath}`
+- `{resultPath}`
+- `{stdoutPath}`
+- `{stderrPath}`
+- `{workerCommandShell}`
+- `{workerCommandJson}`
+- `{uiMode}`
+- `{timeoutMs}`
+
+### Placeholder guidance
+
+- Use `{workerCommandShell}` when your launcher can execute a fully rendered shell command directly.
+- Use `{workerCommandJson}` when your launcher wants the worker command as structured data.
+- Use `{promptPath}` and `{taskPath}` when an external tool should read the generated worker instructions instead of directly executing the worker command.
+
+## Suggested starting points
+
+### Safest default
+
+```json
+{
+  "provider": "local-subprocess"
+}
+```
+
+### Best-effort automatic routing
+
+```json
+{
+  "provider": "auto",
+  "ui_mode": "visible"
+}
+```
+
+### Delegate worker runs into Claude Code
+
+```json
+{
+  "provider": "claude-code",
+  "ui_mode": "visible"
+}
+```
+
+### Delegate worker runs into OpenCode
+
+```json
+{
+  "provider": "opencode",
+  "ui_mode": "visible"
+}
+```
+
+### Use a generic bash launcher bridge
+
+```json
+{
+  "provider": "subprocess-template",
+  "ui_mode": "visible",
+  "subprocess_template": {
+    "command_template": ["bash", "-lc", "{workerCommandShell}"]
+  }
+}
+```
+
+## Antigravity note
+
+A dedicated Antigravity adapter is not currently shipped.
+
+Until one exists, the practical options are:
+
+- run `audit-code` from an Antigravity terminal with `local-subprocess`
+- use `provider: "auto"` when you want best-effort routing without forcing a specific backend
+- use `subprocess-template` with a launcher that Antigravity can reliably invoke
+- treat the conversation-level `/audit-code` contract as primary and the backend CLI as fallback

package/docs/supervisor.md

@@ -0,0 +1,83 @@
+# 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.
+
+## 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
+```
+
+## 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.

package/docs/usage.md

@@ -0,0 +1,172 @@
+# 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
+
+Bootstrap 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 --updates /path/to/runtime_validation_update.json
+audit-code --external-analyzer-results /path/to/external_analyzer_results.json
+```
+
+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 --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
+```
+
+This updates:
+
+- `coverage_matrix.json`
+- `flow_coverage.json`
+- `runtime_validation_tasks.json`
+- `runtime_validation_report.json`
+- `audit_results.jsonl`
+- `requeue_tasks.json`
+- `synthesis_report.json`
+
+## 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.