auditor-lambda 0.3.12 → 0.3.14

package/docs/field-trial-bug-report.md

@@ -1,237 +0,0 @@
-# audit-code Field Trial Bug Report
-
-**Observed by:** LLM workers (Claude, April 2026)  
-**Environments tested:** Claude Desktop (claude-code provider), OpenCode (opencode provider)  
-**Repositories audited:** `Polar-CV-KAN` (~30 source files, ~126 tasks, Claude Desktop); same codebase, OpenCode run  
-**Report date:** 2026-04-21  
-
-Issues marked **[Both]** were independently observed in both environments. Issues marked **[CD]** or **[OC]** were specific to one environment.
-
----
-
-## Critical
-
-### F-01 — Orchestrator never transitions to `status: "complete"` [Both]
-
-**CD observation:** `audit_tasks.json` showed `status: undefined` for all 126 tasks after successful ingestion. The completion gate checks this field, finds it undefined on every task, and permanently blocks. `synthesis_report.json` populated correctly (95 findings, 46 clusters) because synthesis runs on ingestion independently, but `status: "complete"` never fires because the gate only looks at the broken task-status field.
-
-**OC observation:** Even after all obligations reached `satisfied`, `audit_state.json` remained `status: "active"` and re-triggered planning artifacts. Required direct JSON edit to force `status: "complete"`.
-
-**Impact:** The documented stop condition ("stop the loop when terminal output shows `status: complete`") never fires in either environment. Workers must either loop indefinitely or make a judgment call to stop. This is the most fundamental failure in the framework.
-
-**Fix needed:** Audit task status must be written at ingestion time. The completion gate should also fall back on obligation-state truth: if all obligations are `satisfied`, the run is complete regardless of the task-status field.
-
----
-
-### F-02 — Worker launch failures / silent executor failures [Both]
-
-**CD observation:** `structure_executor` failed to launch during initial structuring. The failure was reported in JSON output but the orchestrator continued as if structuring had succeeded. Task quality degraded silently from the start — unclear whether the resulting task plan was the best possible decomposition or a fallback.
-
-**OC observation:** Every executor failed (`agent`, `result_ingestion_executor`, `planning_executor`). The entire audit had to be performed manually by reading source files, writing findings in the correct format, and directly manipulating artifact files. The provider (`opencode`) was supposed to enable interactive dispatch but never actually dispatched work.
-
-**Impact (OC):** The framework served as a state tracker only — no automation at all. **Impact (CD):** Silent quality degradation at the task-planning phase with no way to detect it.
-
-**Fix needed:** Worker launch failures must be surfaced as blocking handoffs, not silently swallowed. The orchestrator must not advance past a failed executor as if it succeeded. Executor failure messages must include enough detail to diagnose the root cause.
-
----
-
-## High
-
-### F-03 — `--results` ingestion is unreliable [Both]
-
-**CD observation:** `audit-code --results <file>` threw `TypeError: e.trim is not a function` when evidence fields contained objects rather than plain strings. The CLI exited 0 in some cases, making it ambiguous whether results were partially or fully ingested.
-
-**OC observation:** Two separate failure modes: (1) the generated task file contained `audit_results_path: "--root"` (the CLI flag was written as the path value) causing an immediate crash; (2) after manually fixing the path, ingestion crashed with `Cannot read properties of undefined (reading 'map')` — the ingestion executor cannot parse the incoming results format.
-
-**Impact:** The primary submission mechanism is unreliable. Workers resort to custom scripts that bypass the framework and will break if the artifact schema changes.
-
-**Fix needed:**
-- Fix the `audit_results_path: "--root"` generation bug in the task file writer.
-- Add schema validation on ingestion that emits field-level errors: `"evidence[2] must be a string, got object"` rather than a bare JS runtime crash.
-- The ingestion executor must not exit 0 on partial failure.
-
----
-
-### F-04 — CLI hangs without output [CD]
-
-On multiple occasions, `audit-code` or `audit-code --results <file>` produced no output and hung indefinitely. No timeout, no error message, no way to distinguish a genuine hang from a slow operation.
-
-**Observed pattern:** Hangs were most frequent immediately after large ingestions and at session start during manifest structuring. Suspected cause: Node.js blocking on large JSON serialization or file locking between the orchestrator writing state and the CLI reading it.
-
-**Fix needed:** Add a timeout (`--timeout <ms>`) and ensure the CLI emits a progress indicator or heartbeat on long operations.
-
----
-
-### F-05 — Requeue tasks explosion — 141 tasks from 10 findings [OC]
-
-After ingesting the first batch of 10 `data_integrity` findings, the orchestrator generated a `requeue_tasks.json` with 141 tasks — more than the original 64 audit tasks. The requeue logic appears to fan out across all `(lens, file_group)` combinations, producing a combinatorial explosion. No guidance is provided on which requeue tasks are actually needed vs. redundant.
-
-**Fix needed:** Requeue logic must de-duplicate against already-completed coverage. Requeue tasks should only be generated for `(file_group, lens)` pairs not already marked complete in `coverage_matrix.json`.
-
----
-
-## Medium
-
-### F-06 — Evidence schema undocumented; validation only at ingestion [Both]
-
-**CD observation:** `evidence[]` must be an array of plain strings. This constraint is documented in `current-prompt.md` but not validated until `--results` ingestion, where failure produces a cryptic JS runtime error with no field-level attribution.
-
-**OC observation:** `evidence` must be an array of objects (`[{excerpt, line_reference}]`), not a single object. Discovered only through the error `"(finding.evidence ?? []) is not iterable"`.
-
-**Note — schema discrepancy:** The two environments reported conflicting evidence types (strings vs. objects). This is itself a documentation or versioning problem — the expected format is not the same across runs, or the prompt changed between environments.
-
-**Fix needed:**
-- Publish a JSON Schema file (or inline schema comment in the prompt) that workers can validate against before submission.
-- The string format should be explicit: `"src/foo.py:42 — variable overwritten before use"`.
-- Reconcile the expected type (string vs object) and pick one; document it prominently.
-
----
-
-### F-07 — `synthesis_current` obligation permanently shows "missing" [Both]
-
-**CD observation:** Even after `synthesis_report.json` was fully populated (95 findings, 46 clusters, 22 work blocks), the obligation tracker showed `synthesis_current: missing` because it was blocked by `audit_tasks_completed` (itself blocked by the undefined-status bug, F-01). The worker cannot distinguish "synthesis truly hasn't run" from "synthesis ran but the gate is broken."
-
-**OC observation:** The obligation was never going to be satisfied by the framework — the synthesis agent never ran. Required manually creating `synthesis_report.json` and forcing the obligation to `satisfied`.
-
-**Fix needed:** Decouple `synthesis_current` satisfaction from `audit_tasks_completed`. If `synthesis_report.json` exists and is non-empty, `synthesis_current` should be satisfied regardless of upstream gate state.
-
----
-
-### F-08 — "All remaining N tasks low priority" — no guidance on what to do [CD]
-
-At a certain point the orchestrator indicated all remaining 110 tasks were low priority. The directive does not define what the worker should do: submit empty findings (what was done), review at reduced depth, or skip entirely. Submitting `findings: []` for 60+ tasks in rapid succession was the only way to unblock the orchestrator, but legitimate low-severity findings in those files were never written.
-
-**Fix needed:** When the orchestrator decides remaining tasks are low priority, emit an explicit directive — e.g., `"You may submit empty findings for these tasks"` or `"Review at reduced depth"` or `"Skip — the audit has sufficient coverage"`.
-
----
-
-### F-09 — Trivially empty files dispatched as full audit tasks [CD]
-
-The task manifest dispatched audit tasks for empty `__init__.py` files (some containing only a docstring), dotfiles (`.gitignore`, `.gitattributes`), and one-line stub files. Each required a full read→write→ingest round-trip to produce an empty `findings: []` result. For 30 files this added ~30–40 pointless round-trips; at scale this is severe.
-
-**Fix needed:** Filter files below a minimum token threshold (or with no parseable code constructs) before dispatching tasks. Batch all trivially-empty files into a single no-op task, or skip them entirely.
-
----
-
-### F-10 — No batch task dispatch; one task per CLI invocation [Both]
-
-**CD observation:** 126 tasks required 252+ CLI invocations plus 126 file reads and writes. The design assumes one task = one LLM call = one CLI round-trip.
-
-**OC observation:** No bulk ingestion mechanism; wrote a custom `scripts/ingest-results.mjs` that directly mutated `audit_results.jsonl`, `coverage_matrix.json`, and `audit_state.json`.
-
-**Fix needed:** Support batched dispatch (a `current-tasks.json` with N tasks per run) and a native `audit-code --batch-results <dir>` that processes all result files in a directory. Alternatively, make `agentBatchSize` settable to a meaningful value that workers actually see in their prompt.
-
----
-
-### F-11 — Coverage matrix ↔ task_id mapping is opaque [OC]
-
-The relationship between `audit_tasks.json` task IDs (e.g., `src-lib:correctness`) and `coverage_matrix.json` file entries (e.g., `src/lib/file-utils.ts` with `required_lenses: [correctness, ...]`) is implicit. A task's `file_group` maps to multiple files in the matrix, but there is no explicit mapping table. The mapping must be reverse-engineered by reading both files.
-
-**Fix needed:** Either include the resolved file list in each task, or provide an `audit-code explain-task <task_id>` subcommand that shows which files and lenses a task covers.
-
----
-
-### F-12 — Bash variable substitution breaks `node -e` shell loops [CD]
-
-When batching remaining tasks with a shell loop that invoked `node -e '...'`, bash expanded `${}` syntax inside the JS string before Node.js received it, producing `bad substitution` errors. The workaround (write a standalone `.mjs` file) is not documented anywhere.
-
-**Fix needed:** Document the correct pattern for batch submission loops, or provide a native `audit-code --batch-results <dir>` to eliminate the need for shell-level scripting entirely.
-
----
-
-### F-13 — Session config discovery and provider switching are error-prone [Both]
-
-**CD observation:** Every invocation printed `[session-config] no session-config.json found` — 252+ times across the run. The warning appeared even after completing ingestion steps that should have established the session.
-
-**OC observation:** Required manually creating `session-config.json` with `{"provider": "opencode"}`. Even after doing so, the provider change only altered the error message; actual dispatch still did not work.
-
-**Fix needed:** Create a default `session-config.json` on first `audit-code` run. Suppress the warning when a session config is genuinely optional. Document the `provider` field and its valid values prominently in the session-config guide.
-
----
-
-### F-14 — No documentation on artifact schema or contract [OC]
-
-The `contract_version: "audit-code/v1alpha1"` header implies a versioned protocol, but there is no schema documentation. The expected formats for JSONL structure, finding shape, task_id conventions, and coverage matrix layout had to be learned entirely by reading existing artifacts and reverse-engineering error messages.
-
-**Fix needed:** Publish a contract reference document alongside `docs/contract.md` (which exists but may be incomplete) covering: all artifact file schemas, field-level types and constraints, task_id naming convention, and the expected `AuditResult` JSON shape with a worked example.
-
----
-
-## Low
-
-### F-15 — `worker_results_pending.json` not cleared after ingestion [CD]
-
-After `audit-code --results <file>`, the staging file is not cleared. Stale results from the previous task are resubmitted if the worker forgets to overwrite the file.
-
-**Fix needed:** After successful ingestion, delete or rename `worker_results_pending.json` (e.g., to `worker_results_submitted_<timestamp>.json`).
-
----
-
-### F-16 — `related_findings` contains only circular self-references [CD]
-
-In the synthesized `synthesis_report.json`, nearly every finding's `related_findings` array contains only the finding's own ID. This is useless and misleads reviewers into thinking cross-finding relationships were analyzed.
-
-**Fix needed:** Omit `related_findings` when the synthesis engine cannot identify cross-finding relationships, rather than populating it with a self-reference.
-
----
-
-### F-17 — Runtime validation evidence shows "pending" for every finding [CD]
-
-All 95 findings contain entries like `"runtime:unit:src-modules: pending — No runtime evidence recorded yet"`. These appear verbatim across every finding, bloating each one with 2–3 lines of noise that convey nothing.
-
-**Fix needed:** Omit pending evidence entries from the output entirely. A finding with no runtime evidence should have no runtime evidence in its array — not a placeholder repeated 95 times.
-
----
-
-### F-18 — `root_cause_clusters` are file co-location groups, not semantic clusters [CD]
-
-The 46 clusters are named `"correctness/correctness in src/modules"` — file-path groups with a lens label, not semantic root causes. One cluster for "correctness in src/modules" contains 5 findings with 3 entirely different root causes (division-by-zero, cudagraph violation, dead code).
-
-**Fix needed:** Root-cause clustering should be semantic (e.g., "All NaN paths from missing eps guards"). Either improve the clustering algorithm or rename the section to `file_clusters` to accurately describe what it contains.
-
----
-
-### F-19 — `work_blocks` section omitted from final summary presentation [CD]
-
-The audit directive says findings should be organized into "non-overlapping blocks of tasks." `synthesis_report.json` correctly generates 22 `work_blocks`. The final summary presentation omitted this section entirely, showing only a flat findings table. Work blocks are arguably the most actionable output and should lead the summary.
-
-**Fix needed:** Make the `work_blocks` presentation requirement explicit and prominent in the final-output section of the prompt.
-
----
-
-### F-20 — `reviewed_ranges` field is unenforceable and creates false confidence [CD]
-
-Workers can declare `reviewed_ranges: [{start: 1, end: 10}]` while writing findings about line 800, or declare the full file range without actually reading it. For a 966-line file this makes the field meaningless.
-
-**Fix needed:** Either remove `reviewed_ranges` (it creates false confidence) or enforce it mechanically by requiring a content hash or line-count to be included alongside the range declaration.
-
----
-
-## Summary Table
-
-| ID | Issue | Sev | Env | Type |
-|----|-------|-----|-----|------|
-| F-01 | Orchestrator never reaches `status: "complete"` — task statuses undefined | Critical | Both | Bug |
-| F-02 | Worker launch failures / silent executor failures | Critical | Both | Bug |
-| F-03 | `--results` ingestion unreliable (type errors, wrong path, `.map()` crash) | High | Both | Bug |
-| F-04 | CLI hangs without output on some invocations | High | CD | Bug |
-| F-05 | Requeue tasks explosion — 141 tasks from 10 findings | High | OC | Bug |
-| F-06 | Evidence schema undocumented; validated only at ingestion (conflicting types across envs) | Medium | Both | DX |
-| F-07 | `synthesis_current` permanently "missing" even when report is populated | Medium | Both | Bug |
-| F-08 | "All remaining N tasks low priority" — no guidance on worker action | Medium | CD | UX |
-| F-09 | Trivially empty files dispatched as full audit tasks | Medium | CD | Design |
-| F-10 | No batch task dispatch; one task = one CLI invocation = one round-trip | Medium | Both | Design |
-| F-11 | Coverage matrix ↔ task_id mapping is opaque; no lookup table | Medium | OC | DX |
-| F-12 | Bash variable substitution breaks `node -e` shell loops | Medium | CD | DX |
-| F-13 | Session config discovery / provider switching error-prone; noisy warnings | Medium | Both | UX |
-| F-14 | No documentation on artifact schema or contract | Medium | OC | DX |
-| F-15 | `worker_results_pending.json` not cleared after ingestion | Low | CD | Bug |
-| F-16 | `related_findings` circular self-references | Low | CD | Data |
-| F-17 | Runtime validation "pending" entries in all 95 findings | Low | CD | Data |
-| F-18 | `root_cause_clusters` are file co-location groups, not semantic | Low | CD | Design |
-| F-19 | `work_blocks` omitted from final summary presentation | Low | CD | UX |
-| F-20 | `reviewed_ranges` unenforceable; creates false confidence | Low | CD | Design |
-
-**Env key:** CD = Claude Desktop (claude-code provider), OC = OpenCode (opencode provider), Both = independently observed in both.
-
-**Type key:** Bug = incorrect behavior, DX = developer/worker experience, UX = output/presentation, Design = intentional design that needs reconsideration, Data = output data quality.

package/docs/github-copilot.md

@@ -1,66 +0,0 @@
-# GitHub Copilot setup
-
-This is one repo-local host integration for the `/audit-code` conversation surface.
-
-It is now a narrower host-specific path. The preferred user flow is a global
-package install plus the prompt's self-bootstrap step; `audit-code install`
-remains the explicit repair or force-refresh path.
-
-## Recommended path
-
-Install once:
-
-```bash
-npm install -g auditor-lambda
-```
-
-Then invoke `/audit-code` in a supported chat surface. The prompt runs:
-
-```bash
-audit-code ensure --quiet
-```
-
-If Copilot has not discovered the workspace prompt/MCP files yet, run this from
-the target repository root:
-
-```bash
-audit-code install
-```
-
-That writes the canonical `/audit-code` prompt and compatibility instructions into:
-
-```text
-.github/prompts/audit-code.prompt.md
-.github/copilot-instructions.md
-```
-
-After that, open GitHub Copilot Chat in the same repository and invoke `/audit-code`.
-
-If you only want the narrower VS Code / Copilot install surface, use:
-
-```bash
-audit-code install --host vscode
-```
-
-## Behavior
-
-- `audit-code ensure` creates or refreshes the same files only when missing or stale
-- `audit-code install` force-refreshes the canonical prompt payload from `skills/audit-code/audit-code.prompt.md`
-- the generated prompt file explicitly sets `agent: auditor` so Copilot Chat uses the generated auditor custom agent
-- the installer upserts its managed compatibility block into `.github/copilot-instructions.md` instead of clobbering unrelated instructions
-- it prints machine-readable JSON describing the installed targets
-
-## Explicit root override
-
-If you are running from outside the target repository:
-
-```bash
-audit-code install --root /path/to/repo
-```
-
-## Why this exists
-
-The goal is to reduce conversation setup friction without repositioning the backend CLI as the primary product surface.
-
-GitHub Copilot now shares the same repo-native self-bootstrap path as the other currently automated hosts.
-The older `audit-code install-host --host copilot` alias still exists for compatibility, but it is no longer the recommended setup flow.

package/docs/model-selection.md

@@ -1,97 +0,0 @@
-# model selection
-
-This repository has two distinct model-selection layers.
-
-## 1. Skill-first product rule
-
-The canonical product surface is `/audit-code` in conversation.
-
-For that surface, the default model rule is:
-
-- use the active conversation model by default
-- avoid forcing the user to supply a model in normal usage
-
-That is the intended product contract.
-
-When packet dispatch is prepared, `dispatch-plan.json` includes
-provider-neutral complexity metadata and a `model_hint.tier` value:
-
-- `small` for tiny, low-priority packets without sensitive lenses or risk tags
-- `standard` for ordinary bounded review packets
-- `deep` for high-priority, large, critical-flow, or external-signal packets
-
-Hosts that support per-subagent model choice may map those tiers to their own
-available models. Hosts that do not support model choice can ignore the fields.
-The backend still does not prescribe concrete model names.
-
-## 2. Backend provider rule
-
-When the local backend delegates bounded worker runs into an external provider, model selection becomes provider-specific.
-
-That means the supervisor should not invent a global model abstraction unless it can be implemented consistently across adapters.
-
-Today the practical rule is:
-
-- no provider-specific model override by default
-- let each provider use its own default model unless explicitly configured otherwise
-- when a model is required, pass it through the provider's own native CLI arguments via `extra_args`
-
-## Current provider behavior
-
-### `local-subprocess`
-
-No external LLM provider is selected here.
-
-The supervisor simply launches the bounded local worker command.
-
-### `claude-code`
-
-The built-in Claude Code adapter supports model overrides through `claude_code.extra_args`.
-
-Example:
-
-```json
-{
-  "provider": "claude-code",
-  "ui_mode": "visible",
-  "claude_code": {
-    "command": "claude",
-    "extra_args": ["--model", "sonnet"]
-  }
-}
-```
-
-Use this only when you want to force a specific Claude Code model instead of relying on the user's normal Claude Code default.
-
-### `opencode`
-
-The built-in OpenCode adapter supports model overrides through `opencode.extra_args`.
-
-Example:
-
-```json
-{
-  "provider": "opencode",
-  "ui_mode": "visible",
-  "opencode": {
-    "command": "opencode",
-    "extra_args": ["--model", "anthropic/claude-sonnet-4.5"]
-  }
-}
-```
-
-Use this only when you want to force a specific OpenCode provider/model pair instead of relying on the user's normal OpenCode default.
-
-### `subprocess-template` and `vscode-task`
-
-These adapters do not define model semantics themselves.
-
-If you need model selection here, include it in the external launcher command template or in the external tool being invoked.
-
-## Recommendation
-
-For the cleanest product behavior:
-
-1. in conversation, let `/audit-code` inherit the active conversation model
-2. for repo-local backend usage, do not force model selection unless the operator has a concrete reason
-3. when needed, set model selection in the provider-native config rather than inventing another repo-level abstraction

package/docs/next-steps.md

@@ -1,202 +0,0 @@
-# Next Implementation Steps
-
-This document tracks the next meaningful implementation work after the packet
-review-dispatch refactor and the current skill-first productionization pass.
-
-As of April 30, 2026, the shared MCP substrate and the host-native installer pass have landed, but this repository is not yet ready for a public production launch.
-
-See:
-
-- `docs/production-readiness.md`
-
-## Current state
-
-The repository now supports:
-
-- `/audit-code` as the documented canonical product route
-- packaged and repository-local access to `skills/audit-code/audit-code.prompt.md`
-- `audit-code prompt-path` as a stable prompt lookup helper
-- `npm install -g auditor-lambda` as the intended one-time user install
-- `audit-code ensure` as an idempotent self-bootstrap helper for current repository host surfaces
-- `audit-code install --host vscode|opencode|codex|claude-desktop|antigravity|all` as an explicit repair or force-refresh installer for the current host surfaces
-- `audit-code mcp` as a first-class stdio MCP server entrypoint
-- a stable MCP contract with the `start_audit`, `get_status`, `continue_audit`, `explain_task`, `validate_artifacts`, `import_results`, and `import_runtime_updates` tools
-- repo-local MCP resources for current artifacts, operator handoff, install guidance, and the current audit report
-- repo-local MCP prompts for `audit-code`, `review-task`, and `synthesize-report`
-- generated `.audit-code/install/manifest.json` plus a shared repo-local MCP launcher script
-- Codex install assets including a repo skill bundle, `AGENTS.md` support, MCP setup guidance, and an automation recipe
-- Claude Desktop install assets including a project template, remote connector template, and generated local bundle artifacts
-- OpenCode install assets including command, skill, prompt, and `opencode.json` support
-- VS Code install assets including prompt file, Copilot instructions, custom agent, and `.vscode/mcp.json`
-- Antigravity install assets including planning-mode guidance and MCP-oriented setup guidance
-- explicit failures for malformed backend config and corrupted artifact JSON
-- `audit-code validate` as a machine-readable backend operator check
-- 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. Prove packet review dispatch on real repositories
-
-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:
-
-- 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:
-
-- `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.
-
-Near-term work should focus on:
-
-- verifying the Codex skill bundle, `AGENTS.md`, MCP setup guidance, and automation recipe against the real Codex app flow
-- installing and smoke-testing the generated Claude Desktop `DXT` or bundle output in a real Desktop environment
-- validating that the OpenCode `opencode.json` shape, command file, and MCP config match current OpenCode behavior
-- 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
-
-### 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.
-
-Near-term work should focus on:
-
-- turning the Codex automation recipe into a proven, documented automation flow after real operator validation
-- polishing Claude Desktop one-click install so the generated bundle is a clearly supported path instead of a mostly technical artifact
-- 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
-
-### 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.
-
-Near-term work should focus on:
-
-- clearer evidence handoff for imported results and runtime updates
-- less operator guesswork when a configured provider fails to return usable results
-- stronger host-specific guidance for provider-assisted bridges
-
-### 5. Harden publish and release operations
-
-The packaged install story is in place, but release operations still need finishing work.
-
-Near-term work should focus on:
-
-- npm package-name availability and ownership
-- one-time npm Trusted Publisher setup for `.github/workflows/publish-package.yml`
-- the first GitHub Actions dry run and live publish through that workflow
-- keeping prerelease publication off the `latest` dist-tag unless intentionally requested
-- keeping linked-install and packaged-install smoke checks as release gates
-
-## Frictionless-ready checklist
-
-The repository should not be described as frictionless and production-ready until this checklist is substantially true:
-
-### Codex, Claude Desktop, OpenCode, and VS Code
-
-- `audit-code ensure` remains the default self-bootstrap path and `audit-code install` remains the explicit repair path
-- the generated repo-local surfaces are obvious in installer output and in `.audit-code/install/GETTING-STARTED.md`
-- a new user can invoke `/audit-code` without guessing where prompts or commands were written
-- the generated MCP setup path works in the real host, not only in unit tests
-- smoke coverage continues to verify the exact repo-local files these hosts consume
-
-### Antigravity
-
-- the planning-mode guidance is explicit, repo-local, and easy to discover
-- `.audit-code/install/GETTING-STARTED.md` gives Antigravity-specific steps instead of generic prompt-import advice
-- docs avoid implying native repo-local saved-workflow support that is not actually shipped
-- the backend fallback remains a clearly secondary path instead of the default recommendation
-
-### Assisted review continuation
-
-- configured interactive providers can continue blocked audits through audit-task review in the same wrapper invocation
-- operator handoff artifacts remain explicit and inspectable even when continuation is smoother
-
-### Release operations
-
-- `npm run verify:release` remains green and authoritative
-- the real publish path is proven with npm ownership, npm Trusted Publishing, and a real GitHub Actions dry run or prerelease publish
-
-## Probable next steps
-
-These are the most likely next implementation steps based on the current codebase state, but they should still be treated as provisional rather than guaranteed:
-
-### 1. Prove the host installers in real products
-
-Status:
-
-- partially completed in code, not yet fully validated operationally
-
-Most likely shape:
-
-- run fresh-repo smoke checks inside Codex, Claude Desktop, OpenCode, and VS Code, with Antigravity validated against its planning-mode path
-- confirm that the generated files are both syntactically valid and actually discovered by each host
-- tighten generated docs wherever operator confusion appears during those checks
-- keep Antigravity as a documented planning-mode path unless a stable project config contract is published
-
-Practical success bar:
-
-- a new operator can run one install command and reach a working `/audit-code` or MCP-backed flow in each claimed host without guesswork
-
-### 2. Harden configured interactive-provider continuation
-
-Most likely shape:
-
-- use the existing provider configuration surface in `.audit-artifacts/session-config.json`
-- keep the provider-assisted review handoff less manual when `claude-code`, `opencode`, or another bridge is intentionally configured
-- preserve explicit artifact imports and operator visibility instead of hiding state transitions
-- improve diagnostics and recovery when the provider fails to emit structured results
-
-Practical success bar:
-
-- a configured provider can continue through audit-task review with good diagnostics and low operator guesswork when something goes wrong
-
-### 3. Finish the Claude Desktop and Antigravity follow-through
-
-Most likely shape:
-
-- prove the generated Claude Desktop local bundle in a real Desktop install flow
-- decide whether to check in or generate the final desktop-extension packaging metadata more explicitly
-- add remote connector deployment guidance that is specific enough for Team or Enterprise rollout
-- document exactly how Antigravity-produced artifacts should flow back through `import_results` and `import_runtime_updates`
-
-Practical success bar:
-
-- Claude Desktop and Antigravity guidance is operational, specific, and consistent with what the products really support
-
-### 4. Prove the release path outside the repository
-
-Most likely shape:
-
-- confirm npm package-name ownership and npm Trusted Publisher configuration
-- run a real GitHub Actions pre-release or dry-run publish
-- keep `npm run verify:release` as the minimum in-repo gate before publish
-
-Practical success bar:
-
-- the release workflow is demonstrated end to end instead of only being inferred from configuration
-
-## Non-goals for the next phase
-
-These should not become the primary focus of the next implementation pass:
-
-- repositioning the CLI as a peer product surface
-- expanding low-level backend helpers into a CLI-first user experience
-- making backend implementation details outrank the conversation contract in docs or product decisions