auditor-lambda 0.3.12 → 0.3.14

package/docs/packaging.md

@@ -1,120 +0,0 @@
-# packaged audit-code validation
-
-This repository validates the packaged installation story for both:
-
-1. the canonical conversation prompt asset
-2. the backend fallback `audit-code` entrypoint
-3. the self-bootstrap `audit-code ensure` path used by global slash commands
-
-It does so in two installation modes:
-
-1. linked local command via `npm link`
-2. clean-room packaged install via `npm pack` followed by `npm install <tarball>`
-
-## Why this exists
-
-The primary product surface is `/audit-code` in conversation.
-
-That means the package needs to ship:
-
-- the canonical prompt asset at `skills/audit-code/audit-code.prompt.md`
-- the companion Codex/OpenCode skill asset at `skills/audit-code/SKILL.md`
-- packet-dispatch support data such as `dispatch/lens-definitions.json`
-- the backend fallback wrapper exposed as `audit-code`
-- user-level postinstall assets for hosts we can safely seed from a global npm
-  install, currently the Claude command and Codex skill bundle
-- `audit-code ensure`, so a globally installed slash command can lazily create
-  the repo-local host assets it needs in each target repository
-
-A linked-command smoke test proves the installed wrapper and prompt lookup work from the working tree.
-A packaged-install smoke test proves the same assets still work when consumed from the packed artifact that a downstream installer would receive.
-
-## Packaged smoke command
-
-From the repository root:
-
-```bash
-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`
-- asserts the packed tarball still includes the required shipped assets and runtime entrypoints
-- installs it into a fresh temporary directory
-- verifies the packaged prompt asset is present and discoverable
-- verifies `audit-code install` can write the bootstrap host surfaces from the packaged install
-- verifies `audit-code ensure` can create those surfaces lazily from the packaged install
-- 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
-
-The packaged-install path is covered by:
-
-```text
-.github/workflows/packaged-entrypoint.yml
-```
-
-The release publish gate also runs both installed-entrypoint smoke paths before `npm publish`:
-
-```text
-.github/workflows/publish-package.yml
-```
-
-## Publish pipeline state
-
-The repository now includes packaging metadata and lifecycle hooks intended for registry publication:
-
-- `package.json` is no longer marked private
-- `publishConfig.access` defaults publication to the public npm access level
-- package contents are curated with a `files` allowlist that includes the canonical prompt, skill, dispatch, schema, and runtime assets
-- `prepack` and `prepare` build the runtime artifact
-- `verify:release` codifies the minimum in-repo release gate
-- `prepublishOnly` now runs that full release gate, including both linked-install and packaged-install smoke validation
-- packaged smoke now verifies the tarball includes `audit-code-wrapper-lib.mjs`, the prompt and skill assets, dispatch lens definitions, the response schema, and `dist/` entrypoints before install-time smoke runs
-- the GitHub publish workflow uses the same release gate before `npm publish`
-- the GitHub publish workflow uses npm Trusted Publishing with GitHub OIDC instead of a long-lived publish token
-- prerelease versions now default to the `next` dist-tag in the publish workflow unless an explicit tag override is chosen on manual dispatch
-
-## Remaining external release steps
-
-Actual publication still depends on npm-side configuration outside the repository:
-
-1. confirm package ownership and intended publish target for `auditor-lambda`
-2. configure npm Trusted Publishing for `.github/workflows/publish-package.yml`
-3. run the first GitHub Actions dry run or live prerelease from that workflow path
-
-The repository-side workflow already pins Node `22.14.0` and upgrades npm to `>=11.5.1`, which is the current minimum combination npm documents for GitHub Actions Trusted Publishing.
-
-## Next packaging steps
-
-The next implementation phase should focus on:
-
-- completing the one-time npm Trusted Publisher setup
-- proving the GitHub Actions dry-run and live publish path end to end
-- preserving the packaged prompt asset and `audit-code prompt-path` as stable release guarantees
-- preserving `audit-code install` as a packaged-install compatibility guarantee
-- keeping linked-install and packaged-install smoke coverage in the publish gate
-- keeping `docs/production-launch-bar.md` aligned with the real release gate
-
-Related roadmap notes:
-
-- `docs/production-readiness.md`
-- `docs/next-steps.md`

package/docs/pipeline.md

@@ -1,152 +0,0 @@
-# Audit pipeline
-
-## Phase 0: intake
-
-Automated:
-
-- enumerate files
-- detect languages and frameworks
-- identify exclusions
-- hash files
-- collect git metadata
-
-Outputs:
-
-- `repo_manifest.json`
-- `file_inventory.json`
-- `stack_profile.json`
-
-## Phase 1: structural extraction
-
-Automated:
-
-- detect services, packages, apps
-- detect routes, jobs, commands, workflows
-- bucket files
-- extract graphs
-- detect data-layer artifacts
-
-Outputs:
-
-- `unit_manifest.json`
-- `surface_manifest.json`
-- `bucket_assignments.json`
-- `graph_bundle.json`
-
-LLM role:
-
-- resolve ambiguous units and suspicious classifications
-
-## Phase 2: mechanical analysis
-
-Automated:
-
-- lint
-- typecheck
-- tests
-- coverage
-- secrets
-- dependencies
-- static security
-- complexity and duplication
-
-Outputs:
-
-- `mechanical_results.json`
-- `hotspot_report.json`
-
-LLM role:
-
-- distinguish signal from noise
-- identify what deserves deeper review
-
-## Phase 3: risk scoring
-
-Automated inputs:
-
-- exposure
-- privilege indicators
-- persistent writes
-- secrets access
-- concurrency signals
-- churn
-- coverage weakness
-
-Outputs:
-
-- `risk_register.json`
-
-LLM role:
-
-- adjust for semantic criticality
-
-## Phase 4: blind-spot mapping
-
-LLM task:
-
-- use manifests, graphs, and bounded source excerpts to identify what tools are likely missing
-
-Outputs:
-
-- `blind_spot_register.json`
-- `runtime_validation_targets.json`
-
-## Phase 5: unit audits
-
-LLM task:
-
-- audit each unit under required lenses
-
-Outputs:
-
-- `audit_results/<unit>/<lens>.json`
-
-## Phase 6: cross-cutting audits
-
-LLM task:
-
-- audit repo-wide concerns such as auth, retries, migrations, config validation, observability, and secrets flow
-
-Outputs:
-
-- `cross_cutting/<theme>.json`
-
-## Phase 7: dynamic validation
-
-Automated + LLM:
-
-- run targeted checks for suspicious cases
-- interpret repro results
-
-Outputs:
-
-- `runtime_validation_report.json`
-
-## Phase 8: coverage verification
-
-Automated:
-
-- verify every file is classified
-- verify every file is audited or explicitly excluded
-- verify reviewed line ranges cover the intended source
-- verify multi-pass overlap for critical units
-
-Outputs:
-
-- `coverage_matrix.json`
-- `line_coverage_map.json`
-- `uncovered_items.json`
-
-## Phase 9: synthesis
-
-LLM task:
-
-- deduplicate findings
-- cluster by root cause
-- prioritize remediation
-
-Outputs:
-
-- `findings.json`
-- `root_cause_clusters.json`
-- `remediation_plan.md`

package/docs/product-direction.md

@@ -1,154 +0,0 @@
-# Product direction
-
-## Source of truth
-
-The primary product is an in-conversation ChatGPT skill:
-
-`/audit-code`
-
-The intended user experience is:
-
-- invoke `/audit-code` in a ChatGPT project conversation
-- use the current conversation model as the primary model
-- use project files and attached repository context as the primary operating context
-- require no manual filesystem paths, provider flags, or model-selection arguments from the user
-- advance the audit automatically until it completes or no further automatic progress is possible, using bounded internal steps only as an implementation detail
-
-## Canonical install asset
-
-The canonical integration asset is:
-
-`skills/audit-code/audit-code.prompt.md`
-
-That asset should be available from both:
-
-- repository checkouts
-- packaged installs
-
-The stable packaged lookup helper is:
-
-```bash
-audit-code prompt-path
-```
-
-That command exists to locate the conversation prompt asset, not to reposition the CLI as the primary user surface.
-
-The intended package install is:
-
-```bash
-npm install -g auditor-lambda
-```
-
-That makes the backend command globally available and lets hosts with user-level
-command or skill discovery expose `/audit-code` before any repository-local
-files exist.
-
-The conversation prompt should self-bootstrap the current repository with:
-
-```bash
-audit-code ensure --quiet
-```
-
-That command creates or refreshes repo-local `/audit-code` surfaces only when
-they are missing or stale.
-
-The explicit repair and compatibility installer is:
-
-```bash
-audit-code install
-```
-
-That command writes the repo-local `/audit-code` surfaces we can automate today instead of making the user choose one host up front.
-
-## What the CLI is
-
-The CLI in this repository is backend infrastructure, a local development harness, and a repo-local fallback operator surface.
-
-It is not the preferred end-user mental model.
-
-## Repo-local fallback
-
-Repo-local backend wrapper:
-
-```bash
-audit-code
-```
-
-from the target repository root.
-
-Fallback explicit form:
-
-```bash
-audit-code --root /path/to/repo
-```
-
-Debug one-step mode:
-
-```bash
-audit-code --single-step
-```
-
-## Backend mode rule
-
-For repo-local backend usage:
-
-- omitted provider should remain the stable safe default: `local-subprocess`
-- `local-subprocess` should stop cleanly once only manual or provider-assisted review remains
-- `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
-- preserve `AuditTask` as the deterministic coverage identity
-- group related tasks into graph-informed review packets for worker dispatch
-- review multiple relevant lenses for the same packet in one worker pass
-- keep one validated `AuditResult` object per underlying task
-- batch tiny homogeneous files rather than spawning one worker per small 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
-
-Future development should optimize for the native skill UX first:
-
-- `/audit-code` in conversation is the canonical product entrypoint
-- 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.
-
-## Near-term implementation priorities
-
-The next implementation phase should focus on:
-
-- reducing prompt-import friction for the conversation setup path
-- keeping the bootstrap path stable across supported hosts
-- extending automation to hosts that still lack a verified repo-local slash-command surface
-- improving continuation when review needs an interactive or assisted provider
-- finishing publish and release hardening for packaged installs
-
-For a fuller roadmap summary, see:
-
-- `docs/next-steps.md`

package/docs/production-launch-bar.md

@@ -1,92 +0,0 @@
-# Production Launch Bar
-
-This document defines the minimum bar this repository should meet before a version is described as production-ready.
-
-It is intentionally narrower than the broader product roadmap in `docs/next-steps.md`.
-
-## Supported product surfaces
-
-The current product surfaces are:
-
-1. `/audit-code` in conversation as the canonical user-facing route
-2. `audit-code prompt-path` as the stable way to locate the packaged prompt asset
-3. `npm install -g auditor-lambda` as the intended one-time user install
-4. `audit-code ensure` as the idempotent repo-local self-bootstrap helper
-5. `audit-code install` as the explicit repo-local repair or force-refresh installer
-6. `audit-code` as the repo-local backend fallback wrapper
-
-Anything below `dist/index.js` remains a backend or development interface rather than the primary end-user contract.
-
-## Supported backend expectations
-
-### 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`
-  - `dispatch/lens-definitions.json`
-  - `skills/audit-code/SKILL.md`
-  - `skills/audit-code/audit-code.prompt.md`
-  - `schemas/audit-code-v1alpha1.schema.json`
-- the checked-in `dist/` output is part of the shipped runtime contract for installed usage
-- global package postinstall should seed user-level command/skill assets only for
-  hosts with stable user-local paths; repo-local assets remain the responsibility
-  of `audit-code ensure` or `audit-code install`
-
-### Backend providers
-
-- `local-subprocess` is the safest default fallback and must keep working without extra provider setup
-- `claude-code`, `opencode`, `subprocess-template`, and `vscode-task` are supported backend adapters when configured correctly
-- `provider: "auto"` is best-effort routing, not a stronger support guarantee than the underlying resolved provider
-
-### Host surfaces
-
-- ChatGPT-style project conversations are the intended `/audit-code` product surface
-- Codex, Claude Desktop, OpenCode, VS Code / GitHub Copilot, and Antigravity repository surfaces are generated through `audit-code ensure` or explicit `audit-code install`
-- editor integrations that import `skills/audit-code/audit-code.prompt.md` are supported as prompt-based integrations
-- no editor-specific native install surface should be called production-ready until it has explicit documentation and a repeatable verification path
-
-## Required verification before calling a release production-ready
-
-Run this from the repository root:
-
-```bash
-npm ci
-npm run verify:release
-```
-
-`npm run verify:release` is the in-repo minimum release gate. It currently covers:
-
-- TypeScript typecheck
-- full automated test suite
-- linked-install `audit-code` smoke coverage
-- packaged-install `audit-code` smoke coverage
-- tarball contract verification for required shipped assets and runtime entrypoints
-- packaged and linked verification of the bootstrap install path
-
-In addition to the in-repo gate, production readiness still requires these external checks:
-
-1. confirm npm package-name ownership and intended publish target
-2. configure npm Trusted Publishing for `.github/workflows/publish-package.yml`
-3. run a real GitHub Actions dry run or prerelease publish from that workflow path
-
-## Operator validation expectations
-
-Before treating the backend fallback as healthy for a repository, `audit-code validate` should pass with zero issues.
-
-That validation now covers:
-
-- artifact-bundle consistency
-- `session-config.json` shape
-- explicit provider readiness for configured external CLIs
-
-## Current residual risk
-
-This repository has a clear backend release gate, but it still should not be called fully production-ready until:
-
-1. hosts without a verified repo-local slash-command surface still have a comparably low-friction bootstrap path
-2. interactive continuation is smoother when assisted review must continue through a provider
-3. external publish operations are proven end to end

package/docs/production-readiness.md

@@ -1,58 +0,0 @@
-# Production Readiness
-
-## Verdict
-
-As of April 30, 2026, the package release path has a strong in-repo release gate, but the broader host experience still has follow-through work before it should be described as a frictionless production launch.
-
-What is already true:
-
-- TypeScript build passes
-- automated test suite passes
-- linked-install smoke coverage passes
-- packaged-install smoke coverage passes
-- packaged tarball contract verification passes
-- `npm run verify:release` is the authoritative local release gate for the current worktree
-- local `npm publish --dry-run` should be run before any release candidate publish
-- npm registry state should be verified at release time rather than inferred from checked-in docs
-- malformed config and corrupted artifact handling are explicit
-- blocked fallback runs now emit structured operator handoff guidance
-- supported repo-local hosts now share an idempotent self-bootstrap path via `audit-code ensure`
-- `audit-code install` remains the explicit repair and force-refresh path
-- configured provider-assisted review can now continue to completion in a single wrapper invocation
-- the GitHub publish workflow is configured for Trusted Publishing through GitHub OIDC rather than a long-lived npm token
-
-## Why It Is Not Yet A Broad Production Claim
-
-The biggest remaining gaps are product and release-operational, not core wrapper correctness:
-
-1. npm publication is not fully proven end to end.
-   The repo now has a Trusted Publishing workflow and a passing local dry run, but npm-side trusted publisher setup plus the first GitHub Actions dry run still need to be completed outside the codebase.
-2. The primary conversation-first product still has setup friction on hosts without a verified repo-local slash-command surface.
-   Codex, Claude Desktop, OpenCode, VS Code / Copilot, and Antigravity now share the same self-bootstrap command, but each generated host surface still needs real-product verification before it can be called frictionless.
-3. Provider-assisted continuation still needs polish outside the happy path.
-   Configured interactive bridges can now continue through audit-task review, but operator guidance and host-specific ergonomics still need refinement when a provider cannot produce results cleanly.
-
-The explicit launch bar is now documented in `docs/production-launch-bar.md`, and the in-repo release gate is codified as `npm run verify:release`.
-
-## Required Next Steps
-
-1. Confirm release operations externally.
-   Validate npm package-name ownership for `auditor-lambda`, configure npm Trusted Publishing for `.github/workflows/publish-package.yml`, and run a real GitHub Actions dry run or prerelease publish from that workflow path.
-2. Extend bootstrap coverage beyond the currently automated hosts.
-   Keep `audit-code ensure` and `audit-code install` stable for Codex, Claude Desktop, OpenCode, VS Code / Copilot, and Antigravity, and close the remaining friction gap for hosts that still lack a verified repo-local install surface.
-3. Polish provider-assisted UX.
-   Keep the new continuation path explicit and inspectable while improving failure hints, host guidance, and operator recovery when a provider bridge misbehaves.
-
-## Nice-To-Have Follow-On Work
-
-- expand host-specific setup guides once the first native integration lands
-- keep release smoke coverage and contract tests fast enough to stay in the publish gate
-- keep `docs/production-launch-bar.md` aligned with the real verification and support surface
-- preserve the packaged prompt asset and `audit-code prompt-path` as hard compatibility guarantees
-
-## Related Docs
-
-- `docs/next-steps.md`
-- `docs/packaging.md`
-- `docs/agent-integrations.md`
-- `docs/production-launch-bar.md`