auditor-lambda 0.2.8 → 0.2.9

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

package/docs/remediation-baseline.md

@@ -0,0 +1,75 @@
+# Remediation Baseline
+
+This document preserves the remediation work that is already in the source tree so the stale audit state can be discarded safely before a fresh rerun.
+
+## Safe reset boundary
+
+After reviewing this document and [docs/workflow-refactor-brief.md](/C:/Code/auditor-lambda/docs/workflow-refactor-brief.md), it is safe to delete:
+
+- `.audit-artifacts/`
+- `audit-report.md`
+
+Those files describe a stale audit run and should not be used as the primary workflow driver for the next implementation pass.
+
+The source tree and tests are the durable baseline to keep.
+
+## Remediation already landed in the source tree
+
+The current worktree already includes substantial remediation across the main audited areas.
+
+- Fixtures and workflows were hardened across `tests/fixtures/simple-app/...`, `.github/workflows/...`, `scripts/smoke-linked-audit-code.mjs`, `scripts/smoke-packaged-audit-code.mjs`, and the related release/operator docs.
+- Extractor path handling and classification behavior were tightened in `src/extractors/...` with dedicated regressions in `tests/extractors-remediation.test.mjs`.
+- Schema-contract and validation coverage were improved across `schemas/...`, `tests/helpers/jsonSchemaAssert.mjs`, `src/validation/...`, `tests/schema-contracts.test.mjs`, and `tests/validation-remediation.test.mjs`.
+- Orchestrator behavior was hardened in `src/orchestrator/...` with focused regressions in `tests/orchestrator-remediation.test.mjs` and `tests/orchestration.test.mjs`.
+- Supervisor and provider behavior were improved in `src/supervisor/...`, `src/providers/...`, and their companion tests.
+- CLI and IO behavior were tightened in `src/cli.ts`, `src/index.ts`, `src/io/...`, and the related remediation tests.
+- Reporting and synthesis behavior were improved in `src/reporting/...` with `tests/reporting-remediation.test.mjs`.
+- The generated repo-local install payload was refreshed so `.audit-code/install/claude-desktop/...` now matches the current `dist/`, `schemas/`, and `skills/audit-code` source of truth, and `.audit-code/install/manifest.json` now points `source_prompt_path` at the repo-local prompt asset instead of a machine-specific global npm path.
+
+## Verification already performed
+
+The following verification was already recorded against the current remediation tree.
+
+- `npm test` passed on 2026-04-22 with 106 passing tests.
+- `npm run build` passed in the targeted remediation passes below.
+- `node --test --test-isolation=none tests/validation-remediation.test.mjs tests/validate-command.test.mjs tests/field-trial-remediation.test.mjs tests/provider-auto-resolution.test.mjs tests/supervisor-remediation.test.mjs` passed.
+- `node --test --test-isolation=none tests/cli-remediation.test.mjs tests/validate-command.test.mjs` passed.
+- `node --test --test-isolation=none tests/extractors-remediation.test.mjs` passed.
+- `node --test --test-isolation=none tests/io-remediation.test.mjs tests/cli-remediation.test.mjs tests/validate-command.test.mjs tests/staleness.test.mjs` passed.
+- `node --test --test-isolation=none tests/adapters-remediation.test.mjs tests/reporting-remediation.test.mjs tests/field-trial-remediation.test.mjs` passed.
+- `node --test --test-isolation=none tests/orchestration.test.mjs tests/orchestrator-remediation.test.mjs tests/reporting-remediation.test.mjs` passed.
+- The manually repaired install payload now has hash parity between the committed Claude Desktop bundle and the canonical repo `dist/`, `schemas/`, and `skills/audit-code` files.
+
+## Environment limits observed during verification
+
+The current sandbox still hits `spawn EPERM` for subprocess-heavy wrapper/provider coverage.
+
+That means:
+
+- broader wrapper/provider integration checks remain environment-limited here
+- the stale audit rerun should not be treated as authoritative
+- the workflow refactor should be completed before a fresh audit is attempted
+
+## Release status
+
+Do not cut a release tag, push a release branch, or publish from the current stale audit state.
+
+The correct order is:
+
+1. preserve the source changes already made
+2. refactor the workflow
+3. delete the stale audit state
+4. rerun the audit from a clean slate
+5. only then decide whether a release is ready
+
+## Fresh rerun checklist
+
+When the workflow refactor is complete, the next context should:
+
+1. keep the current source and doc changes
+2. delete `.audit-artifacts/`
+3. delete `audit-report.md`
+4. run `npm run build`
+5. run the most relevant regression tests for the refactor
+6. start a fresh `/audit-code` run
+7. treat the new audit output as the release gate

package/docs/run-flow.md

@@ -4,20 +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.
 
-## Current backend execution path
+## Intended review-dispatch path
 
 1. Build or import a repository manifest.
-2. Build audit units from the repository manifest.
-3. Initialize a coverage matrix from the file list.
-4. Apply unit-to-file coverage requirements.
-5. Build initial audit tasks.
-6. Dispatch those tasks to LLM agents or other runtimes.
+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. Apply reviewed ranges and completed lenses to the coverage matrix.
-9. Build requeue tasks for missing lenses or uncovered ranges.
+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).
+
 ## Current backend capability
 
 The current TypeScript implementation already covers:
@@ -27,23 +36,26 @@ The current TypeScript implementation already covers:
 - reviewed-range ingestion from audit results
 - runtime validation update ingestion
 - synthesis and completion tracking
-- backend provider handoff for interactive or assisted review
+- backend provider handoff for fallback or compatibility review flows
 
 ## Product interpretation
 
 - 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
 - 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:
 
-- reducing operator friction when the backend reaches a blocked handoff
-- improving continuation when interactive providers are configured
+- 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`
 - `docs/next-steps.md`

package/docs/session-config.md

@@ -1,9 +1,14 @@
 # session-config
 
-This file only applies to the backend fallback CLI.
+This file only applies to explicit backend fallback workflows.
 
 The canonical `/audit-code` conversation route should not require users to touch it.
 
+It does not define who owns semantic review in the canonical conversation flow, and it is not enough by itself to transfer semantic review away from the active conversation agent.
+
+In the intended product workflow, the active conversation agent owns review tasks and any subagent fan-out.
+Use this file only when you intentionally need backend fallback behavior or an explicit compatibility bridge.
+
 Backend provider configuration lives at:
 
 ```text
@@ -35,8 +40,7 @@ audit-code validate
   "provider": "local-subprocess",
   "timeout_ms": 1800000,
   "ui_mode": "headless",
-  "agent_task_batch_size": 4,
-  "parallel_workers": 2
+  "agent_task_batch_size": 1
 }
 ```
 
@@ -51,6 +55,12 @@ Supported values:
 - `opencode`
 - `vscode-task`
 
+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
+
 ### `timeout_ms`
 
 Worker-run timeout in milliseconds.
@@ -70,10 +80,16 @@ 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.
+
 ### `parallel_workers`
 
 How many provider-assisted review batches to launch in parallel when the selected provider supports it.
 
+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.
+
 ## Auto provider mode
 
 `auto` is an explicit opt-in mode.
@@ -98,6 +114,8 @@ No extra config is required.
 
 This mode covers deterministic worker runs locally and stops in a terminal blocked state once the remaining work requires imported audit results or an interactive provider.
 
+This remains the safest fallback default while the semantic-review workflow is being realigned.
+
 ### `claude_code`
 
 ```json
@@ -116,7 +134,9 @@ Fields:
 - `command`: optional override for the Claude Code executable
 - `extra_args`: optional extra arguments appended before the built-in permission-skipping flag
 
-When audit-task review is pending, the generated provider prompt now asks Claude Code to write structured `AuditResult[]` output and then run the bounded worker command so the same `audit-code` invocation can keep advancing.
+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`.
 
 ### `opencode`
 
@@ -136,7 +156,9 @@ Fields:
 - `command`: optional override for the OpenCode executable
 - `extra_args`: optional additional arguments for `opencode run ...`
 
-When audit-task review is pending, the generated provider prompt now asks OpenCode to write structured `AuditResult[]` output and then run the bounded worker command so the same `audit-code` invocation can keep advancing.
+Current implementation support only.
+
+Use this only when you intentionally want the backend fallback CLI to bridge review into an external OpenCode process, together with `audit-code --provider opencode`.
 
 ### `subprocess_template`
 
@@ -157,6 +179,7 @@ Fields:
 - `env`: optional environment-variable overlay
 
 When you use this bridge for provider-assisted review, the launched process should write structured audit results to `task.audit_results_path` and then execute `task.worker_command`.
+Activate it explicitly with `audit-code --provider subprocess-template`.
 
 ### `vscode_task`
 
@@ -172,6 +195,7 @@ When you use this bridge for provider-assisted review, the launched process shou
 ```
 
 This adapter is intentionally thin. It uses the same template expansion model as `subprocess-template`, but is named separately so the operator intent is explicit.
+Activate it explicitly with `audit-code --provider vscode-task`.
 
 ## Template placeholders
 
@@ -215,6 +239,9 @@ This adapter is intentionally thin. It uses the same template expansion model as
 }
 ```
 
+Use this only when you intentionally want backend fallback routing.
+It is not the canonical semantic-review path.
+
 ### Delegate worker runs into Claude Code
 
 ```json
@@ -224,6 +251,12 @@ This adapter is intentionally thin. It uses the same template expansion model as
 }
 ```
 
+Then start the backend bridge explicitly:
+
+```bash
+audit-code --provider claude-code
+```
+
 ### Delegate worker runs into OpenCode
 
 ```json
@@ -233,6 +266,12 @@ This adapter is intentionally thin. It uses the same template expansion model as
 }
 ```
 
+Then start the backend bridge explicitly:
+
+```bash
+audit-code --provider opencode
+```
+
 ### Use a generic bash launcher bridge
 
 ```json
@@ -245,6 +284,12 @@ This adapter is intentionally thin. It uses the same template expansion model as
 }
 ```
 
+Then start the backend bridge explicitly:
+
+```bash
+audit-code --provider subprocess-template
+```
+
 ## Antigravity note
 
 A dedicated Antigravity adapter is not currently shipped.

package/docs/supervisor.md

@@ -6,6 +6,9 @@ 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.
+
 ## Repo-local backend surface
 
 From the target repository root:
@@ -55,6 +58,9 @@ 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 keeps semantic review with the active conversation agent and uses `local-subprocess` only for deterministic worker steps.
+
 ## Auto resolution rule
 
 When `provider` is set to `auto`, the backend resolves in this order:
@@ -81,3 +87,4 @@ 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.