auditor-lambda 0.3.2 → 0.3.4

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,27 @@ 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.
+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.
+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 +32,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 +45,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

@@ -80,7 +80,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`
 
@@ -88,7 +91,8 @@ How many provider-assisted review batches to launch in parallel when the selecte
 
 This setting only applies to explicit backend bridge launches.
 
-It should not be treated as the source of truth for in-conversation subagent parallelism, which belongs to the active conversation agent or host runtime.
+It should not be treated as the source of truth for slash-command subagent
+parallelism, which belongs to the host runtime.
 
 ## Auto provider mode
 
@@ -112,7 +116,10 @@ This keeps the current default stable while still allowing best-effort cross-edi
 
 No extra config is required.
 
-This mode covers deterministic audit execution locally and stops in a terminal blocked state once the remaining work requires imported audit results or an interactive provider.
+This mode covers deterministic audit execution locally and stops in a terminal
+blocked state once the remaining work requires semantic review. The
+slash-command orchestrator should then dispatch bounded subagents when the host
+supports them, or complete one assigned task and stop when it does not.
 
 When the active conversation agent reviews multiple task batches before ingestion, prefer `audit-code --batch-results <dir>` over ad hoc artifact edits.
 

package/docs/supervisor.md

@@ -6,8 +6,13 @@ The primary product contract is `/audit-code` in conversation.
 
 Everything here is fallback and implementation detail guidance for the repo-local backend surface.
 
-In the intended workflow, the active conversation agent owns semantic review.
-Provider adapters are compatibility bridges for backend fallback mode, not the default review owner.
+In the intended workflow, the conversation agent owns orchestration and
+ingestion control, but bounded subagents own semantic review whenever the host
+can dispatch them. If subagents are unavailable, the conversation agent reviews
+one assigned task and stops so `/audit-code` can be rerun from fresh context.
+
+Provider adapters are compatibility bridges for backend fallback mode, not the
+default review owner.
 
 ## Repo-local backend surface
 
@@ -59,7 +64,8 @@ audit-code --provider vscode-task
 ```
 
 Those `--provider` invocations are the explicit bridge handoff point.
-Without an explicit `--provider` flag, the backend keeps semantic review with the active conversation agent and uses `local-subprocess` only for deterministic worker steps.
+Without an explicit `--provider` flag, the backend stops at the semantic-review
+boundary and exposes scoped task artifacts for the slash-command orchestrator.
 
 ## Auto resolution rule
 
@@ -87,4 +93,6 @@ See:
 ## Note
 
 Provider adapters are backend integrations, not the primary product concept.
-Session config defines bridge settings, but the explicit `--provider` flag is what opts the backend into owning semantic-review dispatch.
+Session config defines bridge settings. An explicit `provider: "auto"` or
+`--provider` bridge selection is what opts the backend into provider-mediated
+review dispatch.

package/docs/workflow-refactor-brief.md

@@ -1,177 +1,115 @@
-# 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
+- write one validated result file per underlying task
 
-That is not the intended workflow.
+## Current Product Model
 
-## Intended workflow
+The canonical workflow is still conversation-first:
 
-The intended `/audit-code` workflow is:
+1. The active conversation agent owns orchestration and ingestion control.
+2. Bounded subagents own semantic packet review when the host supports them.
+3. If subagents are unavailable, the conversation agent completes one assigned
+   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.
 
-1. The active conversation agent owns semantic review work.
-2. Deterministic planning computes which files need which lenses.
-3. Pending review is partitioned into non-overlapping review blocks, preferably grouped by lens.
-4. One dispatched review task should correspond to one review block.
-5. `agent_task_batch_size` should stay `1` by default.
-6. If the active conversation agent can delegate to subagents in parallel, that fan-out belongs to the host agent runtime, not to the backend session config.
-7. Backend provider adapters are fallback compatibility bridges only. They should not be the default 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.
 
-## Current implementation drift
+## Implemented Changes
 
-The current code differs from that model in several important ways.
+The refactor now includes:
 
-### 1. Review ownership is provider-mediated
+- 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 outputs to one worker
+- validation and merge checks for missing, duplicate, unknown, malformed, or
+  out-of-scope task results
+- 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
 
-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`.
+## Dispatch Contract
 
-Relevant files:
+`prepare-dispatch` writes a small `dispatch-plan.json`. Each entry points to a
+packet prompt under the run-scoped `task-results/` directory.
 
-- [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)
+The conversation orchestrator should:
 
-### 2. Task planning is unit-first, not lens-first
+- 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`
 
-`buildChunkedAuditTasks()` currently creates tasks as `unit x lens`, then optionally splits oversized files into separate per-lens tasks.
+The parent should not read source files, prompt bodies, result payloads, or
+large task manifests during the normal packet route.
 
-Relevant files:
+## Artifacts
 
-- [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)
+Packet mode adds or updates these artifacts:
 
-### 3. Required lenses are unioned at the unit level
+- `review_packets.json`
+- `audit_plan_metrics.json`
+- `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`
+- `<artifacts_dir>/runs/<run_id>/task-results/*.prompt.md`
+- `<artifacts_dir>/runs/<run_id>/task-results/*.json`
+- `<artifacts_dir>/runs/<run_id>/dispatch-warnings.json`, only when needed
 
-The planner derives `required_lenses` for a unit, then applies that whole union to every file in the unit.
+The existing coverage, runtime validation, requeue, and synthesis artifacts
+remain backend-owned.
 
-That means the task count grows with `units x required_lenses`, not with a deliberately partitioned set of file/lens review blocks.
+## Verification
 
-Relevant files:
+Current in-repo verification:
 
-- [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)
+- `npm test` passes with 143 tests.
 
-### 4. Flow augmentation adds overlapping review tasks
+Relevant test coverage:
 
-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.
+- packet construction and metrics
+- packet ordering
+- graph-connected packet merging
+- tiny test-file batching
+- packet prompt generation
+- packet merge compatibility with the legacy result array
+- missing-result blocking
+- path-heuristic regressions
+- graph extraction from source contents
+- selective deepening triggers and packet refresh
 
-Relevant file:
+## Remaining Follow-Up
 
-- [src/orchestrator/flowPlanning.ts](/C:/Code/auditor-lambda/src/orchestrator/flowPlanning.ts:9)
+The main remaining work is operational, not structural:
 
-### 5. `parallel_workers` means subprocess fan-out, not agent-owned parallelism
+- 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
 
-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 active conversation agent the semantic-review owner
-
-The `agent` executor should represent review work owned by the current conversation or host agent session.
-
-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
-
-### 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 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).
+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.2",
+  "version": "0.3.4",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/schemas/audit_results.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "audit_results.schema.json",
+  "title": "Audit Results",
+  "type": "array",
+  "minItems": 1,
+  "items": {
+    "$ref": "audit_result.schema.json"
+  }
+}

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/SKILL.md

@@ -17,8 +17,16 @@ Normal usage should:
 - avoid manual paths, provider flags, and model-selection arguments
 - advance the audit automatically until it completes or no further automatic progress is possible
 
-Semantic review should stay with the active conversation agent by default.
-If the host can delegate to subagents, that fan-out belongs to the host agent runtime rather than to repo-local backend provider settings.
+Semantic review should be delegated to bounded subagents whenever the host can
+dispatch them. The conversation orchestrator owns dispatch and ingestion control;
+it should not perform broad review itself when subagents are available.
+
+If the host cannot delegate to subagents, the conversation orchestrator may
+complete exactly one assigned review task, ingest it through the provided backend
+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.
 
 Bounded steps are a backend implementation detail, not the intended user experience.
 
@@ -66,7 +74,8 @@ audit-code --single-step
 For repo-local backend usage:
 
 - omitted provider remains `local-subprocess`
-- `local-subprocess` should stop cleanly once only manual or provider-assisted review remains
+- `local-subprocess` should stop cleanly once semantic review is needed and
+  expose scoped task artifacts for the slash-command orchestrator
 - `provider: "auto"` is the explicit opt-in best-effort routing mode
 - explicit provider names remain available when an operator wants a specific backend