audit-tools 0.28.0

package/docs/audit-pkg/history.md

@@ -0,0 +1,66 @@
+# History
+
+This page keeps short archival context that used to live in several
+phase-specific documents. It is not the current roadmap or release gate.
+
+## Field-trial lessons
+
+Earlier real-repository runs surfaced issues around:
+
+- completion detection
+- worker launch failures
+- result ingestion validation
+- command hangs without progress
+- requeue task explosion
+- evidence schema ambiguity
+- noisy runtime placeholders
+- weak root-cause clustering
+- missing work-block presentation
+- unenforceable reviewed ranges
+
+Most of those findings have dedicated regression coverage now. The durable
+lesson is that failure states should be explicit, schema validation should be
+field-level, and packetization should optimize for coherent review context
+rather than raw worker-count reduction alone.
+
+## Remediation baseline
+
+The old remediation baseline recorded fixes across:
+
+- CI and release smoke coverage
+- extractor path handling
+- schema-contract validation
+- orchestration state handling
+- provider and supervisor behavior
+- CLI and IO robustness
+- reporting and synthesis behavior
+- generated install payload parity
+
+Current readiness is tracked in `docs/product.md`, `docs/operator-guide.md`,
+`docs/contracts.md`, `docs/release.md`, and `docs/development.md`.
+
+## Monorepo migration & drift reconciliation (2026-05 → 2026-06)
+
+The auditor and remediator began as standalone repos (`auditor-lambda`,
+`remediator-lambda`) and were merged into this npm-workspaces monorepo on a
+shared `@audit-tools/shared` foundation. `providers/` and `quota/` had been
+copy-pasted into both tools and forked in place; the ten resulting drift bugs
+were all fixed by centralizing the forked logic into `shared` (one source of
+truth). Durable decisions from that work:
+
+- **Access scoping is JSON, not MCP.** `AccessDeclaration` rides on the step
+  contract, so it works with any host; the MCP servers stay compatibility
+  adapters over the same contract.
+- **`--dangerously-skip-permissions` defaults ON for the remediator, OFF for the
+  auditor.** The remediator applies changes unattended and cannot pause; the
+  auditor is read-only. The asymmetry is intentional and the flag is overrideable.
+- **The remediator's machine input is `audit-findings.json`, not the Markdown
+  report.** `audit-report.md` is human-facing; a Markdown file handed to the
+  remediator flows through the free-form LLM extractor, not a deterministic parse.
+- **Prompts use one strict path** — no "or / unless / if-available" fallbacks.
+
+Large files were then broken up as behaviour-preserving pure moves (`cli.ts` from
+4072 lines to a thin dispatcher plus `src/cli/*` handlers; `graph.ts`,
+`reviewPackets.ts`, `internalExecutors.ts`, and the generated language table all
+split out). The sprint-by-sprint handoff docs that tracked this work were removed
+once shipped; this section is their durable residue.

package/docs/audit-pkg/operator-guide.md

@@ -0,0 +1,204 @@
+# Operator Guide
+
+## Install and bootstrap
+
+Install once:
+
+```bash
+npm install -g auditor-lambda
+```
+
+Then invoke `/audit-code` in a supported host. The prompt self-bootstraps the
+current repository with:
+
+```bash
+audit-code ensure --quiet
+```
+
+Use these commands when you want to manage setup manually:
+
+```bash
+audit-code ensure
+audit-code ensure --force
+audit-code install
+audit-code verify-install
+audit-code prompt-path
+```
+
+`ensure` is idempotent. `install` rewrites the supported repo-local host
+surfaces.
+
+## Generated files
+
+Shared install files:
+
+- `.audit-code/install/audit-code.import.md`
+- `.audit-code/install/SKILL.md`
+- `.audit-code/install/GETTING-STARTED.md`
+- `.audit-code/install/manifest.json`
+- `.audit-code/install/run-mcp-server.mjs`
+- `.audit-artifacts/session-config.json` when no backend fallback config exists
+
+Host-specific files may include:
+
+- Codex: managed `AGENTS.md` fallback guidance
+- Claude Desktop: project template, remote MCP connector, local MCP bundle
+- OpenCode: `opencode.json` with auditor agent and permission wiring; the `/audit-code` command is global npm-installed state
+- VS Code/Copilot: prompt, custom agent, instructions, and `.vscode/mcp.json`
+- Antigravity: planning-mode guidance
+
+Use `.audit-code/install/GETTING-STARTED.md` as the repo-local handoff after
+bootstrap.
+
+## Host guidance
+
+ChatGPT-style project conversations are the intended product surface. Use
+`/audit-code` in conversation and let the active model and project files be the
+default context.
+
+Codex should normally use the global skill seeded by the npm install plus
+repo-local `AGENTS.md` fallback guidance. The installed skill includes
+`agents/openai.yaml` metadata so Codex can keep the slash-list display aligned
+with the canonical `/audit-code` spelling.
+
+Claude Desktop is treated as a bundle-install host. Use the generated project
+template and local bundle artifacts when installing the integration.
+
+OpenCode uses the global command seeded by `npm install -g auditor-lambda`.
+The generated project `opencode.json` should not define `command["audit-code"]`;
+it only wires the auditor agent and project permissions. VS Code uses
+repo-local prompt and MCP configuration files.
+
+Antigravity should be treated as a workflow-and-artifacts host until it has a
+stable project-local config surface. Use generated planning-mode guidance
+or the backend fallback from an Antigravity-managed terminal when needed.
+
+Manual prompt-import hosts can use:
+
+```bash
+audit-code prompt-path
+```
+
+## Backend fallback
+
+From the target repository root:
+
+```bash
+audit-code
+```
+
+The wrapper:
+
+- defaults artifacts to `<repo-root>/.audit-tools/audit`
+- advances exactly one bounded step per invocation (`next-step` for the
+  conversation step contract; `advance-audit` for the debug envelope)
+- prints usage on a bare invocation — there is no implicit batch loop
+- refreshes `operator-handoff.json` and `operator-handoff.md` under the
+  artifacts directory
+
+Useful fallback commands:
+
+```bash
+audit-code next-step
+audit-code advance-audit
+audit-code advance-audit --results /path/to/audit_results.json
+audit-code advance-audit --batch-results /path/to/results-dir
+audit-code advance-audit --updates /path/to/runtime_validation_update.json
+audit-code advance-audit --external-analyzer-results /path/to/external_analyzer_results.json
+audit-code explain-task <task_id>
+audit-code validate
+audit-code cleanup
+```
+
+`audit-code next-step` is the backend-rendered step engine used by the
+conversation prompt. It writes `.audit-artifacts/steps/current-step.json` and
+`.audit-artifacts/steps/current-prompt.md`, then the host should follow only
+that prompt.
+
+`audit-code validate` checks artifact shape, cross-artifact consistency,
+session config, and explicit provider readiness.
+
+`audit-code cleanup` removes the `.audit-artifacts/` directory when safe to
+do so. It reads `audit_state.json` before acting: `complete` and `not_started`
+states are deleted unconditionally; `active` and `blocked` states are refused
+(the audit is resumable). If `audit_state.json` is missing — typically a
+crashed run — cleanup also refuses unless `--force` is passed. `--dry-run`
+previews the action without deleting anything.
+
+## Session config
+
+Backend fallback configuration lives at:
+
+```text
+.audit-artifacts/session-config.json
+```
+
+The canonical `/audit-code` conversation route should not require users to
+touch this file.
+
+Default:
+
+```json
+{
+  "provider": "local-subprocess"
+}
+```
+
+Supported providers:
+
+- `local-subprocess`
+- `auto`
+- `subprocess-template`
+- `claude-code`
+- `opencode`
+- `vscode-task`
+
+`local-subprocess` is the safest fallback default. `auto` is explicit opt-in.
+External providers are compatibility bridges, not the intended default review
+owner.
+
+Common fields:
+
+```json
+{
+  "provider": "local-subprocess",
+  "timeout_ms": 1800000,
+  "ui_mode": "headless",
+  "agent_task_batch_size": 1,
+  "parallel_workers": 1
+}
+```
+
+Use `ui_mode: "visible"` when debugging provider stdout/stderr. Use
+`subprocess-template` or `vscode-task` only when you have a reliable launcher
+bridge.
+
+## Model selection
+
+Conversation-level model choice belongs to the host conversation. The backend
+should not force a model in normal usage.
+
+For backend provider bridges, let the chosen provider own its own model
+selection unless the operator has a concrete reason to configure it.
+
+Packet dispatch may emit provider-neutral model hints such as `small`,
+`standard`, or `deep`. Hosts can map those hints to their own models.
+
+## Windows notes
+
+Prefer command arrays over shell strings in `session-config.json`. Avoid nested
+shell quoting when possible. For PowerShell templates, keep the executable and
+arguments separate and prefer `{workerCommandJson}` when a launcher can consume
+structured command data.
+
+Runtime validation wraps package-manager shims such as `npm`, `npx`, `pnpm`,
+and `yarn` through the Windows command shell automatically. A runtime
+`not_confirmed` result can still be environmental when the target repo command
+starts but cannot write its own build output.
+
+If final report promotion to `<repo-root>/audit-report.md` is blocked by local
+permissions, the audit can still complete. Use the artifact-bundle copy of
+`audit-report.md` and run `audit-code validate`.
+
+Run `audit-code validate` after editing session config so command-template
+issues fail before a long audit run.

package/docs/audit-pkg/product.md

@@ -0,0 +1,119 @@
+# Product
+
+> Normative definition: [`spec/audit-goals.md`](../spec/audit-goals.md) — product
+> identity, invariants, deterministic/LLM boundaries, and completion. This page is
+> the product overview.
+
+## Canonical surface
+
+The primary product is `/audit-code` in conversation.
+
+Normal product usage should:
+
+- use the active conversation model by default
+- use project files and attached repository context by default
+- avoid manual paths, provider flags, and model-selection arguments
+- keep semantic review with the active conversation agent by default
+- advance the audit automatically until it completes or no further automatic progress is possible
+
+The CLI is backend infrastructure, a local development harness, and a repo-local
+fallback. It is not the preferred end-user mental model.
+
+## Supported surfaces
+
+The supported user-facing surfaces are:
+
+1. `/audit-code` in conversation
+2. `npm install -g auditor-lambda` as the one-time package install
+3. `audit-code prompt-path` to locate the packaged prompt asset
+4. `audit-code ensure` for idempotent repo-local bootstrap
+5. `audit-code install` for explicit repair or force refresh
+6. `audit-code` as the repo-local backend fallback
+
+Anything below `dist/index.js` is backend or development interface.
+
+## Product model
+
+The intended workflow is:
+
+1. The user invokes `/audit-code`.
+2. The prompt runs `audit-code ensure --quiet`.
+3. Deterministic backend steps build or refresh artifacts.
+4. The active conversation dispatches bounded review packets when semantic
+   judgment is required.
+5. Packet workers submit validated `AuditResult` objects through backend-owned
+   commands.
+6. The backend ingests results, performs selective deepening and runtime
+   validation when needed, and writes the final `audit-report.md`.
+
+Semantic review belongs to the active host conversation by default. Backend
+provider adapters such as `claude-code`, `opencode`, `subprocess-template`, and
+`vscode-task` are compatibility bridges for repo-local fallback workflows.
+
+## Language strategy
+
+Packet quality should not depend on one language ecosystem. Every language
+analyzer must write into the same language-neutral graph and artifact contracts;
+JS/TS and Python get the richest early support only because they are common.
+
+Do not keep expanding support by adding one bespoke parser per ecosystem unless
+there is concrete repository demand or a high-value deterministic signal. Prefer
+making graph planning observable and extensible through generic ownership hints
+over an open-ended list of file-format handlers.
+
+The shared graph should model:
+
+- file dependencies
+- module/package ownership
+- test-to-source relationships
+- entrypoint-to-handler relationships
+- config, schema, migration, workflow, and deployment relationships
+- external boundary crossings such as HTTP, queues, databases, filesystems, and
+  subprocesses
+- edge confidence, direction, and reason
+
+Graph evidence is tiered, strongest first:
+
+- deterministic directed edges (imports, entrypoints, route handlers,
+  test/source links, resolved analyzer references)
+- deterministic ownership edges (package, module, project, or subsystem roots)
+- analyzer-supplied ownership roots, normalized into graph reference edges
+- language-agnostic semantic affinity (shared unusual domain terms, nearby
+  paths, identifier overlap, embeddings)
+
+Semantic affinity can rank `boundary_files`, explain possible context, and
+highlight missing extraction — but it must not merge packets on frequency alone,
+because common tokens (`user`, `request`, `client`, `config`, `error`) connect
+unrelated code.
+
+The fallback must stay useful even when a language has no deep analyzer:
+manifests, path structure, tests, config, and external analyzer output can seed a
+graph with lower-confidence edges. Deterministic tool runners should be
+project-config aware — e.g. ESLint syntax-resolution runs only when the repo has
+local ESLint configuration, not merely because the binary is installed.
+
+## Packet planning
+
+`AuditTask` is the deterministic coverage identity; `ReviewPacket` is the
+worker-facing unit of understanding. Packetization aims for packets that read as
+coherent code-ownership or execution-flow units, not merely budget-sized bundles:
+
+- build packets around coherent subsystems and execution flows
+- keep shared fan-in files visible as context rather than merging large parts of
+  the repo into one packet
+- distinguish strong (deterministic) edges from weak or heuristic ones
+- group tests with the code they verify when it aids review
+- carry packet rationale, key edges, entrypoints, and boundary files
+- prefer the generic ownership-root contract (analyzers naming module roots) over
+  a new parser per ecosystem, and keep graph/manifest parsing modular
+
+Planner observability (`audit_plan_metrics.json`: cohesion, fan-in/out, boundary
+crossings, weak-packet gaps) is how extraction gaps are found and prioritized.
+
+## Non-goals
+
+- repositioning the CLI as a peer product surface
+- making session config the normal way to redirect semantic review into a
+  second external LLM
+- making backend implementation details outrank the conversation contract
+- tying packetization quality to one programming language

package/docs/audit-pkg/release.md

@@ -0,0 +1,131 @@
+# Release
+
+## Release gate
+
+Run from the repository root:
+
+```bash
+npm ci
+npm run verify:release
+```
+
+`verify:release` covers:
+
+- TypeScript typecheck
+- full automated test suite
+- linked-install `audit-code` smoke coverage
+- packaged-install `audit-code` smoke coverage
+- tarball contract verification for shipped assets and runtime entrypoints
+- packaged and linked verification of bootstrap install behavior
+
+For live child-process output while debugging smoke tests:
+
+```bash
+AUDIT_CODE_VERBOSE=1 npm run smoke:packaged-audit-code
+AUDIT_CODE_VERBOSE=1 npm run smoke:linked-audit-code
+```
+
+The packaged smoke path strips inherited `npm_config_*`, `NODE_AUTH_TOKEN`, and
+`NPM_TOKEN` values before nested npm operations so dry runs and smoke installs
+do not accidentally inherit publish credentials or suppress tarball generation.
+
+## Publication
+
+Publication is operational through GitHub Actions Trusted Publishing.
+
+Workflow:
+
+```text
+.github/workflows/publish-package.yml
+```
+
+The workflow:
+
+- requests `id-token: write` for npm OIDC exchange
+- pins Node `22.14.0`
+- upgrades npm to `>=11.5.1`
+- runs `npm run verify:release`
+- previews the packed tarball with `npm pack --dry-run`
+- publishes with public access and provenance
+- defaults semver prerelease versions to the `next` dist-tag unless overridden
+- verifies that the published version resolves from the registry
+- uploads `*-npm-logs` artifacts on failure
+
+Routine CI exercises Node `20` and Node `22`.
+
+## Version bump helpers
+
+Use:
+
+```bash
+npm run release:patch
+```
+
+That bumps the version, updates `package.json` and `package-lock.json`, and
+creates the release commit and annotated tag.
+
+Available variants:
+
+- `npm run release:minor`
+- `npm run release:major`
+
+Full maintainer flow:
+
+```bash
+npm run release:patch:publish
+```
+
+That command checks the worktree, runs the release gate, bumps the version,
+commits, tags, pushes `main` and the tag, creates the GitHub Release, waits for
+`publish-package.yml`, and confirms the new npm version resolves.
+
+Minor and major publish variants:
+
+- `npm run release:minor:publish`
+- `npm run release:major:publish`
+
+## Manual workflow dispatch
+
+Use GitHub Actions `workflow_dispatch` to exercise or run the publish workflow.
+
+Dry run:
+
+- `dry_run=true`
+- `publish_tag=auto`
+
+Live publish:
+
+- `dry_run=false`
+- `publish_tag=auto` unless intentionally overriding the dist-tag
+
+`publish_tag=auto` resolves stable versions to `latest` and prerelease versions
+to `next`.
+
+Publishing a GitHub Release triggers the same workflow.
+
+## Trusted publisher setup
+
+npm Trusted Publishing is configured for this repository. If repository,
+workflow, or ownership details change, keep the npm trusted publisher entry
+aligned with:
+
+- owner or organization: `OhOkThisIsFine`
+- repository: `audit-tools`
+- workflow filename: `publish-package.yml`
+
+## Troubleshooting
+
+If a GitHub Actions run fails:
+
+1. download the uploaded `*-npm-logs` artifact
+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`
+4. confirm npm Trusted Publishing still targets `publish-package.yml`
+
+Post-publish checks:
+
+```bash
+npm view audit-tools version
+npm view audit-tools dist-tags --json
+npm audit signatures
+```

package/opencode.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "command": {
+    "remediate-code": {
+      "template": "Run `remediate-code ensure --quiet`, then `remediate-code next-step`, read only the returned prompt_path, and follow that prompt.",
+      "description": "Conversation-first code remediation",
+      "agent": "remediator",
+      "subtask": false
+    }
+  },
+  "mcp": {},
+  "permission": {
+    "read": "allow",
+    "glob": "allow",
+    "grep": "allow",
+    "external_directory": {
+      "*": "allow"
+    },
+    "edit": {
+      "*": "ask",
+      ".audit-code/**": "allow",
+      ".audit-tools/**": "allow",
+      ".audit-artifacts/**": "allow",
+      "audit-report.md": "allow"
+    },
+    "bash": {
+      "*": "allow",
+      "audit-code synthesize*": "deny",
+      "*dist*index.js* synthesize*": "deny",
+      "*audit-code.mjs* synthesize*": "deny",
+      "audit-code cleanup*": "deny",
+      "*dist*index.js* cleanup*": "deny",
+      "*audit-code.mjs* cleanup*": "deny",
+      "audit-code requeue*": "deny",
+      "*dist*index.js* requeue*": "deny",
+      "*audit-code.mjs* requeue*": "deny",
+      "audit-code ingest-results*": "deny",
+      "*dist*index.js* ingest-results*": "deny",
+      "*audit-code.mjs* ingest-results*": "deny",
+      "audit-code": "allow",
+      "audit-code ensure*": "allow",
+      "*audit-code.mjs* ensure*": "allow",
+      "audit-code next-step*": "allow",
+      "*audit-code.mjs* next-step*": "allow",
+      "audit-code prepare-dispatch*": "allow",
+      "*audit-code.mjs* prepare-dispatch*": "allow",
+      "audit-code submit-packet*": "allow",
+      "*audit-code.mjs* submit-packet*": "allow",
+      "audit-code merge-and-ingest*": "allow",
+      "*audit-code.mjs* merge-and-ingest*": "allow",
+      "audit-code validate*": "allow",
+      "*audit-code.mjs* validate*": "allow",
+      "*audit-code.mjs": "allow",
+      "*audit-code.mjs* worker-run*": "allow",
+      "*node* *auditor-lambda*dist*index.js* worker-run*": "allow",
+      "git status*": "allow",
+      "git diff*": "allow",
+      "grep *": "allow",
+      "Select-String *": "allow",
+      "rm *": "deny"
+    }
+  },
+  "agent": {
+    "auditor": {
+      "description": "Read-heavy audit orchestration agent for the /audit-code workflow.",
+      "permission": {
+        "read": "allow",
+        "glob": "allow",
+        "grep": "allow",
+        "external_directory": {
+          "*": "allow"
+        },
+        "edit": {
+          "*": "ask",
+          ".audit-code/**": "allow",
+          ".audit-tools/**": "allow",
+          ".audit-artifacts/**": "allow",
+          "audit-report.md": "allow"
+        },
+        "bash": {
+          "*": "allow",
+          "audit-code synthesize*": "deny",
+          "*dist*index.js* synthesize*": "deny",
+          "*audit-code.mjs* synthesize*": "deny",
+          "audit-code cleanup*": "deny",
+          "*dist*index.js* cleanup*": "deny",
+          "*audit-code.mjs* cleanup*": "deny",
+          "audit-code requeue*": "deny",
+          "*dist*index.js* requeue*": "deny",
+          "*audit-code.mjs* requeue*": "deny",
+          "audit-code ingest-results*": "deny",
+          "*dist*index.js* ingest-results*": "deny",
+          "*audit-code.mjs* ingest-results*": "deny",
+          "audit-code": "allow",
+          "audit-code ensure*": "allow",
+          "*audit-code.mjs* ensure*": "allow",
+          "audit-code next-step*": "allow",
+          "*audit-code.mjs* next-step*": "allow",
+          "audit-code prepare-dispatch*": "allow",
+          "*audit-code.mjs* prepare-dispatch*": "allow",
+          "audit-code submit-packet*": "allow",
+          "*audit-code.mjs* submit-packet*": "allow",
+          "audit-code merge-and-ingest*": "allow",
+          "*audit-code.mjs* merge-and-ingest*": "allow",
+          "audit-code validate*": "allow",
+          "*audit-code.mjs* validate*": "allow",
+          "*audit-code.mjs": "allow",
+          "*audit-code.mjs* worker-run*": "allow",
+          "*node* *auditor-lambda*dist*index.js* worker-run*": "allow",
+          "git status*": "allow",
+          "git diff*": "allow",
+          "grep *": "allow",
+          "Select-String *": "allow",
+          "rm *": "deny"
+        },
+        "auditor_*": "allow",
+        "question": "allow",
+        "task": "allow"
+      }
+    },
+    "remediator": {
+      "description": "Bounded remediation orchestration agent for the /remediate-code workflow.",
+      "permission": {
+        "edit": {
+          "*": "ask",
+          ".remediation-artifacts/**": "allow",
+          "remediation-report.md": "allow",
+          "remediation-report.json": "allow",
+          "remediation-closing-result.json": "allow"
+        },
+        "bash": {
+          "*": "ask",
+          "remediate-code": "allow",
+          "remediate-code ensure*": "allow",
+          "remediate-code next-step*": "allow",
+          "remediate-code prepare-document-dispatch*": "allow",
+          "remediate-code merge-document-results*": "allow",
+          "remediate-code prepare-implement-dispatch*": "allow",
+          "remediate-code merge-implement-results*": "allow",
+          "remediate-code validate-artifacts*": "allow",
+          "*remediate-code.mjs": "allow",
+          "*remediate-code.mjs* ensure*": "allow",
+          "*remediate-code.mjs* next-step*": "allow",
+          "*remediate-code.mjs* prepare-document-dispatch*": "allow",
+          "*remediate-code.mjs* merge-document-results*": "allow",
+          "*remediate-code.mjs* prepare-implement-dispatch*": "allow",
+          "*remediate-code.mjs* merge-implement-results*": "allow",
+          "*remediate-code.mjs* validate-artifacts*": "allow",
+          "git status*": "allow",
+          "git diff*": "allow",
+          "grep *": "allow",
+          "Select-String *": "allow",
+          "rm *": "deny"
+        },
+        "question": "allow"
+      }
+    }
+  }
+}