auditor-lambda 0.2.6 → 0.2.9

package/docs/agent-integrations.md

@@ -14,6 +14,17 @@ Normal product usage should:
 - 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:
@@ -26,8 +37,8 @@ The preferred bootstrap path is:
 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.
+That installs repo-local `/audit-code` surfaces and MCP-oriented support assets for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity.
+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 one of these supported ways to obtain the raw prompt asset directly when you need prompt import instead:
 
@@ -44,58 +55,56 @@ 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
+### Codex
 
-Use `audit-code install` from the target repository root.
+Use `audit-code install --host codex` or the default `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.
+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 narrower `audit-code install-host --host copilot` alias still exists, but it is no longer the preferred setup path.
+The Codex automation recipe should still be treated as optional follow-through after the basic local flow is validated in the real app.
 
-### OpenCode
+### Claude Desktop
 
-Use `audit-code install` from the target repository root.
+Use `audit-code install --host claude-desktop` or the default `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.
+This repository now treats Claude Desktop as an MCP-first host. The installer writes:
 
-### Claude Code
+- `.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
 
 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.
+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
 
 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.
 
-### 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.import.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:
+There is still no documented native repo-local saved-workflow surface for Antigravity in this repository today, so the intended path is:
 
-1. import `.audit-code/install/audit-code.import.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
+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 Claude Desktop and Antigravity.
+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.
 
@@ -138,7 +147,11 @@ 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 still needs imported results or a provider-capable continuation path.
 
-When `provider` is configured as `claude-code`, `opencode`, `subprocess-template`, or `vscode-task`, the wrapper can now continue through audit-task review in the same invocation as long as that provider can write structured `AuditResult[]` output and hand control back to the bounded worker command.
+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 long-term 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:
 
@@ -151,6 +164,7 @@ 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
 
@@ -168,19 +182,17 @@ This is the safest default backend when the repository is already available loca
 
 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.
-When audit-task review is pending, the provider prompt now asks Claude Code to write structured audit results and then hand back to the bounded worker command so the same wrapper invocation can continue.
+The current implementation can launch 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.
+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 built-in adapter launches a fresh `opencode run ...` session for each worker run.
-When audit-task review is pending, the provider prompt now asks OpenCode to write structured audit results and then hand back to the bounded worker command so the same wrapper invocation can continue.
+The current implementation can launch a fresh `opencode run ...` session for each worker run.
 
-Recommended when OpenCode is the preferred local agent surface.
+Treat this as a compatibility bridge only, not as the intended default review owner.
 
 ### subprocess-template
 
@@ -197,11 +209,15 @@ 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.
+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 the same repo-local `audit-code` wrapper, or set `provider` to `opencode` so the supervisor delegates bounded worker runs into 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
 
@@ -224,6 +240,17 @@ Current recommended usage is one of these:
 
 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, and VS Code 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:
@@ -240,3 +267,5 @@ For a polished operator experience today:
 3. use `audit-code` as the repo-local backend fallback
 4. prefer `local-subprocess` unless you want interactive review to continue automatically through agent tasks
 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, re-run with an explicit `--provider` flag after configuring the matching section in `.audit-artifacts/session-config.json`.

package/docs/artifacts.md

@@ -1,8 +1,10 @@
-# Core artifacts
+# Core Artifacts
 
-These JSON artifacts are the stable contract between deterministic tooling and LLM audit passes.
+This document follows [audit-goals.md](C:/Code/auditor-lambda/spec/audit-goals.md).
 
-## Core files
+## Incomplete-run artifacts
+
+During an incomplete or blocked audit, `.audit-artifacts/` may contain:
 
 - `repo_manifest.json`
 - `file_disposition.json`
@@ -13,64 +15,22 @@ These JSON artifacts are the stable contract between deterministic tooling and L
 - `flow_coverage.json`
 - `risk_register.json`
 - `coverage_matrix.json`
-- `runtime_validation_tasks.json`
-- `runtime_validation_report.json`
+- `runtime_validation_tasks.json` when deterministic runtime validation is planned
+- `runtime_validation_report.json` when runtime validation has executed or been updated
 - `external_analyzer_results.json`
 - `audit_tasks.json`
 - `audit_results.jsonl`
 - `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.
+- dispatch files for the currently active worker task
 
-External analyzer results now also influence:
+## Scope rule
 
-- risk scoring
-- required lenses in coverage
-- task priority
-- dedicated analyzer follow-up tasks
-- requeue priority
-- synthesis evidence and summaries
+Excluded files remain visible in deterministic intake/disposition where useful,
+but they must not create audit work. This includes logs, licenses, lockfiles,
+generated artifacts, vendored artifacts, binaries, and trivial non-code files.
 
-## Key schema notes
+## Completion rule
 
-- `audit_tasks.json`: each task already contains the resolved `file_paths` it covers. Use `audit-code explain-task <task_id>` when you want that task joined back to current `coverage_matrix.json` state.
-- `coverage_matrix.json`: each file records `classification_status`, `audit_status`, `required_lenses`, and `completed_lenses`.
-- `synthesis_report.json`: this is the top-level synthesis artifact. It includes `merged_findings`, semantic `root_cause_clusters`, and `work_blocks`; `work_blocks` are the primary remediation grouping.
+These artifacts are transient implementation state only. When the audit
+completes, `.audit-artifacts/` is removed and only repo-root `audit-report.md`
+remains.

package/docs/bootstrap-install.md

@@ -8,65 +8,86 @@ audit-code install
 
 That command installs the repo-local `/audit-code` surfaces we can automate today.
 
-## What it writes
-
-Installed command surfaces:
+After bootstrap, run:
 
-- `.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
+```bash
+audit-code verify-install
+```
 
-Installed always-on compatibility surfaces:
+That smoke-tests the generated host assets plus the shared repo-local MCP launcher without waiting for a full editor walkthrough.
 
-- `.github/copilot-instructions.md`
-- `AGENTS.md`
-- `CLAUDE.md`
+## What it writes
 
-Installed repo-local canonical assets:
+Installed shared surfaces:
 
 - `.audit-code/install/audit-code.import.md`
 - `.audit-code/install/SKILL.md`
 - `.audit-code/install/GETTING-STARTED.md`
+- `.audit-code/install/manifest.json`
+- `.audit-code/install/run-mcp-server.mjs`
+
+Installed host-specific surfaces:
+
+- Codex:
+  - `.codex/skills/audit-code/*`
+  - `AGENTS.md` managed block when needed
+  - `.audit-code/install/codex/MCP-SETUP.md`
+  - `.audit-code/install/codex/RE-AUDIT-AUTOMATION.md`
+- Claude Desktop:
+  - `.audit-code/install/claude-desktop/PROJECT-TEMPLATE.md`
+  - `.audit-code/install/claude-desktop/remote-mcp-connector.json`
+  - `.audit-code/install/claude-desktop/auditor-lambda.dxt`
+  - `.audit-code/install/claude-desktop/auditor-lambda.mcpb`
+- OpenCode:
+  - `.opencode/commands/audit-code.md`
+  - `.opencode/skills/audit-code/*`
+  - `opencode.json`
+  - `AGENTS.md` managed block when needed
+- VS Code:
+  - `.github/prompts/audit-code.prompt.md`
+  - `.github/copilot-instructions.md`
+  - `.github/agents/auditor.agent.md`
+  - `.vscode/mcp.json`
+- Antigravity:
+  - `.audit-code/install/antigravity/PLANNING-MODE.md`
+  - `AGENTS.md` managed block when needed
 
 The generated `GETTING-STARTED.md` now includes dedicated quick-start sections for:
 
-- VS Code
-- OpenCode
-- Claude Code
+- Codex
 - Claude Desktop
+- OpenCode
+- VS Code
 - 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:
+After bootstrap, the user should be able to open a supported host surface in the repository and invoke:
 
 ```text
 /audit-code
 ```
 
-without supplying extra root paths, provider flags, or model-selection arguments.
+without supplying extra root paths, provider flags, or model-selection arguments, or connect through the shared MCP server when the host prefers tool-driven integration.
 
 ## 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`
+- shared installer output, manifest generation, and repo-local MCP launcher generation
+- Codex skill-bundle and AGENTS-oriented install output
+- OpenCode command, skill, prompt, and config generation
+- VS Code prompt, custom-agent, instruction, and MCP config generation
+- Claude Desktop project-template, remote-connector, and local bundle generation
+- Antigravity planning-mode guidance generation
 
 ## 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
+- product-level smoke validation for the generated Codex, Claude Desktop, OpenCode, and VS Code assets
+- one-click proof that the generated Claude Desktop bundle installs cleanly in a real Desktop environment
+- documented Antigravity artifact round-tripping back through `import_results` and `import_runtime_updates`
 
-For those hosts, the bootstrap command still installs compatibility assets, but the final `/audit-code` discovery behavior remains host-dependent.
+For those gaps, the bootstrap command now writes the repo-local assets and guidance, but the final operator experience still needs end-to-end host verification.
 
-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.
+Use `.audit-code/install/GETTING-STARTED.md` as the low-guess repo-local handoff, and treat `.audit-code/install/manifest.json` as the machine-readable source of truth for what was generated.
 
 ## Narrow compatibility alias
 
@@ -77,3 +98,12 @@ audit-code install-host --host copilot
 ```
 
 Use it only when you intentionally want the smaller Copilot-only install path instead of the default bootstrap.
+
+## Remaining steps
+
+The installer foundation is now in place. The remaining work is:
+
+1. smoke-test each claimed host in the real product, not only via file-generation tests
+2. tighten `GETTING-STARTED.md` and host-specific setup docs where those smoke tests show friction
+3. prove the Claude Desktop local bundle install path operationally
+4. document Antigravity artifact-import workflows more concretely