auditor-lambda 0.3.12 → 0.3.14

package/docs/releasing.md

@@ -1,145 +0,0 @@
-# Releasing
-
-This repository publishes to npm through GitHub Actions Trusted Publishing.
-
-The canonical workflow is:
-
-`/.github/workflows/publish-package.yml`
-
-That workflow already:
-
-- runs on GitHub-hosted runners
-- requests `id-token: write` for npm OIDC exchange
-- 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
-
-Before the first live publish, configure npm itself to trust this repository:
-
-1. confirm the intended npm owner already controls `auditor-lambda`
-2. in the npm package settings, add a GitHub Actions trusted publisher for:
-   - owner or organization: `OhOkThisIsFine`
-   - repository: `auditor-lambda`
-   - workflow filename: `publish-package.yml`
-3. keep the workflow filename stable after that, or update the npm trusted publisher entry before renaming it
-4. after the first successful trusted publish, consider enabling npm's setting that requires 2FA and disallows legacy publish tokens
-
-## Release preflight
-
-From the repository root:
-
-```bash
-npm ci
-npm run verify:release
-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.
-
-## Version bump helpers
-
-You do not need to look up the current version before cutting a release bump.
-
-From the repository root:
-
-```bash
-npm run release:patch
-```
-
-That delegates the increment to `npm version patch`, updates `package.json` and `package-lock.json`, and creates the matching release commit and git tag in the existing repository format:
-
-Under the hood, the helper uses `npm version patch --no-git-tag-version` and then creates the release commit and annotated git tag explicitly so the workflow stays compatible with current npm CLI behavior.
-
-- commit: `release: vX.Y.Z`
-- tag: `vX.Y.Z`
-
-The repository also exposes:
-
-- `npm run release:minor`
-- `npm run release:major`
-
-After the version bump, push `main` and the new tag, then publish through the GitHub Actions trusted publishing flow.
-
-## One-command release publish
-
-When you want the repository to do the full maintainer flow in one command, use:
-
-```bash
-npm run release:patch:publish
-```
-
-That command:
-
-1. verifies the git worktree is clean and you are on `main`
-2. runs `npm run verify:release`
-3. bumps the version, commits `package.json` and `package-lock.json`, and creates the annotated release tag
-4. pushes `main` and the new release tag
-5. creates the matching GitHub Release
-6. waits for `publish-package.yml` to publish through Trusted Publishing
-7. confirms the new npm version resolves from the registry before exiting
-
-Minor and major variants are also available:
-
-- `npm run release:minor:publish`
-- `npm run release:major:publish`
-
-## 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
-
-Use GitHub Actions `workflow_dispatch` when you want to prove the exact publish workflow without uploading a package.
-
-Recommended inputs:
-
-- `dry_run=true`
-- `publish_tag=auto`
-
-`publish_tag=auto` resolves like this:
-
-- stable versions publish to `latest`
-- semver prerelease versions publish to `next`
-
-### Manual live publish
-
-Use `workflow_dispatch` with:
-
-- `dry_run=false`
-- `publish_tag=auto` unless you intentionally need a different dist-tag
-
-This is the safest path for the first trusted-publishing release because it lets you prove the workflow before tying it to a GitHub Release event.
-
-### Release-driven publish
-
-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:
-
-```bash
-npm view auditor-lambda version
-npm view auditor-lambda dist-tags --json
-npm audit signatures
-```
-
-Also confirm that the npm package page shows the expected version and provenance information.

package/docs/remediation-baseline.md

@@ -1,75 +0,0 @@
-# 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/repo-layout.md

@@ -1,30 +0,0 @@
-# Repository layout
-
-## Top-level purpose
-
-- `docs/`: architecture, pipeline, layout, and design notes
-- `schemas/`: JSON schemas for stable intermediate artifacts
-- `skills/audit-code/`: portable prompt assets and skill-facing product instructions
-- `src/`: implementation code for extraction, orchestration, coverage, and reporting
-- `examples/`: example artifacts demonstrating expected shapes
-- `.audit-artifacts/`: runtime-generated local artifact bundle for fallback wrapper runs; do not commit it
-- `dist/`: checked-in compiled runtime output used by the packaged entrypoint
-- `docs/next-steps.md`: current roadmap and next implementation notes
-- `docs/production-launch-bar.md`: explicit minimum launch criteria and release verification bar
-- `docs/production-readiness.md`: current production-readiness verdict and launch blockers
-
-## Near-term code layout
-
-- `src/extractors/`: deterministic collectors and heuristic classifiers
-- `src/orchestrator/`: task construction, chunking, pass logic, and requeue support
-- `src/coverage/` or `src/coverage.ts`: coverage accounting helpers
-- `src/reporting/`: result merging and remediation views
-- `src/types.ts`: shared TypeScript interfaces mirroring the JSON schemas as closely as practical
-
-## Skill portability rule
-
-The repo should be usable even when the host environment changes. For that reason:
-
-- prompts should remain plain markdown
-- artifacts should remain plain JSON
-- orchestration logic should not depend on one editor or one agent runtime

package/docs/run-flow.md

@@ -1,56 +0,0 @@
-# Run flow
-
-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.
-
-## Packet review-dispatch path
-
-1. Build or import a repository manifest.
-2. Build units, graph edges, flows, risk, and other deterministic structure
-   artifacts.
-3. Determine which files require which lenses and create compatible
-   `AuditTask` records.
-4. Build `review_packets.json` and `audit_plan_metrics.json` from those tasks.
-5. Stop at semantic review with an active run handoff.
-6. `prepare-dispatch` writes a small run-scoped `dispatch-plan.json` and one
-   prompt per review packet, plus a backend-owned result map.
-   Isolated large-file packets also get mechanical anchor summaries for
-   targeted review.
-7. The active conversation orchestrator launches one bounded subagent per
-   packet when the host supports subagents.
-8. Each subagent pipes `AuditResult[]` to the packet's `submit-packet` command;
-   the backend validates and writes assigned result files.
-9. `merge-and-ingest` validates the full assigned task set and ingests the
-   existing `AuditResult[]` shape.
-10. Result ingestion updates coverage, requeue, runtime-validation state, and
-   any selective-deepening follow-up tasks.
-11. Repeat until coverage and runtime rules are satisfied.
-12. Synthesize findings into merged outputs.
-
-## Current backend capability
-
-The current TypeScript implementation already covers:
-
-- repo intake and ignore handling
-- structure and planning artifact generation
-- graph-first packet review planning
-- compact packet dispatch and merge envelopes
-- reviewed-range ingestion from audit results
-- bounded selective deepening
-- runtime validation update ingestion
-- synthesis and completion tracking
-- 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 packet dispatch by default
-- when fallback execution blocks, the wrapper should still leave behind explicit operator handoff files and suggested evidence-import paths
-
-Broader product priorities are tracked in:
-
-- `docs/workflow-refactor-brief.md`
-- `docs/next-steps.md`

package/docs/session-config.md

@@ -1,319 +0,0 @@
-# session-config
-
-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
-.audit-artifacts/session-config.json
-```
-
-This file is optional.
-
-If it does not exist, the backend defaults to its built-in behavior.
-On first backend run, `audit-code` now writes a repo-local default file automatically:
-
-```json
-{
-  "provider": "local-subprocess"
-}
-```
-
-If it exists but contains invalid values, the backend now fails loudly before starting worker runs.
-You can also check it explicitly with:
-
-```bash
-audit-code validate
-```
-
-## Supported fields
-
-```json
-{
-  "provider": "local-subprocess",
-  "timeout_ms": 1800000,
-  "ui_mode": "headless",
-  "agent_task_batch_size": 1
-}
-```
-
-### `provider`
-
-Supported values:
-
-- `auto`
-- `local-subprocess`
-- `subprocess-template`
-- `claude-code`
-- `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, either set `provider`
-  in this file intentionally or re-run the wrapper with an explicit
-  `--provider <name>` flag
-
-### `timeout_ms`
-
-Worker-run timeout in milliseconds.
-
-### `ui_mode`
-
-Supported values:
-
-- `headless`
-- `visible`
-
-Use `visible` when you want stdout and stderr mirrored into the current terminal while the provider runs.
-
-### `agent_task_batch_size`
-
-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.
-
-This setting only affects explicit backend provider-assisted fallback batches.
-The canonical conversation route uses run-scoped review packets from
-`prepare-dispatch` while still preserving one validated `AuditResult` per
-underlying 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 slash-command subagent
-parallelism, which belongs to the host runtime.
-
-## Auto provider mode
-
-`auto` is an explicit opt-in mode.
-
-If `provider` is omitted entirely, the backend still defaults to `local-subprocess`.
-
-When `provider` is set to `auto`, resolution works like this:
-
-1. use `vscode-task` when running under VS Code and a `vscode_task.command_template` is configured
-2. otherwise use `subprocess-template` when `subprocess_template.command_template` is configured
-3. otherwise use `claude-code` when Claude Code is available and preferred by config or when it is the only detected external CLI
-4. otherwise use `opencode` when OpenCode is available and preferred by config or when it is the only detected external CLI
-5. otherwise fall back to `local-subprocess`
-
-This keeps the current default stable while still allowing best-effort cross-editor/provider routing when you explicitly want it.
-
-## Provider-specific sections
-
-### `local-subprocess`
-
-No extra config is required.
-
-This mode covers deterministic audit execution locally and stops in a terminal
-blocked state once the remaining work requires semantic review. The
-slash-command orchestrator should then dispatch bounded subagents when the host
-supports them, or complete one assigned task and stop when it does not.
-
-When the active conversation agent reviews multiple task batches before ingestion, prefer `audit-code --batch-results <dir>` over ad hoc artifact edits.
-
-This remains the safest fallback default while the semantic-review workflow is being realigned.
-
-### `claude_code`
-
-```json
-{
-  "provider": "claude-code",
-  "ui_mode": "visible",
-  "claude_code": {
-    "command": "claude",
-    "extra_args": []
-  }
-}
-```
-
-Fields:
-
-- `command`: optional override for the Claude Code executable
-- `extra_args`: optional extra arguments for Claude Code
-- `dangerously_skip_permissions`: optional trusted-automation opt-in. When
-  `true`, the bridge appends `--dangerously-skip-permissions`. Leave this
-  unset for the safer default.
-
-Current implementation support only.
-
-Use this only when you intentionally want the backend fallback CLI to bridge
-review into an external Claude Code process, either by setting
-`provider: "claude-code"` in this file or by running
-`audit-code --provider claude-code`.
-
-### `opencode`
-
-```json
-{
-  "provider": "opencode",
-  "ui_mode": "visible",
-  "opencode": {
-    "command": "opencode",
-    "extra_args": []
-  }
-}
-```
-
-Fields:
-
-- `command`: optional override for the OpenCode executable
-- `extra_args`: optional additional arguments for `opencode run ...`
-
-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`
-
-```json
-{
-  "provider": "subprocess-template",
-  "ui_mode": "visible",
-  "subprocess_template": {
-    "command_template": ["bash", "-lc", "{workerCommandShell}"],
-    "env": {}
-  }
-}
-```
-
-Fields:
-
-- `command_template`: required command array
-- `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`
-
-```json
-{
-  "provider": "vscode-task",
-  "ui_mode": "visible",
-  "vscode_task": {
-    "command_template": ["bash", "-lc", "{workerCommandShell}"],
-    "env": {}
-  }
-}
-```
-
-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
-
-`subprocess-template` and `vscode-task` support these placeholders inside each `command_template` entry:
-
-- `{repoRoot}`
-- `{runId}`
-- `{obligationId}`
-- `{promptPath}`
-- `{taskPath}`
-- `{resultPath}`
-- `{stdoutPath}`
-- `{stderrPath}`
-- `{workerCommandShell}`
-- `{workerCommandJson}`
-- `{uiMode}`
-- `{timeoutMs}`
-
-### Placeholder guidance
-
-- Use `{workerCommandShell}` when your launcher can execute a fully rendered shell command directly.
-- Use `{workerCommandJson}` when your launcher wants the worker command as structured data.
-- Use `{promptPath}` and `{taskPath}` when an external tool should read the generated worker instructions instead of directly executing the worker command.
-
-## Suggested starting points
-
-### Safest default
-
-```json
-{
-  "provider": "local-subprocess"
-}
-```
-
-### Best-effort automatic routing
-
-```json
-{
-  "provider": "auto",
-  "ui_mode": "visible"
-}
-```
-
-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
-{
-  "provider": "claude-code",
-  "ui_mode": "visible"
-}
-```
-
-Then start the backend bridge explicitly:
-
-```bash
-audit-code --provider claude-code
-```
-
-### Delegate worker runs into OpenCode
-
-```json
-{
-  "provider": "opencode",
-  "ui_mode": "visible"
-}
-```
-
-Then start the backend bridge explicitly:
-
-```bash
-audit-code --provider opencode
-```
-
-### Use a generic bash launcher bridge
-
-```json
-{
-  "provider": "subprocess-template",
-  "ui_mode": "visible",
-  "subprocess_template": {
-    "command_template": ["bash", "-lc", "{workerCommandShell}"]
-  }
-}
-```
-
-Then start the backend bridge explicitly:
-
-```bash
-audit-code --provider subprocess-template
-```
-
-## Antigravity note
-
-A dedicated Antigravity adapter is not currently shipped.
-
-Until one exists, the practical options are:
-
-- run `audit-code` from an Antigravity terminal with `local-subprocess`
-- use `provider: "auto"` when you want best-effort routing without forcing a specific backend
-- use `subprocess-template` with a launcher that Antigravity can reliably invoke
-- treat the conversation-level `/audit-code` contract as primary and the backend CLI as fallback