audit-tools 0.45.0 → 0.46.0

package/schemas/audit-code-v1alpha1.schema.json

@@ -0,0 +1,297 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "audit-code-v1alpha1.schema.json",
+  "title": "Audit Code Response",
+  "type": "object",
+  "properties": {
+    "contract_version": {
+      "type": "string",
+      "const": "audit-code/v1alpha1"
+    },
+    "audit_state": {
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "not_started",
+            "active",
+            "blocked",
+            "complete"
+          ]
+        },
+        "last_executor": {
+          "type": "string"
+        },
+        "last_obligation": {
+          "type": "string"
+        },
+        "blockers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "obligations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "state": {
+                "type": "string",
+                "enum": [
+                  "missing",
+                  "present",
+                  "stale",
+                  "blocked",
+                  "satisfied"
+                ]
+              },
+              "reason": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "state"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "status",
+        "obligations"
+      ],
+      "additionalProperties": false
+    },
+    "selected_obligation": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "selected_executor": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "progress_made": {
+      "type": "boolean"
+    },
+    "artifacts_written": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "progress_summary": {
+      "type": "string"
+    },
+    "next_likely_step": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "handoff": {
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "not_started",
+            "active",
+            "blocked",
+            "complete"
+          ]
+        },
+        "repo_root": {
+          "type": "string"
+        },
+        "artifacts_dir": {
+          "type": "string"
+        },
+        "summary": {
+          "type": "string"
+        },
+        "pending_obligations": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "suggested_inputs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "flag": {
+                "type": "string",
+                "enum": [
+                  "--results",
+                  "--batch-results",
+                  "--updates",
+                  "--external-analyzer-results"
+                ]
+              },
+              "suggested_path": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "flag",
+              "suggested_path",
+              "description"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "suggested_commands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "active_review_run": {
+          "type": "object",
+          "properties": {
+            "contract_version": {
+              "type": "string",
+              "const": "audit-review-run/v1alpha1"
+            },
+            "run_id": {
+              "type": "string"
+            },
+            "review_run_path": {
+              "type": "string"
+            },
+            "pending_audit_tasks_path": {
+              "type": "string"
+            },
+            "host_workload_path": {
+              "type": "string"
+            },
+            "host_result_map_path": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "contract_version",
+            "run_id",
+            "review_run_path",
+            "pending_audit_tasks_path",
+            "host_workload_path",
+            "host_result_map_path"
+          ],
+          "additionalProperties": false
+        },
+        "artifact_paths": {
+          "type": "object",
+          "properties": {
+            "operator_inputs_dir": {
+              "type": "string"
+            },
+            "operator_handoff_json": {
+              "type": "string"
+            },
+            "operator_handoff_markdown": {
+              "type": "string"
+            },
+            "session_config": {
+              "type": "string"
+            },
+            "run_ledger": {
+              "type": "string"
+            },
+            "current_review_run": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "current_prompt": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "current_tasks": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "audit_tasks": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "runtime_validation_tasks": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "friction_record": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "operator_inputs_dir",
+            "operator_handoff_json",
+            "operator_handoff_markdown",
+            "session_config",
+            "run_ledger",
+            "current_review_run",
+            "current_prompt",
+            "current_tasks",
+            "audit_tasks",
+            "runtime_validation_tasks",
+            "friction_record"
+          ],
+          "additionalProperties": false
+        },
+        "quick_start": {
+          "type": "string"
+        },
+        "file_map": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "status",
+        "repo_root",
+        "artifacts_dir",
+        "summary",
+        "pending_obligations",
+        "suggested_inputs",
+        "suggested_commands",
+        "artifact_paths"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "contract_version",
+    "audit_state",
+    "selected_obligation",
+    "selected_executor",
+    "progress_made",
+    "artifacts_written",
+    "progress_summary",
+    "next_likely_step"
+  ],
+  "additionalProperties": false
+}

package/schemas/audit_result.schema.json

@@ -43,6 +43,10 @@
           "total_lines": {
             "type": "integer",
             "minimum": 0
+          },
+          "reviewed_lines": {
+            "type": "integer",
+            "minimum": 0
           }
         },
         "required": [

package/schemas/audit_results.schema.json

@@ -45,6 +45,10 @@
             "total_lines": {
               "type": "integer",
               "minimum": 0
+            },
+            "reviewed_lines": {
+              "type": "integer",
+              "minimum": 0
             }
           },
           "required": [

package/scripts/shared/install-host-assets.mjs

@@ -14,14 +14,17 @@ import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 
 /**
  * Read a source file that is required for the install to proceed at all
- * (e.g. the prompt/skill markdown). Missing source is reported as a skip
- * (exitCode reset to 0, not a failure) rather than thrown.
+ * (e.g. the prompt/skill markdown — the product surface itself). A missing
+ * required source is a LOUD failure: it throws so the postinstall exits
+ * non-zero and any failure an earlier step already recorded is never masked
+ * by an exit-code reset here. Only truly optional sources go through
+ * readOptionalSource, which still degrades to a skip.
  */
 export function readRequiredSource(path, label, toolName) {
   if (!existsSync(path)) {
-    console.warn(`${toolName}: ${label} source not found at ${path} - skipping global command install`);
-    process.exitCode = 0;
-    return null;
+    throw new Error(
+      `${toolName}: ${label} source not found at ${path} - required for the install; not skipping silently`,
+    );
   }
   return readFileSync(path);
 }

package/skills/audit-code/SKILL.md

@@ -43,8 +43,10 @@ node audit-code.mjs ensure --quiet
 node audit-code.mjs next-step
 ```
 
-Pass a user-supplied target directory with `--root <path>` on every command. Do
-not add provider, model, quota, routing, or launch flags.
+The target-directory rule has one home — *Preserve user arguments* in the
+`/audit-code` loader prompt, whose absolute path `audit-code prompt-path` prints.
+Follow it as written there. Do not add provider, model, quota, routing, or launch
+flags.
 
 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

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

@@ -21,8 +21,11 @@ repository root.
 
 Preserve user arguments:
 
-- pass a typed target directory with `--root <path>` on every `audit-code`
-  command (`ensure` and each `next-step`)
+- pass the user-supplied target directory with `--root <path>` on every
+  `audit-code` command (`ensure` and each `next-step`)
+
+This is the one full statement of the target-directory rule; the `audit-code`
+skill points here instead of restating it.
 
 Ask for exactly one step:
 

package/skills/audit-code/opencode-command-template.txt

@@ -3,7 +3,7 @@
 Use `audit-code next-step` as the primary interface to the audit workflow.
 
 1. Run `audit-code next-step` directly when shell access is available.
-2. Read `prompt_content` in the response and follow it.
+2. Read the returned JSON far enough to find `prompt_path`, then read and follow the prompt file it points to.
 3. When a step completes (not blocked), run `audit-code next-step` again.
 4. Stop when the step instructions say to stop.
 

package/wrapper/audit-code-wrapper-lib.mjs

@@ -15,7 +15,11 @@ import {
   _getInstallProfile,
   _renderGeminiCommandToml,
 } from './audit-code-wrapper-install-hosts.mjs';
-import { wantsInstallerVerbHelp, installerVerbHelp } from './installer-verb-help.mjs';
+import {
+  wantsInstallerVerbHelp,
+  installerVerbHelp,
+  installerVerbSummaries,
+} from './installer-verb-help.mjs';
 
 export { shouldBuildDistForPaths, assertWorkspaceInstalled };
 export { _INSTALL_HOST_ORDER, _INSTALL_HOST_DEFINITIONS, _getInstallHostKeys, _getInstallProfile, _renderGeminiCommandToml };
@@ -45,24 +49,84 @@ function hasLeadingFlag(argv, name) {
   return false;
 }
 
+// Every occurrence of a flag in an argv, classified by the SAME grammar
+// src/audit/cli/args.ts reads with: an equals token (`--root=/x`) carries its
+// value inline; a bare token (`--root /x`) consumes the FOLLOWING token as its
+// value only when that token exists and is not itself a flag (the mirror of
+// args.ts's isLongFlagToken guard). Reading the dist grammar here is what makes
+// the wrapper's view of "what did the caller pass" agree with what the child
+// will actually act on. Ordered by ascending index; spans never overlap.
+function flagOccurrences(argv, name) {
+  const prefix = `${name}=`;
+  const occurrences = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index].startsWith(prefix)) {
+      occurrences.push({ index, span: 1, inline: true });
+    } else if (argv[index] === name) {
+      const consumesValue =
+        argv[index + 1] !== undefined && !argv[index + 1].startsWith("--");
+      occurrences.push({ index, span: consumesValue ? 2 : 1, inline: false });
+      if (consumesValue) index += 1;
+    }
+  }
+  return occurrences;
+}
+
+// The caller's LAST occurrence is their final word for the flag.
+function lastFlagEntry(argv, name) {
+  const occurrences = flagOccurrences(argv, name);
+  return occurrences[occurrences.length - 1];
+}
+
 function getFlag(argv, name) {
-  const index = argv.indexOf(name);
-  if (index < 0) return undefined;
-  return argv[index + 1];
+  const entry = lastFlagEntry(argv, name);
+  if (!entry) return undefined;
+  return entry.inline ? argv[entry.index].slice(name.length + 1) : argv[entry.index + 1];
 }
 
-// Overwrite an existing flag's value (or append when absent). A fill-only-if-
-// missing default would forward a user-supplied RELATIVE --root/--artifacts-dir
-// raw, re-resolved against the child's cwd (repoRoot), not the caller's cwd —
-// e.g. `--root .` pointed at the package dir (CE-001). Normalizing to an
-// absolute path here makes the forwarded value cwd-stable.
+// Overwrite an existing flag's value or append when absent, ALWAYS emitting the
+// bare two-token form (`--name value`) — the only spelling
+// src/audit/cli/args.ts parses (argv.indexOf, no '=' handling anywhere in
+// src/audit), so forwarding an equals-form token verbatim means dist silently
+// drops it and the CLI default wins — explicit loses, the exact failure class
+// this guards. Every OTHER occurrence (either spelling, including each bare
+// occurrence's consumed value token) is removed, so exactly one canonical
+// occurrence reaches the child and dist's first-match parse cannot land on a
+// stale one. A fill-only-if-missing default would otherwise forward a
+// user-supplied RELATIVE --root/--artifacts-dir raw, re-resolved against the
+// child's cwd (repoRoot), not the caller's cwd — e.g. `--root .` pointed at the
+// package dir (CE-001). Normalizing to an absolute path here makes the
+// forwarded value cwd-stable.
 function setFlag(argv, name, value) {
-  const index = argv.indexOf(name);
-  if (index < 0) {
+  const occurrences = flagOccurrences(argv, name);
+  const kept = occurrences[occurrences.length - 1];
+
+  // Drop the superseded occurrences, highest index first, together with the
+  // value token each bare one consumed.
+  for (let occ = occurrences.length - 2; occ >= 0; occ -= 1) {
+    argv.splice(occurrences[occ].index, occurrences[occ].span);
+  }
+
+  if (!kept) {
     argv.push(name, value);
-  } else {
+    return;
+  }
+
+  // Removed occurrences shifted the kept one left; recompute its index.
+  const removedBefore = occurrences.reduce(
+    (span, occ) => (occ.index < kept.index ? span + occ.span : span),
+    0,
+  );
+  const index = kept.index - removedBefore;
+  if (kept.span === 2) {
+    // Bare with a value slot: overwrite the value in place.
     argv[index + 1] = value;
+    return;
   }
+  // Inline (`--name=x`) or dangling bare: collapse the token to the bare flag
+  // and insert the value after it.
+  argv[index] = name;
+  argv.splice(index + 1, 0, value);
 }
 
 export { hasLeadingFlag, setFlag };
@@ -185,11 +249,12 @@ function printHelp({ usageName, preferredEntrypoint }) {
     '',
     'Helper commands:',
     '- prompt-path prints the absolute path to the canonical /audit-code prompt asset',
-    '- ensure lazily bootstraps repo-local /audit-code assets when they are missing or stale',
-    '- install bootstraps /audit-code into supported repo-local host surfaces',
-    '- verify-install smoke-tests the generated host assets after install',
+    // The four wrapper-intercepted installer verbs are RENDERED from the module
+    // this file already answers `<verb> --help` from, so the listing and the
+    // per-verb help cannot disagree. They were hand-restated here and had
+    // already drifted from it on two of the four.
+    ...installerVerbSummaries('/audit-code'),
     '- mcp starts the local stdio MCP server for repo-local IDE integrations',
-    '- install-host --host copilot keeps the narrower Copilot-focused install path available',
     '- validate checks the current artifact bundle and canonical session intent and exits non-zero when issues exist',
     '- validate-results --results FILE validates AuditResult payloads against the active task manifest without ingesting them',
     '- explain-task <task_id> prints the resolved file coverage and current status for a task id',

package/wrapper/installer-verb-help.mjs

@@ -52,6 +52,18 @@ const VERB_DETAIL = Object.freeze({
   ],
 });
 
+/**
+ * One verb's one-line summary, with `{product}` bound to the slash-command the
+ * bin installs. The accessor exists so the surface can be RENDERED — the docs
+ * that list these verbs read this module rather than restating it, which is how
+ * `docs/audit-pkg/product.md` came to omit two of the four.
+ */
+export function installerVerbSummary(verb, product) {
+  const summary = VERB_SUMMARY[verb];
+  if (summary === undefined) throw new Error(`unknown installer verb: ${verb}`);
+  return summary.replace('{product}', product);
+}
+
 /** True when `verb` is one of the wrapper-intercepted installer verbs. */
 export function isInstallerVerb(verb) {
   return typeof verb === 'string' && INSTALLER_VERBS.includes(verb);
@@ -76,7 +88,7 @@ export function wantsInstallerVerbHelp(argv) {
  * installs (e.g. `/audit-code`); `usageName` is the bin as the caller invoked it.
  */
 export function installerVerbHelp(verb, { usageName, product }) {
-  const summary = VERB_SUMMARY[verb].replace('{product}', product);
+  const summary = installerVerbSummary(verb, product);
   return [
     `Usage: node ${usageName} ${verb} [--root PATH] [--quiet]`,
     '',
@@ -92,7 +104,5 @@ export function installerVerbHelp(verb, { usageName, product }) {
 
 /** The one-line summaries, for a bin's top-level help listing. */
 export function installerVerbSummaries(product) {
-  return INSTALLER_VERBS.map(
-    (verb) => `- ${verb} ${VERB_SUMMARY[verb].replace('{product}', product)}`,
-  );
+  return INSTALLER_VERBS.map((verb) => `- ${verb} ${installerVerbSummary(verb, product)}`);
 }

package/docs/audit-pkg/development.md

@@ -1,113 +0,0 @@
-# Development
-
-## Repository layout
-
-- `src/`: implementation code
-- `schemas/`: JSON schemas for public and internal artifacts
-- `examples/`: validated artifact examples
-- `skills/audit-code/`: canonical prompt and skill-facing instructions
-- `dispatch/`: standalone result validation and merge helpers
-- `tests/`: vitest-based test suite and regression coverage
-- `dist/`: build output (gitignored, not checked in) produced by `npm run build` / the `prepack` script;
-  shipped only in the packed npm tarball
-
-## Agent handoff
-
-Long-term product direction lives in [`product.md`](product.md). Current state + immediate next steps are in
-[`HANDOFF.md`](../HANDOFF.md); open work in [`backlog.md`](../backlog.md). There is no
-shipped-sprint archive — that history lives in git + project memory.
-
-## Build and test
-
-```bash
-npm install
-npm run check
-npm test
-npx vitest run tests/audit/host-handoff.test.ts
-npm run verify:release
-```
-
-Run `npm install` from the repository root before running build, check, test, or
-package-scoped workflows in a fresh clone or git worktree. Missing
-`node_modules` can surface as misleading `audit-tools/shared` export or type
-errors because dependents may resolve stale compiled `dist/` output.
-
-The test suite is intentionally contract-heavy. Update tests when changing
-schema shape, prompt contracts, host-handoff behavior, installer output, or release
-workflow semantics.
-
-## Architecture
-
-The system separates deterministic extraction from bounded LLM judgment: intake, analysis artifacts,
-task planning, provider-neutral host workloads, strict result ingestion, and synthesis into
-`audit-report.md`. Backend/model selection, concurrency, retries, and transport belong to the host and
-are not audit-tools configuration.
-
-**The ordering has one home** — the `PRIORITY` array in `src/audit/orchestrator/nextStep.ts`, walked by
-`decideNextStep`. `src/audit/README.md` carries the conceptual grouping with the disclaimer that `PRIORITY` is
-authoritative; read the array for the real sequence. Copies of it have drifted before, which is why
-neither this file nor any other keeps a second one.
-
-Portability rules:
-
-- tool-specific collectors write tool-agnostic JSON
-- prompts consume artifacts and bounded source context
-- review work is attributable to files, lenses, passes, and tasks
-- coverage gaps are machine-detectable
-
-`AuditTask` is the coverage identity; `AuditResult[]` is the ingestion contract.
-
-## Adding language analyzers
-
-Language support should be adapter-based. A new analyzer should enrich shared
-artifacts instead of inventing a language-specific planning path.
-
-Avoid adding another bespoke manifest or project-file parser by default. First
-ask whether the signal is common in expected repositories, whether it provides
-direction or ownership that path heuristics cannot, and whether the same value
-could come from a generic analyzer-supplied ownership hint.
-
-Preferred outputs:
-
-- graph edges with kind, direction, confidence, and reason
-- entrypoints and surfaces
-- test-to-source links
-- package/module ownership hints, including analyzer-supplied `ownership_roots`
-  that become `analyzer-ownership-root-link` graph references
-- contract-suite links for small JSON Schema, workflow, package-script, or
-  TypeScript type suites when planner metrics show otherwise weak packets
-- external boundary hints
-- line counts and anchor summaries for large files
-
-Keep deep analyzers optional: a repository should still produce useful packets
-from manifests, paths, tests, and external analyzer results when a language has
-only fallback support. Command-backed analyzers should prove project intent
-before running — prefer repo-local config checks (`eslint.config.*`, `.eslintrc*`,
-`package.json` `eslintConfig`) over executing a globally installed tool and
-parsing its no-config failure.
-
-Language-agnostic semantic affinity is useful for ranking adjacent context but
-should stay low-authority: don't let shared token frequency alone force packet
-merges; use it for `boundary_files` or candidate explanations unless a
-deterministic edge corroborates the relationship.
-
-## Production readiness
-
-Drive priorities from field trials, not speculation: run representative
-repositories through planning, validate the bundle (`audit-code validate`), and
-compare `audit_plan_metrics.json` (packet count, weak-packet count, cohesion,
-merge/boundary edge kinds) across runs. Promote an extractor or planner change
-when those metrics expose a deterministic gap — and prefer improving shared
-graph resolution or generic analyzer ownership roots before adding another
-ecosystem-specific parser.
-
-Before treating a build as production-ready, verify the full review loop in one
-real host (`next-step` emits the complete workload → the host writes each bound
-result → `next-step` ingests them → `validate`), then run the release gate from a clean
-checkout (see [`release.md`](release.md) for what `npm run verify:release`
-covers and when to run it). Keep runtime command execution covered when
-changing it — including the Windows package-manager-shim path (see the Windows
-notes in [`operator-guide.md`](operator-guide.md)). If the
-final `audit-report.md` cannot be promoted from `.audit-tools/audit/` to
-`.audit-tools/audit-report.md` due to local permissions, completion still succeeds and the
-pre-promotion copy under `.audit-tools/audit/` is authoritative.