auditor-lambda 0.3.3 → 0.3.5

package/docs/next-steps.md

@@ -1,6 +1,7 @@
 # Next Implementation Steps
 
-This document tracks the next meaningful implementation work after the current skill-first productionization pass.
+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.
 
@@ -31,22 +32,26 @@ The repository now supports:
 - an explicit in-repo release gate via `npm run verify:release`
 - structured operator handoff output plus `.audit-artifacts/operator-handoff.{json,md}` for blocked fallback runs
 - configured provider bridges that can continue audit-task review by writing structured results and handing control back to the bounded worker command
+- graph-informed review packets, `review_packets.json`, and `audit_plan_metrics.json`
+- compact packet `prepare-dispatch` and `merge-and-ingest` envelopes
 
 That means the current release is suitable for a controlled alpha or beta skill-first workflow with MCP-aware host bootstrapping, but it is not yet the final public production end-state.
 
 ## Near-term priorities
 
-### 1. Realign review dispatch with the conversation-owned workflow
+### 1. Prove packet review dispatch on real repositories
 
-The highest-priority product refactor is to move semantic-review ownership back to the active conversation agent and to replace the current unit-first review fan-out with non-overlapping lens-aware review blocks.
+The highest-priority product follow-through is to validate the packet workflow
+outside this repository and compare it to the legacy fan-out baseline.
 
 Near-term work should focus on:
 
-- making the active conversation agent the default owner of semantic review
-- keeping `agent_task_batch_size` at one review block per task
-- treating backend provider adapters as compatibility bridges rather than the default review owner
-- replacing the current unit-first task planner with a non-overlapping lens-block planner
-- deleting the stale audit state and rerunning the audit only after that refactor lands
+- running `/audit-code` against at least one nontrivial external repository
+- recording packet count, task count, warning count, and largest-packet estimate
+- comparing observed worker count and token/quota behavior against the old
+  one-task-per-worker model
+- tightening packet budgets or warning thresholds if real repositories expose
+  rough edges
 
 The current handoff for this work is:
 

package/docs/product-direction.md

@@ -94,9 +94,11 @@ That means:
 The intended review planner should:
 
 - determine which files require which lenses
-- partition unresolved review into non-overlapping review blocks
-- prefer lens-homogeneous blocks when practical
-- keep the default dispatch granularity to one review block per task
+- preserve `AuditTask` as the deterministic coverage identity
+- group related tasks into graph-informed review packets for worker dispatch
+- review multiple relevant lenses for the same packet in one worker pass
+- keep one validated `AuditResult` object per underlying task
+- batch tiny homogeneous files rather than spawning one worker per small task
 
 ## Default context & model rules
 

package/docs/run-flow.md

@@ -4,28 +4,29 @@ 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.
 
-## Intended review-dispatch path
+## Packet review-dispatch path
 
 1. Build or import a repository manifest.
-2. Build units, flows, and other deterministic structure artifacts.
-3. Determine which files require which lenses.
-4. Partition unresolved file/lens obligations into non-overlapping review blocks.
-5. Hand one review block at a time to the active conversation agent.
-6. Let the active agent decide whether it wants to use subagents in parallel.
-7. Ingest structured audit results.
-8. Mark completed file/lens coverage in the coverage matrix.
-9. Build requeue only for still-missing coverage.
-10. Repeat until coverage rules are satisfied.
-11. Synthesize findings into merged outputs.
-
-## Current implementation note
-
-The current TypeScript backend still has workflow drift:
-
-- planning is still mostly unit-first rather than lens-block-first
-- explicit backend providers can still end up owning semantic review in fallback mode
-
-That drift is being tracked explicitly in [docs/workflow-refactor-brief.md](/C:/Code/auditor-lambda/docs/workflow-refactor-brief.md).
+2. Build units, graph edges, flows, risk, and other deterministic structure
+   artifacts.
+3. Determine which files require which lenses and create compatible
+   `AuditTask` records.
+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, 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 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
+   any selective-deepening follow-up tasks.
+11. Repeat until coverage and runtime rules are satisfied.
+12. Synthesize findings into merged outputs.
 
 ## Current backend capability
 
@@ -33,7 +34,10 @@ The current TypeScript implementation already covers:
 
 - repo intake and ignore handling
 - structure and planning artifact generation
+- graph-first packet review planning
+- compact packet dispatch and merge envelopes
 - reviewed-range ingestion from audit results
+- bounded selective deepening
 - runtime validation update ingestion
 - synthesis and completion tracking
 - backend provider handoff for fallback or compatibility review flows
@@ -43,18 +47,9 @@ The current TypeScript implementation already covers:
 - 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
-- the active conversation agent should own semantic review by default
+- the active conversation agent should own semantic packet dispatch by default
 - 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:
-
-- realigning review planning around non-overlapping lens blocks
-- moving semantic-review ownership back to the active conversation agent
-- keeping backend provider bridges explicitly secondary
-- keeping evidence import and runtime-update handoff paths explicit and easier to follow
-
 Broader product priorities are tracked in:
 
 - `docs/workflow-refactor-brief.md`

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`
 
@@ -80,7 +82,10 @@ How many audit tasks to include in one provider-assisted review batch.
 
 When this is greater than `1`, the generated worker prompt points at `current-tasks.json` / `pending-audit-tasks.json` and expects one `AuditResult` per assigned task.
 
-The intended default review granularity remains one review block per task.
+This setting only affects explicit backend provider-assisted fallback batches.
+The canonical conversation route uses run-scoped review packets from
+`prepare-dispatch` while still preserving one validated `AuditResult` per
+underlying task.
 
 ### `parallel_workers`
 
@@ -138,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

@@ -1,186 +1,124 @@
-# Workflow Refactor Brief
+# Workflow Refactor Status
 
-This document is the handoff for the next context window.
+This document records the packet-dispatch refactor that replaced the older
+one-agent-per-small-task review plan.
 
-Use it as the source of truth for the workflow refactor before running a fresh audit again.
+## Goal
 
-## Why this refactor is needed
+Reduce token and quota usage for `/audit-code` while preserving deterministic
+validation, ingestion, coverage tracking, and report synthesis.
 
-The current implementation still advances deterministic audit state correctly, but the semantic-review phase has drifted away from the intended product behavior.
+The implemented design is a compatibility-preserving packet layer:
 
-The key symptom is that the backend can currently treat `provider` selection as the owner of review work, which is how the recent rerun ended up trying to use `claude-code` from `.audit-artifacts/session-config.json`.
+- keep `AuditTask` as the backend planning and coverage identity
+- keep `AuditResult[]` as the ingestion contract
+- 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
+- submit packet results through the backend so only assigned result files are
+  written
 
-That is not the intended workflow.
+## Current Product Model
 
-## Intended workflow
-
-The intended `/audit-code` workflow is:
+The canonical workflow is still conversation-first:
 
 1. The active conversation agent owns orchestration and ingestion control.
-2. Bounded subagents own semantic review work whenever the host supports them.
+2. Bounded subagents own semantic packet review when the host supports them.
 3. If subagents are unavailable, the conversation agent completes one assigned
-   review task and stops so `/audit-code` can be rerun from fresh context.
-4. Deterministic planning computes which files need which lenses.
-5. Pending review is partitioned into non-overlapping review blocks, preferably grouped by lens.
-6. One dispatched review task should correspond to one review block.
-7. `agent_task_batch_size` should stay `1` by default.
-8. Subagent fan-out belongs to the host agent runtime, not to the backend session config.
-9. Backend provider adapters are fallback compatibility bridges only. They should not be the default review owner.
-
-## Current implementation drift
-
-The current code differs from that model in several important ways.
-
-### 1. Review ownership is provider-mediated
-
-Today, the `agent` executor in the backend fallback path is still routed through `createFreshSessionProvider()` and may spawn an external CLI such as `claude` or `opencode`.
-
-Relevant files:
-
-- [src/cli.ts](/C:/Code/auditor-lambda/src/cli.ts:771)
-- [src/providers/index.ts](/C:/Code/auditor-lambda/src/providers/index.ts:37)
-- [src/providers/claudeCodeProvider.ts](/C:/Code/auditor-lambda/src/providers/claudeCodeProvider.ts:12)
-- [src/providers/opencodeProvider.ts](/C:/Code/auditor-lambda/src/providers/opencodeProvider.ts)
-- [src/providers/spawnLoggedCommand.ts](/C:/Code/auditor-lambda/src/providers/spawnLoggedCommand.ts:24)
-
-### 2. Task planning is unit-first, not lens-first
-
-`buildChunkedAuditTasks()` currently creates tasks as `unit x lens`, then optionally splits oversized files into separate per-lens tasks.
-
-Relevant files:
-
-- [src/orchestrator/taskBuilder.ts](/C:/Code/auditor-lambda/src/orchestrator/taskBuilder.ts:101)
-- [src/orchestrator/unitBuilder.ts](/C:/Code/auditor-lambda/src/orchestrator/unitBuilder.ts:130)
-
-### 3. Required lenses are unioned at the unit level
-
-The planner derives `required_lenses` for a unit, then applies that whole union to every file in the unit.
-
-That means the task count grows with `units x required_lenses`, not with a deliberately partitioned set of file/lens review blocks.
-
-Relevant files:
-
-- [src/orchestrator/unitBuilder.ts](/C:/Code/auditor-lambda/src/orchestrator/unitBuilder.ts:153)
-- [src/orchestrator/planning.ts](/C:/Code/auditor-lambda/src/orchestrator/planning.ts:63)
-- [src/coverage.ts](/C:/Code/auditor-lambda/src/coverage.ts:29)
-
-### 4. Flow augmentation adds overlapping review tasks
-
-After the base unit tasks are built, the planner adds extra flow-aware tasks rather than repartitioning the pending review set into one global non-overlapping dispatch plan.
-
-Relevant file:
-
-- [src/orchestrator/flowPlanning.ts](/C:/Code/auditor-lambda/src/orchestrator/flowPlanning.ts:9)
-
-### 5. `parallel_workers` means subprocess fan-out, not agent-owned parallelism
-
-The current `parallel_workers` setting only controls how many external provider worker runs the backend fallback CLI launches.
-
-It does not represent, and should not limit, the active conversation agent's own ability to use subagents.
-
-Relevant files:
-
-- [src/cli.ts](/C:/Code/auditor-lambda/src/cli.ts:83)
-- [src/cli.ts](/C:/Code/auditor-lambda/src/cli.ts:960)
-
-## Evidence from the current stale audit
-
-The current stale audit run produced:
-
-- `91` units
-- average `3.26` required lenses per unit
-- `333` audit tasks total
-- `294` regular unit-lens tasks
-- `10` large-file split tasks
-- `29` flow tasks
-
-That fan-out is consistent with the current unit-first planner, not with the intended lens-block dispatch model.
-
-## Refactor goals
-
-The next implementation pass should do the following.
-
-### A. Make the slash-command orchestrator the review dispatcher
-
-The `agent` executor should represent review work owned by the current
-conversation or host agent session, with semantic review delegated to bounded
-subagents whenever possible.
-
-Target behavior:
-
-- normal `/audit-code` usage does not require `provider: "claude-code"` or `provider: "opencode"`
-- session-config should not be the normal way to choose a second LLM for review
-- backend provider bridges remain available only for explicit fallback workflows
-- when subagents are unavailable, one invocation performs at most one semantic
-  review task before stopping
-
-### B. Plan review work at the file/lens level
-
-Coverage should still know which files require which lenses, but dispatch planning should work from unresolved `(file, lens)` obligations rather than from unit-wide lens unions.
-
-Target behavior:
-
-- each review block should have explicit `file_paths`
-- each review block should represent one lens
-- review blocks in the same dispatch wave should be file-disjoint unless overlap is intentionally justified
-
-### C. Partition pending review into non-overlapping blocks
-
-Replace the current unit-first task planner with a lens-aware block planner.
-
-Target behavior:
-
-- no combinatorial `unit x lens` explosion unless that is genuinely the smallest valid partition
-- large-file splitting may remain, but it should happen inside the lens-block planner
-- critical-flow context should influence block construction without blindly adding overlapping tasks on top
-
-### D. Keep result ingestion deterministic
-
-The current ingestion model is mostly sound and should be preserved.
-
-Relevant files:
-
-- [src/orchestrator/resultIngestion.ts](/C:/Code/auditor-lambda/src/orchestrator/resultIngestion.ts)
-- [src/coverage.ts](/C:/Code/auditor-lambda/src/coverage.ts:42)
-
-### E. Reframe session-config as backend fallback only
-
-`session-config.json` should continue to configure backend fallback bridges, but it should not be treated as the owner of semantic-review orchestration in the canonical workflow.
-
-`parallel_workers` should either:
-
-- become a legacy fallback-only knob, or
-- be removed from the semantic-review mental model entirely
-
-## Acceptance criteria
-
-The refactor should be treated as done only when all of the following are true.
-
-- Starting `/audit-code` in a conversation does not rely on an external `claude-code` or `opencode` subprocess to own semantic review.
-- The slash-command orchestrator dispatches bounded subagents when available and
-  falls back to one semantic review task per invocation otherwise.
-- The backend fallback still supports deterministic stages and explicit compatibility bridges.
-- The default dispatch granularity for semantic review remains one review block per task.
-- Pending review tasks are planned as lens-aware, non-overlapping file blocks.
-- `parallel_workers` no longer defines the default semantic-review parallelism model.
-- The next fresh audit can be run from a clean slate without inheriting the current stale provider-mediated task queue.
-
-## Suggested implementation order
-
-1. Refactor the review-ownership model in [src/cli.ts](/C:/Code/auditor-lambda/src/cli.ts), [src/providers/index.ts](/C:/Code/auditor-lambda/src/providers/index.ts), and related supervisor docs.
-2. Replace the current task planner in [src/orchestrator/taskBuilder.ts](/C:/Code/auditor-lambda/src/orchestrator/taskBuilder.ts) with a lens-block planner.
-3. Rework flow-aware planning in [src/orchestrator/flowPlanning.ts](/C:/Code/auditor-lambda/src/orchestrator/flowPlanning.ts) so it participates in block construction instead of layering overlapping tasks afterward.
-4. Update docs and tests.
-5. Delete the stale audit state and rerun the audit from scratch.
-
-## Clean rerun after refactor
-
-Once the refactor is in place, the next context should:
-
-1. keep the source changes and documentation already in the worktree
-2. delete `.audit-artifacts/`
-3. delete `audit-report.md`
-4. run the workflow again from a clean state
-5. treat the new audit output as authoritative
-
-For the remediation baseline that should survive the stale audit reset, see [docs/remediation-baseline.md](/C:/Code/auditor-lambda/docs/remediation-baseline.md).
+   fallback review task and stops so `/audit-code` can be rerun from fresh
+   context.
+4. Backend provider adapters remain explicit compatibility bridges, not the
+   default semantic-review owner.
+
+Session config remains backend fallback configuration. It should not be treated
+as the normal way to redirect semantic review into a second external LLM.
+
+## Implemented Changes
+
+The refactor now includes:
+
+- deterministic `review_packets.json` derived from current `AuditTask` records
+- `audit_plan_metrics.json` with packet counts, repeated reference estimates,
+  largest packet details, and estimated agent reduction
+- 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 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, including swapped result files
+- compact `prepare-dispatch` and `merge-and-ingest` JSON envelopes
+- terse worker completion convention:
+  `valid: <packet_id>, findings=<n>`
+- selective deepening for high-severity, low-confidence, conflicting,
+  high-risk clean, and runtime-disagreement cases
+- refreshed packet metrics whenever selective deepening adds follow-up tasks
+
+## Dispatch Contract
+
+`prepare-dispatch` writes a small `dispatch-plan.json`. Each entry points to a
+packet prompt under the run-scoped `task-results/` directory.
+
+The conversation orchestrator should:
+
+- read only `dispatch-plan.json`
+- launch one subagent per packet entry
+- tell the subagent to read and follow `entry.prompt_path`
+- wait for terse success replies
+- run `merge-and-ingest`
+
+The parent should not read source files, prompt bodies, result payloads, or
+large task manifests during the normal packet route.
+
+## Artifacts
+
+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
+
+The existing coverage, runtime validation, requeue, and synthesis artifacts
+remain backend-owned.
+
+## Verification
+
+Current in-repo verification:
+
+- `npm test` passes with 148 tests.
+
+Relevant test coverage:
+
+- packet construction and metrics
+- packet ordering
+- graph-connected packet merging
+- tiny test-file batching
+- packet prompt generation
+- 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
+
+## Remaining Follow-Up
+
+The main remaining work is operational, not structural:
+
+- run `/audit-code` against at least one nontrivial external repository and
+  compare packet counts, warning counts, worker completion summaries, and
+  observed token/quota behavior against the legacy baseline
+- keep host-specific smoke testing current for Codex, Claude Desktop, OpenCode,
+  VS Code, and Antigravity guidance
+
+For the detailed packet dispatch reference, see
+`docs/dispatch-implementation-plan.md`.

package/package.json

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

package/schemas/finding.schema.json

@@ -17,21 +17,7 @@
   "properties": {
     "id": { "type": "string" },
     "title": { "type": "string" },
-    "category": {
-      "type": "string",
-      "enum": [
-        "correctness",
-        "architecture",
-        "maintainability",
-        "security",
-        "reliability",
-        "performance",
-        "data_integrity",
-        "tests",
-        "operability",
-        "config_deployment"
-      ]
-    },
+    "category": { "type": "string", "minLength": 1 },
     "severity": {
       "type": "string",
       "enum": ["critical", "high", "medium", "low", "info"]

package/schemas/graph_bundle.schema.json

@@ -40,6 +40,22 @@
             "additionalProperties": false
           }
         },
+        "references": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["from", "to"],
+            "properties": {
+              "from": { "type": "string" },
+              "to": { "type": "string" },
+              "kind": {
+                "type": "string",
+                "description": "Reference edge kind from literal or path-oriented extraction (e.g. 'relative-string-reference', 'repo-path-reference')."
+              }
+            },
+            "additionalProperties": false
+          }
+        },
         "routes": {
           "type": "array",
           "items": {

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,19 @@ 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 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: