auditor-lambda 0.3.4 → 0.3.6

package/docs/dispatch-implementation-plan.md

@@ -3,8 +3,8 @@
 This document describes the implemented review-dispatch path for `/audit-code`.
 The original dispatch plan was one agent per audit task. The current path keeps
 the existing `AuditTask` and `AuditResult` contracts, but groups related tasks
-into review packets so a worker can read a coherent file set once and produce
-one validated result file for each assigned task.
+into review packets so a worker can read a coherent file set once and submit
+one validated result for each assigned task through a backend-owned write path.
 
 ## Current Workflow
 
@@ -15,15 +15,16 @@ one validated result file for each assigned task.
 
 2. audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
    -> reads pending-audit-tasks.json and review planning artifacts
-   -> writes dispatch-plan.json
+   -> writes a slim dispatch-plan.json
+   -> writes backend-owned dispatch-result-map.json
    -> writes one packet prompt per dispatch-plan entry
    -> prints one compact JSON envelope
 
 3. Conversation orchestrator reads only dispatch-plan.json
    -> launches one subagent per packet
    -> each subagent reads its packet prompt and assigned files
-   -> each subagent writes one task-results/<task_id>.json per underlying task
-   -> each subagent runs the validation commands in the prompt
+   -> each subagent pipes AuditResult[] to the submit-packet command in the prompt
+   -> submit-packet validates and writes only backend-assigned result files
    -> each subagent replies: valid: <packet_id>, findings=<n>
 
 4. audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
@@ -62,6 +63,7 @@ Packet planning is deterministic and compatibility-preserving:
 - graph edges from imports, calls, and references can merge related task groups
 - heuristic container edges do not force packet expansion
 - packet chunking respects task-count and line-budget limits
+- a single file that exceeds the packet target is isolated rather than split
 - high-priority packets sort ahead of lower-priority packets
 
 Generated packets include:
@@ -88,7 +90,10 @@ audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
 Artifacts:
 
 - `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`
+- `<artifacts_dir>/runs/<run_id>/dispatch-result-map.json`
 - `<artifacts_dir>/runs/<run_id>/task-results/<packet_id>.prompt.md`
+- `<artifacts_dir>/runs/<run_id>/task-results/<packet_id>.anchors.json`,
+  only for isolated large-file packets
 - `<artifacts_dir>/runs/<run_id>/dispatch-warnings.json`, only when warnings
   exist
 
@@ -115,24 +120,53 @@ The command prints a compact JSON envelope:
 ```json
 {
   "packet_id": "src-auth:security-correctness:packet-1-...",
-  "task_id": "src-auth:security-correctness:packet-1-...",
-  "task_ids": ["src-auth:security", "src-auth:correctness"],
   "description": "Audit 2 file(s), 2 task(s), 2 lens(es) (~70 lines)",
-  "output_paths": {
-    "src-auth:security": ".audit-artifacts/runs/run-1/task-results/src-auth_security.json",
-    "src-auth:correctness": ".audit-artifacts/runs/run-1/task-results/src-auth_correctness.json"
+  "prompt_path": ".audit-artifacts/runs/run-1/task-results/src-auth_security-correctness_packet-1_ab12cd34ef56.prompt.md",
+  "complexity": {
+    "priority": "high",
+    "task_count": 2,
+    "file_count": 2,
+    "total_lines": 70,
+    "estimated_tokens": 1180,
+    "lenses": ["security", "correctness"],
+    "tags": ["critical_flow"],
+    "large_file_mode": false
   },
-  "prompt_path": ".audit-artifacts/runs/run-1/task-results/src-auth_security-correctness_packet-1.prompt.md",
-  "lenses": ["security", "correctness"],
-  "file_paths": ["src/api/auth.ts", "src/lib/session.ts"],
-  "total_lines": 70,
-  "estimated_tokens": 1180
+  "model_hint": {
+    "tier": "deep",
+    "reasons": ["high_priority", "critical_flow"]
+  }
 }
 ```
 
 The orchestrator should launch one subagent per entry with the entry
 description and a prompt that tells the subagent to read and follow
 `entry.prompt_path`.
+If the host supports per-subagent model selection, it may map
+`entry.model_hint.tier` (`small`, `standard`, or `deep`) to local model names.
+These hints are provider-neutral; the backend does not hardcode model names or
+require model selection during normal use.
+
+## Large File Mode
+
+The workflow does not impose a hard single-file size limit. When a packet is
+large because it contains one large file, `prepare-dispatch` keeps that file in
+an isolated packet and writes a mechanical anchor summary next to the packet
+prompt. The anchor summary may include:
+
+- file boundaries
+- imports and exports
+- top-level symbols
+- route-like declarations
+- risk keywords
+- graph edges
+- external analyzer signals
+
+The packet prompt points the worker at the anchor file and asks for targeted
+reads/searches within the assigned file. The backend still validates and writes
+results through `submit-packet`. This keeps large-file review bounded by
+mechanically generated structure without slicing files into arbitrary line
+ranges.
 
 ## Packet Prompt Contract
 
@@ -141,20 +175,31 @@ Each packet prompt tells the worker to:
 - review the packet once
 - read only the listed repo-relative files
 - produce one JSON object per listed task
-- write each object to that task's exact `output_path`
+- pipe one JSON array to the prompt's `submit-packet` command
 - preserve the existing `AuditResult` fields:
   `task_id`, `unit_id`, `pass_id`, `lens`, `file_coverage`, `findings`
 - keep `file_coverage[]` as `{ path, total_lines }`
 - keep every finding lens equal to the task lens
-- avoid source edits, remediation, extra task results, and unrelated audits
-- run the generated validation command for every task result
-- reply exactly `valid: <packet_id>, findings=<total finding count>` after all
-  validation commands pass
+- avoid direct file writes, source edits, remediation, extra task results, and
+  unrelated audits
+- reply exactly `valid: <packet_id>, findings=<total finding count>` after the
+  submit command accepts the packet
 
 This keeps packet review efficient while leaving merge and ingestion
 mechanically deterministic.
 
-## Validation
+## Submission and Validation
+
+Packet submission is exposed through:
+
+```bash
+audit-code submit-packet --run-id <run_id> --packet-id <packet_id> --artifacts-dir <artifacts_dir>
+```
+
+The command reads `AuditResult[]` from stdin, validates the complete assigned
+packet, and writes only the backend-assigned per-task result paths from
+`dispatch-result-map.json`. This keeps result writes out of the LLM prompt and
+prevents swapped or unknown task result files from being ingested.
 
 Per-task validation is exposed through:
 
@@ -162,6 +207,10 @@ Per-task validation is exposed through:
 audit-code validate-result --run-id <run_id> --task-id <task_id> --artifacts-dir <artifacts_dir>
 ```
 
+Generated packet prompts may pass run ids, packet ids, task ids, and artifact paths through
+base64url flags such as `--run-id-b64`, `--packet-id-b64`, `--task-id-b64`, and
+`--artifacts-dir-b64` when raw values could contain shell-sensitive characters.
+
 The validator checks the result against the assigned task set and enforces the
 mechanical constraints that matter for ingestion:
 
@@ -171,7 +220,7 @@ mechanical constraints that matter for ingestion:
 - line spans do not exceed known `total_lines`
 - result fields conform to the shipped schemas
 
-Workers should retry invalid JSON up to the bounded retry count in the prompt.
+Workers should retry rejected submissions up to the bounded retry count in the prompt.
 
 ## `merge-and-ingest` Output
 
@@ -183,7 +232,9 @@ audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
 
 Merge behavior:
 
-- validates every JSON file under `task-results/`
+- validates every backend-assigned result-map path
+- rejects unexpected JSON files under `task-results/`
+- rejects task IDs that appear in the wrong assigned result path
 - rejects duplicate task results
 - rejects unknown task IDs
 - rejects missing assigned task results

package/docs/github-copilot.md

@@ -30,7 +30,7 @@ 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 generated prompt file explicitly sets `agent: auditor` so Copilot Chat uses the generated auditor custom agent
 - 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
 

package/docs/model-selection.md

@@ -13,6 +13,17 @@ For that surface, the default model rule is:
 
 That is the intended product contract.
 
+When packet dispatch is prepared, `dispatch-plan.json` includes
+provider-neutral complexity metadata and a `model_hint.tier` value:
+
+- `small` for tiny, low-priority packets without sensitive lenses or risk tags
+- `standard` for ordinary bounded review packets
+- `deep` for high-priority, large, critical-flow, or external-signal packets
+
+Hosts that support per-subagent model choice may map those tiers to their own
+available models. Hosts that do not support model choice can ignore the fields.
+The backend still does not prescribe concrete model names.
+
 ## 2. Backend provider rule
 
 When the local backend delegates bounded worker runs into an external provider, model selection becomes provider-specific.

package/docs/next-steps.md

@@ -3,7 +3,7 @@
 This document tracks the next meaningful implementation work after the packet
 review-dispatch refactor and the current skill-first productionization pass.
 
-As of April 22, 2026, the shared MCP substrate and the first host-native installer pass have landed, but this repository is not yet ready for a public production launch.
+As of April 30, 2026, the shared MCP substrate and the host-native installer pass have landed, but this repository is not yet ready for a public production launch.
 
 See:
 
@@ -144,7 +144,7 @@ Status:
 
 Most likely shape:
 
-- run fresh-repo smoke checks inside Codex, Claude Desktop, OpenCode, and VS Code
+- run fresh-repo smoke checks inside Codex, Claude Desktop, OpenCode, and VS Code, with Antigravity validated against its planning-mode path
 - confirm that the generated files are both syntactically valid and actually discovered by each host
 - tighten generated docs wherever operator confusion appears during those checks
 - keep Antigravity as a documented planning-mode path unless a stable project config contract is published

package/docs/packaging.md

@@ -17,6 +17,8 @@ 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 companion Codex/OpenCode skill asset at `skills/audit-code/SKILL.md`
+- packet-dispatch support data such as `dispatch/lens-definitions.json`
 - 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.
@@ -76,11 +78,11 @@ The repository now includes packaging metadata and lifecycle hooks intended for
 
 - `package.json` is no longer marked private
 - `publishConfig.access` defaults publication to the public npm access level
-- package contents are curated with a `files` allowlist that includes the canonical prompt asset
+- package contents are curated with a `files` allowlist that includes the canonical prompt, skill, dispatch, schema, and runtime assets
 - `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
+- packaged smoke now verifies the tarball includes `audit-code-wrapper-lib.mjs`, the prompt and skill assets, dispatch lens definitions, the response schema, and `dist/` entrypoints before install-time smoke runs
 - the GitHub publish workflow uses the same release gate before `npm publish`
 - the GitHub publish workflow uses npm Trusted Publishing with GitHub OIDC instead of a long-lived publish token
 - prerelease versions now default to the `next` dist-tag in the publish workflow unless an explicit tag override is chosen on manual dispatch

package/docs/production-launch-bar.md

@@ -25,6 +25,8 @@ Anything below `dist/index.js` remains a backend or development interface rather
 - packaged installs must include:
   - `audit-code`
   - `audit-code-wrapper-lib.mjs`
+  - `dispatch/lens-definitions.json`
+  - `skills/audit-code/SKILL.md`
   - `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
@@ -38,7 +40,7 @@ Anything below `dist/index.js` remains a backend or development interface rather
 ### 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`
+- Codex, Claude Desktop, OpenCode, VS Code / GitHub Copilot, and Antigravity repository surfaces are generated 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
 

package/docs/production-readiness.md

@@ -2,7 +2,7 @@
 
 ## Verdict
 
-As of April 22, 2026, the package release path is ready for a public npm release candidate, but the broader host experience still has follow-through work before it should be described as a frictionless production launch.
+As of April 30, 2026, the package release path has a strong in-repo release gate, but the broader host experience still has follow-through work before it should be described as a frictionless production launch.
 
 What is already true:
 
@@ -11,9 +11,9 @@ What is already true:
 - linked-install smoke coverage passes
 - packaged-install smoke coverage passes
 - packaged tarball contract verification passes
-- `npm run verify:release` passes for the current `0.2.8` worktree
-- local `npm publish --dry-run` passes for `auditor-lambda@0.2.8`
-- npm currently reports `auditor-lambda@0.2.6` as `latest`, so the checked-in release version is still unpublished
+- `npm run verify:release` is the authoritative local release gate for the current worktree
+- local `npm publish --dry-run` should be run before any release candidate publish
+- npm registry state should be verified at release time rather than inferred from checked-in docs
 - 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`
@@ -27,7 +27,7 @@ The biggest remaining gaps are product and release-operational, not core wrapper
 1. npm publication is not fully proven end to end.
    The repo now has a Trusted Publishing workflow and a passing local dry run, but npm-side trusted publisher setup plus the first GitHub Actions dry run still need to be completed 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.
+   Codex, Claude Desktop, OpenCode, VS Code / Copilot, and Antigravity now share the same bootstrap command, but each generated host surface still needs real-product verification before it can be called frictionless.
 3. Provider-assisted continuation still needs polish outside the happy path.
    Configured interactive bridges can now continue through audit-task review, but operator guidance and host-specific ergonomics still need refinement when a provider cannot produce results cleanly.
 
@@ -38,7 +38,7 @@ The explicit launch bar is now documented in `docs/production-launch-bar.md`, an
 1. Confirm release operations externally.
    Validate npm package-name ownership for `auditor-lambda`, configure npm Trusted Publishing for `.github/workflows/publish-package.yml`, and run a real GitHub Actions dry run or prerelease publish from that 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.
+   Keep `audit-code install` stable for Codex, Claude Desktop, OpenCode, VS Code / Copilot, and Antigravity, and close the remaining friction gap for hosts that still lack a verified repo-local install surface.
 3. Polish provider-assisted UX.
    Keep the new continuation path explicit and inspectable while improving failure hints, host guidance, and operator recovery when a provider bridge misbehaves.
 

package/docs/run-flow.md

@@ -14,11 +14,13 @@ This document describes the backend execution flow that supports that conversati
 4. Build `review_packets.json` and `audit_plan_metrics.json` from those tasks.
 5. Stop at semantic review with an active run handoff.
 6. `prepare-dispatch` writes a small run-scoped `dispatch-plan.json` and one
-   prompt per review packet.
+   prompt per review packet, plus a backend-owned result map.
+   Isolated large-file packets also get mechanical anchor summaries for
+   targeted review.
 7. The active conversation orchestrator launches one bounded subagent per
    packet when the host supports subagents.
-8. Each subagent writes one validated `AuditResult` JSON object per underlying
-   task.
+8. Each subagent pipes `AuditResult[]` to the packet's `submit-packet` command;
+   the backend validates and writes assigned result files.
 9. `merge-and-ingest` validates the full assigned task set and ingests the
    existing `AuditResult[]` shape.
 10. Result ingestion updates coverage, requeue, runtime-validation state, and

package/docs/session-config.md

@@ -59,7 +59,9 @@ Current implementation note:
 
 - `claude-code`, `opencode`, `subprocess-template`, and `vscode-task` are backend compatibility bridges
 - they are not the intended default owner of semantic review when the active conversation agent can handle the work directly
-- to activate one of those bridges for semantic review, re-run the wrapper with an explicit `--provider <name>` flag
+- to activate one of those bridges for semantic review, either set `provider`
+  in this file intentionally or re-run the wrapper with an explicit
+  `--provider <name>` flag
 
 ### `timeout_ms`
 
@@ -141,11 +143,17 @@ This remains the safest fallback default while the semantic-review workflow is b
 Fields:
 
 - `command`: optional override for the Claude Code executable
-- `extra_args`: optional extra arguments appended before the built-in permission-skipping flag
+- `extra_args`: optional extra arguments for Claude Code
+- `dangerously_skip_permissions`: optional trusted-automation opt-in. When
+  `true`, the bridge appends `--dangerously-skip-permissions`. Leave this
+  unset for the safer default.
 
 Current implementation support only.
 
-Use this only when you intentionally want the backend fallback CLI to bridge review into an external Claude Code process, together with `audit-code --provider claude-code`.
+Use this only when you intentionally want the backend fallback CLI to bridge
+review into an external Claude Code process, either by setting
+`provider: "claude-code"` in this file or by running
+`audit-code --provider claude-code`.
 
 ### `opencode`
 

package/docs/supervisor.md

@@ -63,9 +63,11 @@ audit-code --provider subprocess-template
 audit-code --provider vscode-task
 ```
 
-Those `--provider` invocations are the explicit bridge handoff point.
-Without an explicit `--provider` flag, the backend stops at the semantic-review
-boundary and exposes scoped task artifacts for the slash-command orchestrator.
+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
 

package/docs/workflow-refactor-brief.md

@@ -15,7 +15,8 @@ The implemented design is a compatibility-preserving packet layer:
 - 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
-- write one validated result file per underlying task
+- submit packet results through the backend so only assigned result files are
+  written
 
 ## Current Product Model
 
@@ -42,9 +43,11 @@ The refactor now includes:
 - 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 outputs to one worker
+- 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
+  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>`
@@ -75,7 +78,10 @@ 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
 
@@ -86,7 +92,7 @@ remain backend-owned.
 
 Current in-repo verification:
 
-- `npm test` passes with 143 tests.
+- `npm test` passes with 148 tests.
 
 Relevant test coverage:
 
@@ -95,8 +101,11 @@ Relevant test coverage:
 - graph-connected packet merging
 - tiny test-file batching
 - packet prompt generation
-- packet merge compatibility with the legacy result array
+- 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/skills/audit-code/SKILL.md

@@ -28,6 +28,10 @@ command, then stop so the user can rerun `/audit-code` from fresh context.
 Subagent fan-out belongs to the host agent runtime rather than to repo-local
 backend provider settings.
 
+When dispatch-plan entries include provider-neutral complexity and
+`model_hint.tier` metadata, a capable host may map those tiers to its own
+subagent models. The backend should not prescribe concrete model names.
+
 Bounded steps are a backend implementation detail, not the intended user experience.
 
 ## Embedded Prompt Payload

package/skills/audit-code/audit-code.prompt.md

@@ -1,7 +1,7 @@
 ---
 description: Autonomous local loop code auditing - advances deterministic audit state, delegates bounded review tasks, and ingests validated results
 argument-hint: [target-dir]
-allowed-tools: [Read, Write, Bash, Glob, Grep, Agent]
+allowed-tools: [Read, Bash, Glob, Grep, Agent]
 ---
 
 # `/audit-code` Execution Directive
@@ -81,14 +81,24 @@ In a single message, launch one Agent/subagent call per dispatch-plan entry:
 Agent({ description: entry.description, prompt: "Read and follow the audit instructions in: " + entry.prompt_path })
 ```
 
+If the host supports per-subagent model selection, use `entry.model_hint.tier`
+as a provider-neutral routing hint (`small`, `standard`, or `deep`). Map it to
+available host models without asking the user to choose model names. If model
+selection is unavailable, ignore the hint and dispatch normally.
+
+If the host supports per-subagent tool restrictions, give review subagents no
+Write tool and allow shell access only for the `audit-code submit-packet`
+command printed in their prompt.
+
 All subagent calls should be launched together. Wait for them to finish.
 
 Subagents own bounded semantic review. They must read only their prompt and
-assigned files, write exactly the requested audit result JSON to `output_path`,
-run the validation command in their prompt, retry up to 3 times if validation
-fails, and stop. They must not edit source files, remediate findings, create
-extra task results, run unrelated audits, or write the worker `result.json`
-control envelope.
+assigned files, produce the requested `AuditResult[]`, pipe it to the
+`submit-packet` command in their prompt, retry up to 3 times if submission
+fails, and stop. The backend command validates and writes the packet-owned
+result artifacts. They must not use direct file writes, edit source files,
+remediate findings, create extra task results, run unrelated audits, or write
+the worker `result.json` control envelope.
 
 Then run: