audit-tools 0.45.0 → 0.48.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/audit/postinstall.mjs

@@ -63,7 +63,9 @@ const OPENCODE_AUDIT_BASH_PERMISSION = {
 // Resolved best-effort: on a fresh workspace checkout the shared dist may not
 // be built yet, in which case the OpenCode config deployment below is
 // skipped with a warning instead of failing the whole install.
-const sharedOpenCodePermissions = await resolveSharedOpenCodePermissions();
+const sharedOpenCodePermissions = /** @type {NonNullable<Awaited<ReturnType<typeof resolveSharedOpenCodePermissions>>>} */ (
+  await resolveSharedOpenCodePermissions()
+);
 
 // A pre-hardening deploy wrote agent-scope bash['*']='allow' (the historically
 // managed broad value). Migrate exactly that value away so the generated 'ask'
@@ -312,7 +314,7 @@ try {
   console.log(`audit-code: restart Claude Desktop for /audit-code to appear in the slash-command menu`);
   counts.succeeded++;
 } catch (err) {
-  console.warn(`audit-code: could not install Claude Desktop plugin (${err.message})`);
+  console.warn(`audit-code: could not install Claude Desktop plugin (${/** @type {any} */ (err).message})`);
   console.warn(`  Plugin directory: ${claudePluginDir}`);
   counts.failed++;
 }

package/scripts/postinstall.mjs

@@ -63,7 +63,7 @@ async function manageArtifactGitignore() {
     }
   } catch (err) {
     console.warn(
-      `[audit-tools] postinstall: .gitignore management skipped (${err?.message ?? err}).`,
+      `[audit-tools] postinstall: .gitignore management skipped (${/** @type {any} */ (err)?.message ?? err}).`,
     );
   }
 }

package/scripts/remediate/postinstall.mjs

@@ -84,7 +84,9 @@ function withoutRetiredRemediateCodeBashRules(rule) {
 // Resolved best-effort: on a fresh workspace checkout the shared dist may not
 // be built yet, in which case the OpenCode config deployment below is
 // skipped with a warning instead of failing the whole install.
-const sharedOpenCodePermissions = await resolveSharedOpenCodePermissions();
+const sharedOpenCodePermissions = /** @type {NonNullable<Awaited<ReturnType<typeof resolveSharedOpenCodePermissions>>>} */ (
+  await resolveSharedOpenCodePermissions()
+);
 
 // A pre-hardening deploy wrote agent-scope bash['*']='allow' (the historically
 // managed broad value). Migrate exactly that value away so the generated 'ask'

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);
 }
@@ -104,7 +107,7 @@ export function runInstalls(toolName, installs, counts) {
       console.log(`${toolName}: ${action} global ${install.label} at ${install.path}`);
       counts.succeeded++;
     } catch (err) {
-      console.warn(`${toolName}: could not install global ${install.label} (${err.message})`);
+      console.warn(`${toolName}: could not install global ${install.label} (${/** @type {any} */ (err).message})`);
       console.warn(`  To install manually, copy from:`);
       console.warn(`    ${install.sourcePath}`);
       console.warn(`  to:`);
@@ -123,6 +126,10 @@ export function runInstalls(toolName, installs, counts) {
  * historically worded this differently). `manualInstructions`, if given, is
  * an array of extra warn lines printed on failure only.
  */
+/**
+ * @param {{toolName: string, path: string, sharedOpenCodePermissions: any, buildMerged: Function, label: string, manualInstructions?: string[]}} options
+ * @param {{succeeded: number, failed: number}} counts
+ */
 export function installOpenCodeGlobalConfig(
   { toolName, path, sharedOpenCodePermissions, buildMerged, label, manualInstructions },
   counts,
@@ -142,7 +149,7 @@ export function installOpenCodeGlobalConfig(
     console.log(`${toolName}: ${action} global ${label} in ${path}`);
     counts.succeeded++;
   } catch (err) {
-    console.warn(`${toolName}: could not install global ${label} (${err.message})`);
+    console.warn(`${toolName}: could not install global ${label} (${/** @type {any} */ (err).message})`);
     for (const line of manualInstructions ?? []) console.warn(line);
     counts.failed++;
   }
@@ -172,7 +179,7 @@ export function installAntigravityPlugin(
     console.log(`${toolName}: ${skillAction} Antigravity plugin skill at ${antigravityPluginSkillPath}`);
     counts.succeeded++;
   } catch (err) {
-    console.warn(`${toolName}: could not install Antigravity plugin (${err.message})`);
+    console.warn(`${toolName}: could not install Antigravity plugin (${/** @type {any} */ (err).message})`);
     counts.failed++;
   }
 }

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-build.mjs

@@ -32,7 +32,7 @@ function resolveSpawn(command, args) {
 }
 
 function runBuild(command, args) {
-  return new Promise((resolvePromise, rejectPromise) => {
+  return /** @type {Promise<void>} */ (new Promise((resolvePromise, rejectPromise) => {
     const resolved = resolveSpawn(command, args);
     const child = spawn(resolved.command, resolved.args, {
       cwd: repoRoot,
@@ -50,7 +50,7 @@ function runBuild(command, args) {
       }
       rejectPromise(new Error(`Command failed with exit code ${code}.`));
     });
-  });
+  }));
 }
 
 export async function shouldBuildDistForPaths({
@@ -120,7 +120,7 @@ async function acquireBuildLock() {
       process.stderr.write(JSON.stringify({ event: "build_lock_acquired", pid: process.pid, lock: buildLockPath, acquired_at: acquiredAt }) + '\n');
       return handle;
     } catch (error) {
-      if (error && error.code === 'EEXIST') {
+    if (error && /** @type {any} */ (error).code === 'EEXIST') {
         try {
           const lockStats = await stat(buildLockPath);
           if (Date.now() - lockStats.mtimeMs > BUILD_LOCK_MAX_AGE_MS) {

package/wrapper/audit-code-wrapper-install-hosts.mjs

@@ -404,7 +404,7 @@ export function buildHostCatalog({ root, host, assets }) {
         steps: definition.steps,
       };
     })
-    .filter(Boolean)
+    .filter((entry) => entry !== null)
     .map((entry) => ({
       ...entry,
       primary_path: entry.primary_path,
@@ -882,9 +882,9 @@ export async function verifyInstalledBootstrap(argv) {
     return;
   }
 
-  const assetPaths = installManifest.asset_paths ?? {};
+  const assetPaths = /** @type {any} */ (installManifest).asset_paths ?? {};
   const hostCatalog = new Map(
-    (installManifest.hosts ?? []).map((entry) => [entry.host, entry]),
+    (/** @type {any} */ (installManifest).hosts ?? []).map((entry) => [entry.host, entry]),
   );
   const selectedHosts = requestedHost && requestedHost !== 'all'
     ? getInstallHostKeys(requestedHost)

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',
@@ -270,6 +335,7 @@ async function runDistCommandInline(commandName, argv, { ensureArtifactsDir = fa
   await cli.runCli([process.execPath, distCliEntry, commandName, ...commandArgs]);
 }
 
+/** @param {{usageName: string, argv?: string[], preferredEntrypoint?: string}} options */
 export async function runAuditCodeWrapper({
   usageName,
   argv = process.argv.slice(2),