auditor-lambda 0.2.8 → 0.2.10

package/dist/validation/artifacts.js

@@ -1,6 +1,9 @@
-import { requireKeys } from "./basic.js";
+import { pushValidationIssue, requireKeys, } from "./basic.js";
 function pushIssue(issues, path, message) {
-    issues.push({ path, message });
+    pushValidationIssue(issues, path, message);
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
 }
 export function validateArtifactBundle(bundle) {
     const issues = [];
@@ -37,14 +40,24 @@ export function validateArtifactBundle(bundle) {
     if (bundle.external_analyzer_results) {
         issues.push(...requireKeys(bundle.external_analyzer_results, "external_analyzer_results", ["tool", "results"]));
     }
-    const repoPaths = new Set(bundle.repo_manifest?.files.map((file) => file.path) ?? []);
-    const dispositionMap = new Map(bundle.file_disposition?.files.map((item) => [item.path, item.status]) ??
-        []);
-    const unitIds = new Set(bundle.unit_manifest?.units.map((unit) => unit.unit_id) ?? []);
-    const flowIds = new Set(bundle.critical_flows?.flows.map((flow) => flow.id) ?? []);
-    const runtimeTaskIds = new Set(bundle.runtime_validation_tasks?.tasks.map((task) => task.id) ?? []);
+    const repoManifestFiles = asArray(bundle.repo_manifest?.files);
+    const fileDispositionEntries = asArray(bundle.file_disposition?.files);
+    const unitManifestUnits = asArray(bundle.unit_manifest?.units);
+    const criticalFlows = asArray(bundle.critical_flows?.flows);
+    const flowCoverageEntries = asArray(bundle.flow_coverage?.flows);
+    const riskRegisterItems = asArray(bundle.risk_register?.items);
+    const surfaceEntries = asArray(bundle.surface_manifest?.surfaces);
+    const runtimeValidationTasks = asArray(bundle.runtime_validation_tasks?.tasks);
+    const runtimeValidationResults = asArray(bundle.runtime_validation_report?.results);
+    const externalAnalyzerResults = asArray(bundle.external_analyzer_results?.results);
+    const coverageFiles = asArray(bundle.coverage_matrix?.files);
+    const repoPaths = new Set(repoManifestFiles.map((file) => file.path));
+    const dispositionMap = new Map(fileDispositionEntries.map((item) => [item.path, item.status]));
+    const unitIds = new Set(unitManifestUnits.map((unit) => unit.unit_id));
+    const flowIds = new Set(criticalFlows.map((flow) => flow.id));
+    const runtimeTaskIds = new Set(runtimeValidationTasks.map((task) => task.id));
     if (bundle.repo_manifest && bundle.coverage_matrix) {
-        const coveragePaths = new Set(bundle.coverage_matrix.files.map((file) => file.path));
+        const coveragePaths = new Set(coverageFiles.map((file) => file.path));
         for (const path of repoPaths) {
             if (!coveragePaths.has(path)) {
                 pushIssue(issues, "coverage_matrix", `Missing coverage entry for ${path}`);
@@ -52,7 +65,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.repo_manifest && bundle.file_disposition) {
-        const dispositionPaths = new Set(bundle.file_disposition.files.map((file) => file.path));
+        const dispositionPaths = new Set(fileDispositionEntries.map((file) => file.path));
         for (const path of repoPaths) {
             if (!dispositionPaths.has(path)) {
                 pushIssue(issues, "file_disposition", `Missing disposition entry for ${path}`);
@@ -60,7 +73,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.unit_manifest) {
-        for (const unit of bundle.unit_manifest.units) {
+        for (const unit of unitManifestUnits) {
             if (unit.files.length === 0) {
                 pushIssue(issues, `unit_manifest:${unit.unit_id}`, "Unit has no files");
             }
@@ -79,7 +92,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.coverage_matrix && bundle.unit_manifest) {
-        for (const file of bundle.coverage_matrix.files) {
+        for (const file of coverageFiles) {
             if (!repoPaths.has(file.path)) {
                 pushIssue(issues, "coverage_matrix", `Coverage contains unknown file ${file.path}`);
             }
@@ -103,7 +116,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.critical_flows) {
-        for (const flow of bundle.critical_flows.flows) {
+        for (const flow of criticalFlows) {
             if (flow.paths.length === 0) {
                 pushIssue(issues, `critical_flows:${flow.id}`, "Flow has no paths");
             }
@@ -122,7 +135,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.flow_coverage && bundle.critical_flows) {
-        for (const flow of bundle.flow_coverage.flows) {
+        for (const flow of flowCoverageEntries) {
             if (!flowIds.has(flow.flow_id)) {
                 pushIssue(issues, `flow_coverage:${flow.flow_id}`, `Flow coverage references unknown flow ${flow.flow_id}`);
             }
@@ -143,15 +156,15 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.risk_register && bundle.unit_manifest) {
-        const riskUnitIds = new Set(bundle.risk_register.items.map((item) => item.unit_id));
-        for (const unit of bundle.unit_manifest.units) {
+        const riskUnitIds = new Set(riskRegisterItems.map((item) => item.unit_id));
+        for (const unit of unitManifestUnits) {
             if (!riskUnitIds.has(unit.unit_id)) {
                 pushIssue(issues, "risk_register", `Missing risk entry for unit ${unit.unit_id}`);
             }
         }
     }
     if (bundle.surface_manifest) {
-        for (const surface of bundle.surface_manifest.surfaces) {
+        for (const surface of surfaceEntries) {
             if (!repoPaths.has(surface.entrypoint)) {
                 pushIssue(issues, `surface_manifest:${surface.id}`, `Surface references unknown entrypoint ${surface.entrypoint}`);
             }
@@ -162,7 +175,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.runtime_validation_tasks) {
-        for (const task of bundle.runtime_validation_tasks.tasks) {
+        for (const task of runtimeValidationTasks) {
             if (task.target_paths.length === 0) {
                 pushIssue(issues, `runtime_validation_tasks:${task.id}`, "Runtime validation task has no target paths");
             }
@@ -174,14 +187,14 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.runtime_validation_report) {
-        for (const result of bundle.runtime_validation_report.results) {
+        for (const result of runtimeValidationResults) {
             if (!runtimeTaskIds.has(result.task_id)) {
                 pushIssue(issues, `runtime_validation_report:${result.task_id}`, `Runtime validation result references unknown task ${result.task_id}`);
             }
         }
     }
     if (bundle.external_analyzer_results) {
-        for (const item of bundle.external_analyzer_results.results) {
+        for (const item of externalAnalyzerResults) {
             if (!repoPaths.has(item.path) && bundle.repo_manifest) {
                 pushIssue(issues, `external_analyzer_results:${item.id}`, `External analyzer result references unknown path ${item.path}`);
             }

package/dist/validation/auditResults.d.ts

@@ -1,11 +1,11 @@
 import type { AuditTask } from "../types.js";
+import { type ValidationIssue } from "./basic.js";
 export type IssueSeverity = "error" | "warning";
-export interface AuditResultIssue {
+export interface AuditResultIssue extends ValidationIssue {
     result_index: number;
     task_id: string;
     severity: IssueSeverity;
     field: string;
-    message: string;
 }
 export interface ValidateAuditResultOptions {
     lineIndex?: Record<string, number>;

package/dist/validation/auditResults.js

@@ -1,3 +1,4 @@
+import { describeValue, formatValidationIssues, isRecord, } from "./basic.js";
 const REQUIRED_FINDING_FIELDS = [
     "id",
     "title",
@@ -24,21 +25,10 @@ const VALID_LENSES = new Set([
 function pushIssue(issues, params) {
     issues.push({
         ...params,
+        path: params.path ?? params.field,
         severity: params.severity ?? "error",
     });
 }
-function describeValue(value) {
-    if (Array.isArray(value)) {
-        return "array";
-    }
-    if (value === null) {
-        return "null";
-    }
-    return typeof value;
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
@@ -404,7 +394,9 @@ export function validateAuditResults(results, tasks, options = {}) {
     return issues;
 }
 export function formatAuditResultIssues(issues) {
-    return issues
-        .map((issue) => `  [${issue.severity}] ${issue.task_id} / ${issue.field}: ${issue.message}`)
-        .join("\n");
+    return formatValidationIssues(issues.map((issue) => ({
+        path: `${issue.task_id} / ${issue.field}`,
+        message: issue.message,
+        severity: issue.severity,
+    })));
 }

package/dist/validation/basic.d.ts

@@ -1,5 +1,13 @@
+export type ValidationSeverity = "error" | "warning";
 export interface ValidationIssue {
     path: string;
     message: string;
+    severity: ValidationSeverity;
 }
-export declare function requireKeys(record: Record<string, unknown>, path: string, keys: string[]): ValidationIssue[];
+export declare function describeValue(value: unknown): string;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function createValidationIssue(path: string, message: string, severity?: ValidationSeverity): ValidationIssue;
+export declare function pushValidationIssue(issues: ValidationIssue[], path: string, message: string, severity?: ValidationSeverity): void;
+export declare function prefixValidationIssues(prefix: string, issues: ValidationIssue[]): ValidationIssue[];
+export declare function formatValidationIssues(issues: ValidationIssue[]): string;
+export declare function requireKeys(value: unknown, path: string, keys: readonly string[]): ValidationIssue[];

package/dist/validation/basic.js

@@ -1,8 +1,45 @@
-export function requireKeys(record, path, keys) {
+export function describeValue(value) {
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (value === null) {
+        return "null";
+    }
+    return typeof value;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function createValidationIssue(path, message, severity = "error") {
+    return { path, message, severity };
+}
+export function pushValidationIssue(issues, path, message, severity = "error") {
+    issues.push(createValidationIssue(path, message, severity));
+}
+export function prefixValidationIssues(prefix, issues) {
+    return issues.map((issue) => ({
+        ...issue,
+        path: issue.path.length === 0
+            ? prefix
+            : issue.path === prefix || issue.path.startsWith(`${prefix}.`)
+                ? issue.path
+                : `${prefix}.${issue.path}`,
+    }));
+}
+export function formatValidationIssues(issues) {
+    return issues
+        .map((issue) => `  [${issue.severity}] ${issue.path}: ${issue.message}`)
+        .join("\n");
+}
+export function requireKeys(value, path, keys) {
     const issues = [];
+    if (!isRecord(value)) {
+        pushValidationIssue(issues, path, `Expected an object, got ${describeValue(value)}.`);
+        return issues;
+    }
     for (const key of keys) {
-        if (!(key in record)) {
-            issues.push({ path, message: `Missing required key: ${key}` });
+        if (!(key in value)) {
+            pushValidationIssue(issues, path, `Missing required key: ${key}`);
         }
     }
     return issues;

package/dist/validation/sessionConfig.d.ts

@@ -1,6 +1,8 @@
-import type { SessionConfig } from "../types/sessionConfig.js";
-import type { ValidationIssue } from "./basic.js";
+import { type SessionConfig } from "../types/sessionConfig.js";
+import { type ValidationIssue } from "./basic.js";
 export declare function validateSessionConfig(value: unknown): ValidationIssue[];
 export declare function validateConfiguredProviderEnvironment(sessionConfig: SessionConfig, options?: {
     commandExists?: (command: string) => boolean;
+    pathExists?: (commandPath: string) => boolean;
 }): ValidationIssue[];
+export { formatValidationIssues } from "./basic.js";

package/dist/validation/sessionConfig.js

@@ -1,18 +1,11 @@
 import { spawnSync } from "node:child_process";
-const VALID_PROVIDERS = new Set([
-    "auto",
-    "local-subprocess",
-    "subprocess-template",
-    "claude-code",
-    "opencode",
-    "vscode-task",
-]);
-const VALID_UI_MODES = new Set(["headless", "visible"]);
+import { accessSync, constants } from "node:fs";
+import { PROVIDER_NAMES, SESSION_UI_MODES, } from "../types/sessionConfig.js";
+import { isRecord, pushValidationIssue, } from "./basic.js";
+const VALID_PROVIDERS = new Set(PROVIDER_NAMES);
+const VALID_UI_MODES = new Set(SESSION_UI_MODES);
 function pushIssue(issues, path, message) {
-    issues.push({ path, message });
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    pushValidationIssue(issues, path, message);
 }
 function validateStringArray(value, path, label, issues, options = {}) {
     if (!Array.isArray(value)) {
@@ -74,6 +67,9 @@ function validateAgentProviderSection(value, path, issues) {
         if (typeof value.command !== "string" || value.command.trim().length === 0) {
             pushIssue(issues, `${path}.command`, "command must be a non-empty string when provided.");
         }
+        else if (!isSupportedConfiguredCommand(value.command)) {
+            pushIssue(issues, `${path}.command`, "command must be a bare executable name or direct executable path. Put CLI flags in extra_args.");
+        }
     }
     if (value.extra_args !== undefined) {
         validateStringArray(value.extra_args, `${path}.extra_args`, "extra_args", issues, { allowEmptyArray: true });
@@ -84,6 +80,43 @@ function commandExists(command) {
     const result = spawnSync(lookupCommand, [command], { stdio: "ignore" });
     return result.status === 0;
 }
+function configuredPathExists(commandPath) {
+    try {
+        accessSync(commandPath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function startsWithPathPrefix(command) {
+    return (command.startsWith(".") ||
+        command.startsWith("/") ||
+        command.startsWith("\\\\") ||
+        /^[A-Za-z]:[\\/]/.test(command));
+}
+function containsForbiddenCommandSyntax(command) {
+    return /[\r\n"'`|&;<>]/.test(command);
+}
+function isBareExecutableName(command) {
+    return (command.length > 0 &&
+        !/\s/.test(command) &&
+        !containsForbiddenCommandSyntax(command) &&
+        !/[\\/]/.test(command) &&
+        !/^[A-Za-z]:/.test(command));
+}
+function isDirectExecutablePath(command) {
+    return (command.length > 0 &&
+        !containsForbiddenCommandSyntax(command) &&
+        startsWithPathPrefix(command));
+}
+function isSupportedConfiguredCommand(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0 || trimmed !== command) {
+        return false;
+    }
+    return isBareExecutableName(trimmed) || isDirectExecutablePath(trimmed);
+}
 export function validateSessionConfig(value) {
     const issues = [];
     if (value === undefined) {
@@ -122,18 +155,32 @@ export function validateSessionConfig(value) {
 export function validateConfiguredProviderEnvironment(sessionConfig, options = {}) {
     const issues = [];
     const lookupCommand = options.commandExists ?? commandExists;
+    const lookupPath = options.pathExists ?? configuredPathExists;
     const provider = sessionConfig.provider ?? "local-subprocess";
     if (provider === "claude-code") {
         const command = sessionConfig.claude_code?.command ?? "claude";
-        if (!lookupCommand(command)) {
+        if (isBareExecutableName(command) && !lookupCommand(command)) {
             pushIssue(issues, "claude_code.command", `Configured claude-code executable was not found on PATH: ${command}.`);
         }
+        else if (isDirectExecutablePath(command) && !lookupPath(command)) {
+            pushIssue(issues, "claude_code.command", `Configured claude-code executable path does not exist: ${command}.`);
+        }
+        else if (!isSupportedConfiguredCommand(command)) {
+            pushIssue(issues, "claude_code.command", "Configured claude-code command must be a bare executable name or direct path. Put CLI flags in extra_args.");
+        }
     }
     if (provider === "opencode") {
         const command = sessionConfig.opencode?.command ?? "opencode";
-        if (!lookupCommand(command)) {
+        if (isBareExecutableName(command) && !lookupCommand(command)) {
             pushIssue(issues, "opencode.command", `Configured opencode executable was not found on PATH: ${command}.`);
         }
+        else if (isDirectExecutablePath(command) && !lookupPath(command)) {
+            pushIssue(issues, "opencode.command", `Configured opencode executable path does not exist: ${command}.`);
+        }
+        else if (!isSupportedConfiguredCommand(command)) {
+            pushIssue(issues, "opencode.command", "Configured opencode command must be a bare executable name or direct path. Put CLI flags in extra_args.");
+        }
     }
     return issues;
 }
+export { formatValidationIssues } from "./basic.js";

package/docs/agent-integrations.md

@@ -14,6 +14,17 @@ Normal product usage should:
 - avoid manual `--root`, provider flags, and model selection in normal use
 - let the supervisor advance the audit automatically until it completes or no further automatic progress is possible
 
+## Review ownership rule
+
+Semantic review should stay with the active conversation agent by default.
+
+That means:
+
+- use the current host conversation as the normal owner of review work
+- if the host agent can delegate to subagents in parallel, let the host runtime make that decision
+- do not treat `.audit-artifacts/session-config.json` as the normal way to choose a second LLM for review
+- treat backend provider adapters as compatibility bridges for fallback CLI usage only
+
 ## Conversation-first setup
 
 The canonical prompt asset is:
@@ -136,7 +147,11 @@ Terminal interpretation:
 - `audit_state.status === "complete"` means the audit finished end to end.
 - `audit_state.status === "blocked"` means the wrapper exhausted automatic work and the remaining review still needs imported results or a provider-capable continuation path.
 
-When `provider` is configured as `claude-code`, `opencode`, `subprocess-template`, or `vscode-task`, the wrapper can now continue through audit-task review in the same invocation as long as that provider can write structured `AuditResult[]` output and hand control back to the bounded worker command.
+Current implementation note:
+
+- the backend fallback still supports explicit provider bridges such as `claude-code`, `opencode`, `subprocess-template`, and `vscode-task`
+- those bridges are compatibility modes, not the intended default review owner
+- the intended long-term workflow is documented in [docs/workflow-refactor-brief.md](/C:/Code/auditor-lambda/docs/workflow-refactor-brief.md)
 
 When additional evidence exists, pass it into the same wrapper:
 
@@ -149,6 +164,7 @@ audit-code --external-analyzer-results /path/to/external_analyzer_results.json
 Each response also refreshes `.audit-artifacts/operator-handoff.json` and `.audit-artifacts/operator-handoff.md` so operators can see the pending obligations, suggested import paths, and session-config continuation hint without reconstructing the state manually.
 
 Everything below is backend fallback guidance, not the primary product path.
+Use it when the current host cannot keep review inside the active conversation, not as the first choice for semantic-review ownership.
 
 ## Provider matrix
 
@@ -156,9 +172,9 @@ Everything below is backend fallback guidance, not the primary product path.
 
 Use when you want the supervisor to stay entirely local.
 
-This requires no external agent CLI. The supervisor launches fresh worker subprocesses that call the bounded `worker-run` entrypoint for deterministic stages.
+This requires no external agent CLI. Deterministic executors run in-process during normal wrapper runs, and the supervisor only stops once the remaining work is genuinely semantic review.
 
-When the remaining work is genuinely audit-task review, `local-subprocess` stops in a terminal blocked handoff instead of pretending more automatic progress is available.
+When that review boundary is reached, `local-subprocess` stops in a terminal blocked handoff instead of pretending more automatic progress is available. Use `--results <file>` for a single batch or `--batch-results <dir>` when the active conversation agent reviewed multiple task batches before ingestion.
 
 This is the safest default backend when the repository is already available locally.
 
@@ -166,19 +182,17 @@ This is the safest default backend when the repository is already available loca
 
 Use when Claude Code is installed and authenticated on the machine.
 
-The built-in adapter launches a fresh Claude Code print-mode session for each worker run.
-When audit-task review is pending, the provider prompt now asks Claude Code to write structured audit results and then hand back to the bounded worker command so the same wrapper invocation can continue.
+The current implementation can launch a fresh Claude Code print-mode session for each worker run.
 
-Recommended when you want the audit supervisor to delegate bounded tasks into Claude Code without manually driving each step.
+Treat this as a compatibility bridge only, not as the intended default review owner.
 
 ### opencode
 
 Use when OpenCode is installed and authenticated on the machine.
 
-The built-in adapter launches a fresh `opencode run ...` session for each worker run.
-When audit-task review is pending, the provider prompt now asks OpenCode to write structured audit results and then hand back to the bounded worker command so the same wrapper invocation can continue.
+The current implementation can launch a fresh `opencode run ...` session for each worker run.
 
-Recommended when OpenCode is the preferred local agent surface.
+Treat this as a compatibility bridge only, not as the intended default review owner.
 
 ### subprocess-template
 
@@ -195,11 +209,15 @@ Treat this as an advanced backend adapter rather than the default path.
 
 ### Claude Code
 
-Use the repo-local `audit-code` wrapper from the target repository root, or set `provider` to `claude-code` in `.audit-artifacts/session-config.json` so the supervisor delegates bounded worker runs into Claude Code.
+Use `/audit-code` in the active conversation as the primary path.
+
+Only use the repo-local `audit-code` wrapper with `provider: "claude-code"` in `.audit-artifacts/session-config.json` when you intentionally want backend fallback bridging into Claude Code.
 
 ### OpenCode
 
-Use the same repo-local `audit-code` wrapper, or set `provider` to `opencode` so the supervisor delegates bounded worker runs into OpenCode.
+Use `/audit-code` in the active conversation as the primary path.
+
+Only use the repo-local `audit-code` wrapper with `provider: "opencode"` when you intentionally want backend fallback bridging into OpenCode.
 
 ### VS Code
 
@@ -249,3 +267,5 @@ For a polished operator experience today:
 3. use `audit-code` as the repo-local backend fallback
 4. prefer `local-subprocess` unless you want interactive review to continue automatically through agent tasks
 5. use `subprocess-template` only when integrating a non-native editor or launcher surface
+
+If you intentionally want the backend fallback to bridge semantic review into another process, re-run with an explicit `--provider` flag after configuring the matching section in `.audit-artifacts/session-config.json`.

package/docs/next-steps.md

@@ -36,7 +36,24 @@ That means the current release is suitable for a controlled alpha or beta skill-
 
 ## Near-term priorities
 
-### 1. Verify the shipped host integrations end to end
+### 1. Realign review dispatch with the conversation-owned workflow
+
+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.
+
+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
+
+The current handoff for this work is:
+
+- `docs/workflow-refactor-brief.md`
+- `docs/remediation-baseline.md`
+
+### 2. Verify the shipped host integrations end to end
 
 The biggest remaining gap is not raw feature presence anymore. It is host-by-host proof that the generated assets work in the actual products they target.
 
@@ -48,7 +65,7 @@ Near-term work should focus on:
 - validating the VS Code prompt, agent, and `.vscode/mcp.json` flow inside a real workspace
 - validating that the Antigravity planning-mode guidance is accurate and does not over-promise a native saved-workflow surface
 
-### 2. Close the remaining host-native UX gaps
+### 3. Close the remaining host-native UX gaps
 
 The product goal is still conversational first, not fallback-CLI first, and some shipped surfaces are still guidance-heavy rather than truly native.
 
@@ -59,7 +76,7 @@ Near-term work should focus on:
 - deciding whether OpenCode and VS Code need any smaller UX refinements after smoke-testing, rather than assuming the first generated surfaces are final
 - keeping Antigravity framed as a workflow-and-artifacts host until Google documents a stable project-local config surface
 
-### 3. Polish continuation through assisted review
+### 4. Polish continuation through assisted review
 
 The repo-local backend fallback still intentionally stops in blocked state under `local-subprocess`, but configured provider bridges can now continue the audit-task review phase automatically.
 
@@ -69,7 +86,7 @@ Near-term work should focus on:
 - less operator guesswork when a configured provider fails to return usable results
 - stronger host-specific guidance for provider-assisted bridges
 
-### 4. Harden publish and release operations
+### 5. Harden publish and release operations
 
 The packaged install story is in place, but release operations still need finishing work.
 

package/docs/packaging.md

@@ -31,6 +31,18 @@ npm install
 npm run verify:release
 ```
 
+For live child-process output during packaged smoke debugging:
+
+```bash
+AUDIT_CODE_VERBOSE=1 npm run smoke:packaged-audit-code
+```
+
+For the linked-install variant:
+
+```bash
+AUDIT_CODE_VERBOSE=1 npm run smoke:linked-audit-code
+```
+
 That script:
 
 - creates a tarball with `npm pack`
@@ -41,6 +53,8 @@ That script:
 - invokes the installed `audit-code` binary from `node_modules/.bin`
 - validates emitted JSON against `schemas/audit-code-v1alpha1.schema.json`
 - exercises the same evidence-import and completion flow used by the linked-command smoke test
+- strips inherited `npm_config_*`, `NODE_AUTH_TOKEN`, and `NPM_TOKEN` values before nested npm operations so `npm publish --dry-run` does not accidentally suppress tarball generation or leak publish credentials into the smoke environment
+- emits step-by-step progress plus a final success summary so CI logs show where the run failed or completed across both the linked and packaged smoke paths
 
 ## CI
 

package/docs/product-direction.md

@@ -78,11 +78,32 @@ For repo-local backend usage:
 - `provider: "auto"` is the explicit opt-in mode for best-effort routing across configured or detected backends
 - explicit provider names should remain available for operators who want a specific backend
 
+## Semantic review ownership
+
+The intended semantic-review owner is the active conversation agent.
+
+That means:
+
+- `/audit-code` should hand review work to the current conversation or host agent session first
+- if that active agent can delegate to subagents in parallel, that fan-out belongs to the host runtime rather than to repo-local backend defaults
+- backend provider adapters are compatibility bridges for fallback CLI usage, not the default owner of review work
+- session-config should not be the normal mechanism for redirecting semantic review into a second external LLM CLI
+
+## Task-planning rule
+
+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
+
 ## Default context & model rules
 
 1. By default, the current ChatGPT project conversation and its files should be treated as the primary context.
 2. The user should not need to supply `--root`, provider names, or backend-specific settings in normal usage.
 3. For backend CLI delegation, let the chosen provider own its own model-selection behavior unless explicitly configured.
+4. Backend fallback settings should not cap the active conversation agent's own subagent parallelism model.
 
 ## Development rule
 
@@ -92,6 +113,7 @@ Future development should optimize for the native skill UX first:
 - packaged installs should help users reach the prompt asset for that conversation route
 - the CLI and supervisor are implementation details and fallback harnesses
 - provider adapters are backend internals, not the primary product concept
+- semantic-review dispatch belongs to the active conversation agent, not to an externally spawned fallback provider by default
 - docs, tests, and examples should present the skill-first flow before any CLI flow
 
 If documentation or implementation details conflict, prefer the skill-first contract above over the CLI-first backend shape.

package/docs/production-launch-bar.md

@@ -20,6 +20,8 @@ Anything below `dist/index.js` remains a backend or development interface rather
 ### Node and package runtime
 
 - Node `>=20` is the minimum supported runtime from `package.json`
+- GitHub Actions currently exercises the test suite on Node `20` and Node `22`
+- release and publish automation stays pinned to Node `22.14.0`
 - packaged installs must include:
   - `audit-code`
   - `audit-code-wrapper-lib.mjs`

package/docs/releasing.md

@@ -13,7 +13,9 @@ That workflow already:
 - pins Node `22.14.0`
 - upgrades npm to `>=11.5.1`
 - runs `npm run verify:release` before any publish attempt
+- previews the packed tarball with `npm pack --dry-run` before any live publish attempt
 - defaults semver prerelease versions to the `next` dist-tag unless manual dispatch overrides it
+- uploads npm debug logs when a publish-path step fails
 
 ## One-time npm setup
 
@@ -39,6 +41,12 @@ npm publish --dry-run
 
 The local dry run is still valuable even though the real publish happens in GitHub Actions. It proves the packed artifact, lifecycle hooks, and publish metadata before you spend a release on a broken workflow run.
 
+## Supported Node lines
+
+Routine CI currently exercises the repository on Node `20` and Node `22`.
+
+Release and publish workflows stay pinned to Node `22.14.0` because that is the line this repository uses for npm Trusted Publishing and release smoke verification.
+
 ## GitHub release paths
 
 ### Manual dry run
@@ -68,6 +76,15 @@ This is the safest path for the first trusted-publishing release because it lets
 
 After the manual path is proven, publishing a GitHub Release will trigger the same workflow and publish the package.
 
+## Workflow troubleshooting
+
+If a GitHub Actions run fails:
+
+1. download the uploaded `*-npm-logs` artifact from the failed run
+2. rerun `npm ci` and `npm run verify:release` locally from the same commit
+3. for publish failures, rerun `publish-package.yml` with `dry_run=true` before retrying a live publish
+4. if publish still fails, confirm npm Trusted Publishing is still configured for `publish-package.yml`
+
 ## Post-publish checks
 
 After a live publish, verify the result from a clean shell: