audit-tools 0.52.3 → 0.52.5

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

@@ -44,13 +44,31 @@ Each `next-step` invocation writes:
 Follow only the returned prompt. A review handoff also writes a versioned host
 workload and result-map path under `.audit-tools/audit/`. Result ingestion binds
 every result to its run, work item and prompt and verifies it before state
-advances; the full check set is the generated block in
+advances; the mechanical check set is the generated block in
 [`contracts.md`](contracts.md). Replaying an already accepted result is a no-op.
 
 There are no provider, model, routing, quota, context-window, worker-command, or
 headless-launch settings in audit-tools. Parallelism and concrete execution
 choices belong to the host runtime.
 
+## Functional preflight and review context
+
+The first audit `next-step` emits a `functional_preflight` prompt with the exact
+report path and current run identity. The host records source and relationship
+inspection it actually performed. Installed tool names alone do not establish
+capability. Both capabilities permit `ready`; unavailable source inspection
+requires `stop`. Limited relationship inspection permits `degraded` only with an
+explicit operator decision and a concrete limitation carried into the audit report.
+A missing or stale declaration does not permit semantic work, including through
+direct ingestion or recovery commands. Follow the emitted prompt rather than
+inventing capability fields or reusing another run's declaration.
+
+Some review lanes require an independent context. Their prompts specify a bound
+review envelope and output path; ordinary work items retain their normal result
+contract. Unavailable required review pauses instead of silently becoming self-review.
+A declaration describes the host's context, not verified reviewer identity. See
+[semantic review submissions](contracts.md#semantic-review-submissions).
+
 ## Backend fallback
 
 From the target repository root:
@@ -125,9 +143,46 @@ Durable external-analyzer choices live separately at:
 .audit-tools/audit/analyzer-policy.json
 ```
 
-That strict artifact may contain `analyzers` resolution choices and
-`analyzer_consent` decisions. Per-run consent tokens are deliberately not
-persistable.
+That strict artifact retains `analyzers` resolution choices, not standing
+permission to install or run analyzers. Grants and declines apply only to the
+current audit, recorded in its tool-owned `run-consent.json`. Resume keeps that
+run's decisions; a fresh run asks again. Legacy `analyzer_consent` entries are
+ignored as authorization. Transient consent tokens are never persisted.
+
+Audits leave source bytes unchanged by default. Formatting requires explicit
+per-run `next-step --auto-fix` approval. Once `--dry-run` is selected, formatting
+stays disabled for the rest of that run, even when later continuations omit it.
+
+## Remediation control and verification
+
+From the target repository, the host can use:
+
+```bash
+remediate-code next-step --plan-only
+remediate-code pause
+remediate-code resume
+remediate-code cancel
+```
+
+Plan-only completes planning and persists a pause before implementation dispatch.
+Pause preserves the current phase, accepted work and workload binding; resume
+continues from that live state. Cancel is terminal for the current run and
+preserves its work and diagnostics. Follow the emitted continuation after each
+command; pause and cancel are not cleanup commands.
+
+Remediation runs the target repository's declared build, typecheck, lint and test
+commands at verification boundaries. If no executable verification is available,
+the workflow asks for a command or a stop instead of reporting success. An approved
+`next-step --verification-command <command>` supplies the test command without
+silently dropping other declared checks.
+
+To request independent per-result contract conformance review, set
+`conformance_review: true` in the confirmed intent checkpoint before the first
+implementation handoff. It is off by default. The tool binds that choice to the
+run; successful landed and no-change outcomes then require the bound review after
+mechanical checks. Changed result or contract content invalidates the review.
+Insufficient evidence requests repair; unavailable independent review pauses.
+Accepted review declarations survive closeout in the outcomes and report.
 
 ## Generated deliverables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audit-tools",
-  "version": "0.52.3",
+  "version": "0.52.5",
   "private": false,
   "license": "ISC",
   "description": "Provider-neutral code auditing and remediation workflows for arbitrary repositories.",
@@ -53,8 +53,8 @@
     "test": "npm run build && node scripts/shared/run-vitest-gate.mjs",
     "test:single": "npm run build && node scripts/shared/run-vitest-gate.mjs",
     "verify:guards": "node scripts/shared/run-vitest-gate.mjs --retry=2 --exclude \"**/audit-code-completion-*.test.ts\" --exclude \"**/audit-code-wrapper-*.test.ts\" --exclude \"**/audit/next-step-core-*.test.ts\" --exclude \"**/seam-host-only-next-step.test.ts\" --exclude \"**/*-e2e.test.*\" --exclude \"**/next-step-implement-dispatch.test.ts\" --exclude \"**/next-step-pipeline-dispatch.test.ts\"",
-    "verify:checks": "node scripts/shared/profile-run.mjs verify-checks check:control-bytes check:shared-primitives check:agents-region check:loader-fragments check:version-gates check:guard-reach check:guard-reach-paths check:pin-obligations check:sites-pinned check:contract-sites check:generated-artifacts check:invariant-glossary check:nightly-inbox check:ci-trigger-paths check:loop-core-patterns check:loop-core-closure check:constitutional-doc-paths check:runtime-artifact-names check:friction-categories check:executor-producers check:spec-mirrors check:cli-surface check:ingestion-checks check:deadcode check:orphan-modules check:lint check:dup check:depgraph check:doc-manifest check:doc-links check:doc-code-citations check:philosophy-brief check:readme-sample-report check:proposal-red-at check:handoff-roadmap check:retired-infrastructure check:backlog-index check:memory-citations check:review-routing check:doc-test-consumers check:backlog-budget check:backlog-status check:backlog-line-numbers check:backlog-friction-tags check:tests build check:scripts verify:hosts verify:remediate-hosts pack:smoke smoke:packaged-audit-code smoke:packaged-remediate-code smoke:remediate-gate",
-    "verify:release": "npm run verify:checks && node scripts/shared/run-vitest-gate.mjs && npm run smoke:linked-audit-code && npm run smoke:linked-remediate-code",
+    "verify:checks": "node scripts/shared/profile-run.mjs verify-checks --catalog=checks",
+    "verify:release": "node scripts/shared/profile-run.mjs verify-release --catalog=release",
     "check:control-bytes": "node scripts/check-control-bytes.mjs",
     "check:shared-primitives": "node scripts/check-shared-primitives.mjs",
     "check:agents-region": "node scripts/check-agents-region.mjs",
@@ -97,7 +97,6 @@
     "check:loop-core-patterns": "node scripts/shared/generate-loop-core-patterns.mjs --check",
     "check:backlog-budget": "node scripts/check-backlog-budget.mjs",
     "check:review-routing": "node scripts/check-review-routing.mjs",
-    "check:doc-test-consumers": "node scripts/check-doc-test-consumers.mjs",
     "check:memory-citations": "node scripts/check-memory-citations.mjs",
     "check:version-gates": "node scripts/check-version-gates.mjs",
     "check:constitutional-doc-paths": "node scripts/shared/generate-constitutional-doc-paths.mjs --check",
@@ -120,7 +119,8 @@
     "check:pin-obligations": "node scripts/check-pin-obligations.mjs",
     "check:contract-sites": "node --import tsx/esm scripts/check-contract-sites.mjs",
     "check:sites-pinned": "node scripts/check-sites-pinned.mjs",
-    "check:guard-reach-paths": "node scripts/shared/generate-guard-reach-paths.mjs --check"
+    "check:guard-reach-paths": "node scripts/shared/generate-guard-reach-paths.mjs --check",
+    "check:backlog": "node scripts/check-backlog.mjs"
   },
   "engines": {
     "node": ">=22"

package/remediate-code.mjs

@@ -5,9 +5,8 @@
 // to dist/remediate/index.js.
 
 import { fileURLToPath } from "url";
-import { pathToFileURL } from "url";
 import { dirname, join } from "path";
-import { existsSync, readdirSync, statSync } from "fs";
+import { existsSync, readdirSync, statSync, realpathSync } from "fs";
 import { spawnSync } from "child_process";
 
 // The installer (B2) is imported LAZILY inside main() only when an install verb
@@ -190,7 +189,21 @@ export async function main(argv = process.argv.slice(2)) {
   applyWrapperExitAction(getWrapperExitAction(result));
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+// sites-pinned: tests/remediate/remediate-code.test.ts
+// npm's POSIX bin is a symlink. Node resolves the module URL, but argv[1]
+// retains the bin path; compare filesystem identities while keeping imports inert.
+function invokedDirectly() {
+  try {
+    return process.argv[1] != null &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR")) return false;
+    throw error; // unexpected filesystem failures must not become a silent CLI success
+  }
+}
+
+if (invokedDirectly()) {
   main().catch((error) => {
     console.error(error?.stack ?? String(error));
     process.exit(1);

package/skills/audit-code/audit-code.prompt.md

@@ -26,49 +26,19 @@ Preserve user arguments:
   Pass the user-supplied target directory with `--root <path>` only when running
   from outside that repository.
 
-This target-directory rule is one shared fragment, rendered into this body and
-the `remediate-code` loader body in the same words; both skills point here
-instead of restating it.
-
 Ask for exactly one step:
 
 ```bash
 audit-code next-step
 ```
 
-Immediately after this first response, before following its workload prompt or
-calling `next-step` again, perform a host-side structural-capability preflight.
-Confirm that working tools can inspect the structural graph/relationships and
-source structure required for the audit. An installed tool name or an unavailable
-server is not evidence of capability. This check belongs to the host; do not add
-provider, routing, model, or machine-capability fields to audit-tools.
-
-If that capability is unavailable, state the concrete limitation and explicitly
-say the audit is degraded/non-comprehensive. Stop before critical-flow analysis,
-charter work, contract or conceptual review, per-file review, or writing semantic
-results. Do not defer the notice until a report is written or silently substitute
-source-only review for a comprehensive request. A user-chosen quick/shallow audit
-may proceed with the stated limitation and the reflection required below.
-
 Read the returned JSON only far enough to find `prompt_path`, then read and
 follow only that prompt. Do not inspect workload, result, schema, or state files
 unless the current prompt directs you to them.
 
 When the prompt emits semantic review items, assign them with the host's native
 subagent facilities when available. Do not send provider, model, quota,
-context-window, routing, or launch configuration to audit-tools. If the user has
-chosen a degraded quick/shallow run, record one reserved AgentReflection with task_id exactly
-`audit-capability-preflight`. Every reflection requires all three of `task_id`,
-`instruction_clarity` (one of `clear`, `mostly_clear`, `ambiguous`, `unclear`)
-and `severity`; a line missing any of the three is discarded whole. Append each
-reflection as one JSON object per line to the run's agent-reflection file, whose
-path the step contract supplies as `artifact_paths.agent_feedback` — never
-reproduce that filename from memory, because a wrongly named file is read as
-"no reflections" rather than reported. Use severity
-`high` or `critical` when material to claimed coverage, with concrete
-`tool_friction`, `ambiguities`, and `suggestions` details. A structurally incapable run must not be labelled comprehensive. Keep
-the conversation-first flow and loader contract; do not add provider, routing,
-model, or machine-capability fields to audit-tools. Write the
+context-window, routing, or launch configuration to audit-tools. Write the
 prompt-bound result artifacts exactly where requested and let the next backend
 step validate and ingest them.
 

package/skills/remediate-code/remediate-code.prompt.md

@@ -21,12 +21,18 @@ Preserve user arguments:
   root from the working directory on its own, so normal usage passes no `--root`.
   Pass the user-supplied target directory with `--root <path>` only when running
   from outside that repository.
-- pass an existing path with `--input <path>`; write conversational feedback to a
-  temporary file and pass it with `--guidance-file <path>`.
-
-The target-directory rule above is one shared fragment, rendered into this body
-and the `audit-code` loader body in the same words; both skills point at the
-loader bodies instead of restating it.
+- pass an existing path with `--input <path>`; pass conversational feedback directly
+  with `--guidance <text>`. The tool creates and selects its intake file. Use
+  `--guidance-file <path>` only for an existing guidance document.
+
+Honor operator lifecycle intent through the backend: for “plan only,” add
+`--plan-only` to `next-step`; planning will finish at a persisted pause before
+implementation. For an explicit pause, resume, or cancellation request, run
+`remediate-code pause`, `remediate-code resume`, or `remediate-code cancel`, then
+follow its returned `prompt_path`. Do not resume a paused run without the
+operator asking, or advance a cancelled run. Optional `--worktree <path>` and
+`--outcome <text>` record host-reported context only; they never authorize branch
+creation, deletion, or cleanup.
 
 Then ask for exactly one step: