audit-tools 0.30.7 → 0.30.9

package/README.audit.md

@@ -1,222 +0,0 @@
-# audit-code
-
-Skill-first audit orchestration backend for the `/audit-code` product surface.
-
-## Canonical Product Route
-
-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
-
-## Conversation Setup
-
-The canonical asset for editor and conversation integrations is:
-
-`skills/audit-code/audit-code.prompt.md`
-
-Packaged installs and repository checkouts both ship that prompt asset.
-
-The intended user install is one global tool install:
-
-```bash
-npm install -g audit-tools
-```
-
-That makes `audit-code` available on `PATH`. During package install, the package
-also writes user-level command/skill assets for hosts we can seed safely, including
-the Claude command file, the global Codex skill bundle with `audit-code` display
-metadata, and the global OpenCode slash command entry in
-`~/.config/opencode/opencode.json`.
-
-After that, invoke `/audit-code` in a supported host. The prompt self-bootstraps
-the current repository by running:
-
-```bash
-audit-code ensure --quiet
-```
-
-That command writes or refreshes the repo-local assets only when they are missing
-or stale, then normal audit execution continues without manual paths, provider
-flags, or model-selection arguments.
-
-The explicit repair and compatibility setup path remains:
-
-```bash
-audit-code install
-```
-
-That bootstraps repo-local supporting surfaces for the hosts we can automate today, including:
-
-- Codex `AGENTS.md` fallback guidance for the global skill surface
-- Claude Desktop local MCP bundle artifacts and project template guidance
-- OpenCode `opencode.json` with auditor agent and permission wiring; the `/audit-code` command stays in the global npm-installed OpenCode config
-- VS Code prompt, custom agent, Copilot instructions, and `.vscode/mcp.json`
-- Antigravity planning-mode guidance plus the shared repo-local MCP launcher
-
-`audit-code ensure` refreshes those files automatically when the packaged prompt
-or skill changes. Use `audit-code install` or `audit-code ensure --force` when
-you intentionally want to rewrite every generated host surface on demand.
-
-After bootstrap, you can smoke-test the generated host assets and launcher from the repository root:
-
-```bash
-audit-code verify-install
-```
-
-After that, open a supported conversation surface in the repository and invoke `/audit-code`.
-
-If a host still needs manual prompt import after bootstrap, open:
-
-```text
-.audit-code/install/GETTING-STARTED.md
-```
-
-That repo-local guide now includes dedicated quick-start sections for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity, plus the installed canonical prompt asset path for prompt-import fallback flows.
-
-For narrower compatibility, `audit-code install-host --host copilot` still exists.
-
-For hosts that still need manual import after bootstrap, or for environments with no repo-local install surface, after installing the package or checking out the repository, use:
-
-```bash
-audit-code prompt-path
-```
-
-Import the reported file into your editor or conversation environment's custom prompt configuration, then invoke `/audit-code` in conversation.
-
-Typical examples include custom instructions, `.cursorrules`, prompt libraries, or comparable editor-specific prompt surfaces.
-
-## Repo-Local Backend Fallback
-
-The CLI in this repository is backend infrastructure and a repo-local fallback surface.
-
-The conversation step engine used by `/audit-code` — the single execution loop —
-runs from the target repository root:
-
-```bash
-audit-code next-step
-```
-
-Repository-local equivalent:
-
-```bash
-node /path/to/audit-tools/audit-code.mjs next-step
-```
-
-This advances deterministic audit state one bounded step, writes
-`.audit-tools/audit/steps/current-step.json` and
-`.audit-tools/audit/steps/current-prompt.md`, auto-builds `dist/` if it is
-missing, and creates the artifacts directory automatically. Hosts follow only
-the returned step prompt, then call `next-step` again. A bare `audit-code`
-invocation prints usage; there is no implicit batch loop.
-
-Explicit root override still exists for callers running from outside the target repository:
-
-```bash
-audit-code next-step --root /path/to/repo
-```
-
-For one bounded debug advance that prints the execution envelope
-(`contract_version: "audit-code/v1alpha1"`) instead of a step contract:
-
-```bash
-audit-code advance-audit
-```
-
-For an operator-side artifact consistency check:
-
-```bash
-audit-code validate
-```
-
-That check now covers the artifact bundle plus `session-config.json` and explicit provider readiness.
-
-For native batch ingestion of multiple result files during a debug advance:
-
-```bash
-audit-code advance-audit --batch-results /path/to/audit-results-dir
-```
-
-For task-to-coverage inspection without reverse-engineering multiple artifacts:
-
-```bash
-audit-code explain-task <task_id>
-```
-
-To remove a leftover `.audit-tools/audit/` directory from an interrupted or
-crashed audit:
-
-```bash
-audit-code cleanup
-audit-code cleanup --dry-run   # preview without deleting
-audit-code cleanup --force     # delete even if state is unknown
-```
-
-Refuses to delete if the audit state is `active` or `blocked` (resumable).
-Pass `--force` when `audit_state.json` is missing (crashed run).
-
-The backend wrapper response schema is `schemas/audit-code-v1alpha1.schema.json`.
-
-## Backend Provider Modes
-
-If `provider` is omitted, the backend defaults to the safest mode:
-
-```json
-{
-  "provider": "local-subprocess"
-}
-```
-
-If you want best-effort cross-editor or provider routing, opt into:
-
-```json
-{
-  "provider": "auto",
-  "ui_mode": "visible"
-}
-```
-
-Optional backend config:
-
-`.audit-tools/audit/session-config.json`
-
-## Practical Guidance
-
-- use `/audit-code` in conversation as the canonical product surface
-- install once with `npm install -g audit-tools`, then let `/audit-code` run `audit-code ensure --quiet` in each repository
-- use `audit-code install` when you want to repair or force-refresh repo-local host assets
-- use `audit-code prompt-path` to locate the packaged prompt asset
-- use `audit-code` from the repository root only when you need the repo-local backend fallback
-- use omitted provider or `local-subprocess` for the safest deterministic fallback behavior
-- use `provider: "auto"` only when you want best-effort routing across installed backends
-- treat explicit provider bridges as compatibility fallback, not as the intended owner of semantic review
-
-## Build And Test
-
-```bash
-npm install
-npm run test:single -- tests/audit/next-step.test.mjs
-npm run verify:release
-npm run release:patch
-npm run release:patch:publish
-```
-
-When developing from a fresh clone or git worktree, run repo-root `npm install`
-before package checks. Missing `node_modules` can cause misleading type errors.
-
-For GitHub Actions publication and npm Trusted Publishing setup, see `docs/audit-pkg/release.md`.
-
-## Key Docs
-
-- `docs/audit-pkg/product.md`
-- `docs/audit-pkg/operator-guide.md`
-- `docs/audit-pkg/contracts.md`
-- `docs/audit-pkg/release.md`
-- `docs/audit-pkg/development.md`
-- `docs/history.md`
-- `skills/audit-code/SKILL.md`

package/README.remediate.md

@@ -1,112 +0,0 @@
-# remediate-code
-
-Conversation-first remediation orchestrator for arbitrary repositories. It
-accepts the auditor's `audit-findings.json` (the deterministic machine contract)
-from [audit-code](https://github.com/OhOkThisIsFine/audit-tools), an
-`audit-report.md` or other feedback document (LLM-extracted), or conversational
-feedback — then advances through one backend-rendered step prompt at a time.
-
-## Primary Usage
-
-```bash
-npm install -g audit-tools
-```
-
-Then start from a conversation:
-
-```text
-/remediate-code path/to/audit-findings.json
-```
-
-You can also start with free-form feedback:
-
-```text
-/remediate-code clean up the auth flow and make the session refresh behavior easier to test
-```
-
-The global loader runs `remediate-code ensure --quiet`, then
-`remediate-code next-step`, reads only the returned `prompt_path`, and follows
-that one prompt. Each prompt carries its own allowed commands and stop
-condition.
-
-If the starting point is not already a structured auditor report, the backend
-first creates an intake brief from the supplied document(s) or conversational
-feedback. It asks for clarification when the goals, non-goals, affected areas,
-or success criteria are ambiguous. The normal remediation workflow starts only
-after that brief is clear enough to convert into bounded findings.
-
-## Runtime Artifacts
-
-Active runs use `.audit-tools/remediation/` in the target repository. The current
-state is `.audit-tools/remediation/state.json`, and the current step contract is
-written to:
-
-- `.audit-tools/remediation/steps/current-step.json`
-- `.audit-tools/remediation/steps/current-prompt.md`
-
-After close, the durable outputs are written to `.audit-tools/`:
-
-- `remediation-report.md`
-- `remediation-outcomes.json`
-- `remediation-closing-result.json`
-
-## Development From Source
-
-The global `npm install -g audit-tools` path is for users. For repository
-development in a fresh clone or git worktree, run `npm install` at the repo root
-before build, check, or test workflows.
-
-## CLI
-
-| Command | Description |
-| --- | --- |
-| `remediate-code next-step [--input <path>] [--host-can-dispatch-subagents]` | Decide and render exactly one next action |
-| `remediate-code prepare-implement-dispatch --run-id <id>` | Write bounded implementation prompts |
-| `remediate-code merge-implement-results --run-id <id>` | Validate implementation results and update item state |
-| `remediate-code validate-artifacts` | Validate runtime artifacts |
-| `remediate-code install` | Deprecated alias that repairs global assets and writes no repo-local host files |
-| `remediate-code ensure [--quiet]` | Repair/check global Claude, Codex, and OpenCode assets |
-
-`next-step` is the single canonical execution path. Hosts and IDEs should call
-it repeatedly, read the returned `prompt_path`, follow that one prompt, and then
-call `next-step` again only when the prompt says to continue.
-
-## Auditor Compatibility
-
-The auditor's canonical `audit-findings.json` is parsed **deterministically** —
-findings, work-block assignments, and synthesis themes are adopted verbatim, with
-no LLM involved. A Markdown `audit-report.md` (or any other free-form or partial
-document) is instead routed through intake synthesis and bounded LLM finding
-extraction, so it cannot silently produce a zero-finding plan. The deterministic
-contract is locked by `tests/fixtures/auditor-contract-audit-findings.json`,
-regenerated with `npm run fixtures:auditor-contract` from audit-code's
-findings renderer.
-
-## Intake
-
-The remediator can start from any of these inputs:
-
-- a structured auditor report
-- one or more feedback or planning documents
-- conversational feedback typed directly after `/remediate-code`
-- a mix of documents and conversation
-
-Runtime intake artifacts live under `.audit-tools/remediation/intake/`:
-
-- `source-manifest.json`
-- `conversation-start.md`
-- `intake-summary.json`
-- `intake-clarifications.json`
-- `remediation-brief.md`
-
-Structured auditor reports skip intake and go directly to planning. All other
-starting points go through synthesis first, and ambiguous requests pause for a
-single batched clarification before findings are extracted.
-
-## Closing
-
-The default closing action is `none`. Actions such as `commit`, `push`,
-`open-pr`, `publish`, `tag`, and `custom` record command exit codes and captured
-output in `remediation-closing-result.json`; reports only claim success after
-the command succeeds. Closing is advanced by a generated `next-step` finalization
-command, not the broad compatibility `run` loop.