auditor-lambda 0.2.8 → 0.2.9

package/docs/workflow-refactor-brief.md

@@ -0,0 +1,177 @@
+# Workflow Refactor Brief
+
+This document is the handoff for the next context window.
+
+Use it as the source of truth for the workflow refactor before running a fresh audit again.
+
+## Why this refactor is needed
+
+The current implementation still advances deterministic audit state correctly, but the semantic-review phase has drifted away from the intended product behavior.
+
+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`.
+
+That is not the intended workflow.
+
+## Intended workflow
+
+The intended `/audit-code` workflow is:
+
+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.
+
+## 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 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).

package/package.json

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

package/schemas/audit_result.schema.json

@@ -20,7 +20,10 @@
     "task_id": { "type": "string" },
     "unit_id": { "type": "string" },
     "pass_id": { "type": "string" },
-    "lens": { "type": "string" },
+    "lens": {
+      "type": "string",
+      "enum": ["correctness", "architecture", "maintainability", "security", "reliability", "performance", "data_integrity", "tests", "operability", "config_deployment"]
+    },
     "agent_role": { "type": "string" },
     "file_coverage": {
       "type": "array",

package/schemas/audit_task.schema.json

@@ -21,6 +21,7 @@
     },
     "file_paths": {
       "type": "array",
+      "minItems": 1,
       "items": { "type": "string" }
     },
     "line_ranges": {
@@ -44,7 +45,7 @@
         "mechanical_results_ref": { "type": "string" },
         "risk_register_ref": { "type": "string" }
       },
-      "additionalProperties": true
+      "additionalProperties": { "type": "string" }
     },
     "rationale": { "type": "string" },
     "priority": {
@@ -53,6 +54,7 @@
     },
     "tags": {
       "type": "array",
+      "minItems": 1,
       "items": { "type": "string" }
     },
     "status": {

package/schemas/coverage_matrix.schema.json

@@ -9,7 +9,7 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["path", "classification_status", "audit_status"],
+        "required": ["path", "unit_ids", "classification_status", "audit_status", "required_lenses", "completed_lenses"],
         "properties": {
           "path": { "type": "string" },
           "unit_ids": {
@@ -39,9 +39,9 @@
             }
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/critical_flows.schema.json

@@ -31,11 +31,15 @@
           "notes": {
             "type": "array",
             "items": { "type": "string" }
+          },
+          "confidence": {
+            "type": "string",
+            "enum": ["high", "low"]
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/file_disposition.schema.json

@@ -25,9 +25,9 @@
           },
           "reason": { "type": "string" }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/finding.schema.json

@@ -11,7 +11,8 @@
     "confidence",
     "lens",
     "affected_files",
-    "summary"
+    "summary",
+    "evidence"
   ],
   "properties": {
     "id": { "type": "string" },
@@ -54,13 +55,14 @@
     "summary": { "type": "string" },
     "affected_files": {
       "type": "array",
+      "minItems": 1,
       "items": {
         "type": "object",
         "required": ["path"],
         "properties": {
           "path": { "type": "string" },
-          "line_start": { "type": "integer" },
-          "line_end": { "type": "integer" },
+          "line_start": { "type": "integer", "minimum": 1 },
+          "line_end": { "type": "integer", "minimum": 1 },
           "symbol": { "type": "string" }
         },
         "additionalProperties": false
@@ -70,17 +72,20 @@
     "likelihood": { "type": "string" },
     "evidence": {
       "type": "array",
+      "minItems": 1,
       "items": { "type": "string" }
     },
     "reproduction": {
       "type": "array",
+      "minItems": 1,
       "items": { "type": "string" }
     },
     "systemic": { "type": "boolean" },
     "related_findings": {
       "type": "array",
+      "minItems": 1,
       "items": { "type": "string" }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/flow_coverage.schema.json

@@ -45,9 +45,9 @@
             "items": { "type": "string" }
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/repo_manifest.schema.json

@@ -13,7 +13,7 @@
         "root": { "type": "string" },
         "default_branch": { "type": "string" }
       },
-      "additionalProperties": true
+      "additionalProperties": false
     },
     "generated_at": { "type": "string" },
     "files": {
@@ -24,14 +24,14 @@
         "properties": {
           "path": { "type": "string" },
           "language": { "type": "string" },
-          "size_bytes": { "type": "integer" },
+          "size_bytes": { "type": "integer", "minimum": 0 },
           "hash": { "type": "string" },
           "excluded": { "type": "boolean" },
           "exclusion_reason": { "type": "string" }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/risk_register.schema.json

@@ -26,9 +26,9 @@
             "items": { "type": "string" }
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/runtime_validation_report.schema.json

@@ -26,9 +26,9 @@
             "items": { "type": "string" }
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/runtime_validation_tasks.schema.json

@@ -18,10 +18,16 @@
           },
           "target_paths": {
             "type": "array",
+            "minItems": 1,
             "items": { "type": "string" }
           },
           "reason": { "type": "string" },
           "priority": { "type": "string", "enum": ["high", "medium", "low"] },
+          "command": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" }
+          },
           "suggested_checks": {
             "type": "array",
             "items": { "type": "string" }
@@ -31,9 +37,9 @@
             "items": { "type": "string" }
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/surface_manifest.schema.json

@@ -17,7 +17,10 @@
             "enum": ["interface", "background"]
           },
           "entrypoint": { "type": "string" },
-          "exposure": { "type": "string" },
+          "exposure": {
+            "type": "string",
+            "enum": ["network", "local"]
+          },
           "methods": {
             "type": "array",
             "items": { "type": "string" }
@@ -27,9 +30,9 @@
             "items": { "type": "string" }
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/schemas/unit_manifest.schema.json

@@ -25,6 +25,7 @@
           },
           "required_lenses": {
             "type": "array",
+            "minItems": 1,
             "items": {
               "type": "string",
               "enum": ["correctness", "architecture", "maintainability", "security", "reliability", "performance", "data_integrity", "tests", "operability", "config_deployment"]
@@ -35,9 +36,9 @@
             "items": { "type": "string" }
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }

package/skills/audit-code/SKILL.md

@@ -17,6 +17,9 @@ 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.
+
 Bounded steps are a backend implementation detail, not the intended user experience.
 
 ## Embedded Prompt Payload
@@ -58,6 +61,8 @@ For repo-local backend usage:
 - `provider: "auto"` is the explicit opt-in best-effort routing mode
 - explicit provider names remain available when an operator wants a specific backend
 
+Those explicit provider names are backend compatibility bridges, not the intended default review owner.
+
 ## Development rule
 
 Prefer the skill-first conversational contract over the CLI-first backend shape.