auditor-lambda 0.3.13 → 0.3.15

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/scripts/postinstall.mjs

@@ -25,6 +25,40 @@ function writeGeneratedFile(path, content) {
   return action;
 }
 
+function splitFrontmatter(text) {
+  const normalized = text.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?/u);
+  if (!match) return { body: normalized };
+  return { body: normalized.slice(match[0].length) };
+}
+
+function mergeOpenCodeGlobalConfig(existing, promptBody) {
+  const parsed = existing ? JSON.parse(existing) : {};
+  return {
+    ...parsed,
+    command: {
+      ...(parsed.command && typeof parsed.command === 'object' && !Array.isArray(parsed.command)
+        ? parsed.command
+        : {}),
+      'audit-code': {
+        template: promptBody.trimStart(),
+        description: 'Autonomous local loop code auditing',
+        agent: 'auditor',
+        subtask: false,
+      },
+    },
+  };
+}
+
+function installMergedJson(path, buildMerged) {
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  const merged = buildMerged(existing);
+  const action = existing ? 'updated' : 'installed';
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+  return action;
+}
+
 const promptSource = readRequiredSource(promptSourceFile, 'prompt');
 const skillSource = readRequiredSource(skillSourceFile, 'skill');
 
@@ -32,6 +66,8 @@ if (!promptSource || !skillSource) {
   process.exit(0);
 }
 
+const promptBody = splitFrontmatter(promptSource.toString('utf8')).body;
+
 const installs = [
   {
     label: 'Claude command',
@@ -62,3 +98,16 @@ for (const install of installs) {
     console.warn(`    ${install.path}`);
   }
 }
+
+// Install OpenCode global command via merged config
+const opencodeGlobalConfig = join(homedir(), '.config', 'opencode', 'opencode.json');
+try {
+  const action = installMergedJson(opencodeGlobalConfig, (existing) =>
+    mergeOpenCodeGlobalConfig(existing, promptBody),
+  );
+  console.log(`audit-code: ${action} global OpenCode command in ${opencodeGlobalConfig}`);
+} catch (err) {
+  console.warn(`audit-code: could not install global OpenCode command (${err.message})`);
+  console.warn(`  To install manually, add "command": { "audit-code": { "template": "...", "agent": "auditor" } } to:`);
+  console.warn(`    ${opencodeGlobalConfig}`);
+}

package/docs/agent-integrations.md

@@ -1,318 +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 only repo-local fallback
-instructions and shared launcher assets.
-
-Use `audit-code install --host codex` only when you want to repair or force-refresh
-the Codex fallback files from the target repository root.
-
-That updates `AGENTS.md` through a managed fallback block when needed. It does
-not write a repo-local Codex skill bundle, so Codex should expose only the
-global `/audit-code` command surface.
-The intended operator flow is still conversational first, with the global skill and AGENTS guidance steering the active Codex session toward `/audit-code` and the MCP-backed workflow.
-
-### 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