audit-tools 0.44.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": [
@@ -101,7 +105,7 @@
               "config_deployment",
               "observability"
             ],
-            "description": "Optional: defaults from the enclosing AuditResult lens when omitted."
+            "description": "defaults from the enclosing AuditResult lens when omitted."
           },
           "summary": {
             "type": "string"

package/schemas/audit_results.schema.json

@@ -45,6 +45,10 @@
             "total_lines": {
               "type": "integer",
               "minimum": 0
+            },
+            "reviewed_lines": {
+              "type": "integer",
+              "minimum": 0
             }
           },
           "required": [
@@ -103,7 +107,7 @@
                 "config_deployment",
                 "observability"
               ],
-              "description": "Optional: defaults from the enclosing AuditResult lens when omitted."
+              "description": "defaults from the enclosing AuditResult lens when omitted."
             },
             "summary": {
               "type": "string"

package/schemas/finding.schema.json

@@ -47,7 +47,7 @@
         "config_deployment",
         "observability"
       ],
-      "description": "Optional: defaults from the enclosing AuditResult lens when omitted."
+      "description": "defaults from the enclosing AuditResult lens when omitted."
     },
     "summary": {
       "type": "string"

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,15 +249,17 @@ 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',
     '- ingest-results --results FILE validates and ingests canonical AuditResult payloads',
+    '- unaccept-results --work-item <id> (repeatable) or --all removes entries from the accepted host-results pair so a poisoned acceptance can be re-ingested after repair',
     '- status summarizes deterministic audit state and pending review work',
     '',
     'Defaults:',

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)}`);
 }