fix(scanners): a target path that does not exist is an error, not a grade

Surfaced by the router dogfood: quoting the placeholder stopped the shell from
swallowing it, which moved the failure down into the CLIs — and revealed that
most of them never check the target at all. Measured:

  node scanners/posture.mjs /nonexistent/path/xyz --output-file …
  exit 0
  Health: B (86/100) — Good shape — a few items to address

Nothing in that output distinguishes it from a real audit: well-formed
envelope, all 10 areas present, 16 opportunities reported. A typo'd path did
not fail — it flattered.

Exit 3 is the right code by the plugin's own contract: 0/1/2 are PASS/WARNING/
FAIL about a configuration that WAS examined, and every command template gates
on exactly that distinction, so a bad path flowed through the whole workflow as
a clean result.

This was a consistency gap, not a design question. Measured across the nine
target-taking CLIs, four already did it right with the same message and the
same exit code (manifest, token-hotspots-cli, whats-active, optimize-lens-cli);
five did not (scan-orchestrator and drift-cli exit 1, posture,
plugin-health-scanner and fix-cli exit 0). The five now share
lib/require-target-dir.mjs, which carries that exact behaviour. The four with
inline copies are left alone — consolidating them is a cleanup, not part of
this fix.

The guard is asserted over ALL nine CLIs, so a new one cannot join the wrong
half, and a third case is covered: a target that exists but is a regular file.
A valid target — including an empty directory — is explicitly unaffected.

Suite 1483 -> 1486, frozen v5.0.0 snapshots untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YDAwy1ZXRpZxht1wyCeSbF

scanners/lib/require-target-dir.mjs

@@ -0,0 +1,49 @@
+/**
+ * Target-path precondition shared by the target-taking CLIs.
+ *
+ * A scan target is a scan ROOT. If it does not exist, or is not a directory,
+ * the scanner cannot do its job — and by the plugin's exit-code contract that
+ * is exit 3, not a verdict. Codes 0/1/2 are PASS/WARNING/FAIL *about a
+ * configuration that was examined*; every command template gates on exactly
+ * that distinction, so returning a verdict for an unreadable target sends a
+ * typo'd path through the whole workflow as a clean result.
+ *
+ * Measured before this guard existed (session #56):
+ *   node scanners/posture.mjs /nonexistent/path/xyz  →  exit 0,
+ *   "Health: B (86/100) — Good shape — a few items to address"
+ *
+ * The message and exit code here are not new: `manifest.mjs`,
+ * `token-hotspots-cli.mjs`, `whats-active.mjs` and `optimize-lens-cli.mjs`
+ * already carried this exact block inline. This module is where the CLIs that
+ * lacked it get it from; the four that have their own copies are left alone
+ * (consolidating them is a cleanup, not part of this fix).
+ */
+
+import { stat } from 'node:fs/promises';
+
+/**
+ * Verify that `absPath` is an existing directory.
+ *
+ * Writes the diagnostic to stderr itself, so callers stay a two-line guard:
+ *
+ *   if (!(await requireTargetDir(resolvedPath))) { process.exitCode = 3; return; }
+ *
+ * Never throws, and never calls `process.exit()` — an abrupt exit discards
+ * unflushed stdout when the CLI is on a pipe.
+ *
+ * @param {string} absPath - Resolved absolute target path.
+ * @returns {Promise<boolean>} true when the target is usable as a scan root.
+ */
+export async function requireTargetDir(absPath) {
+  try {
+    const s = await stat(absPath);
+    if (!s.isDirectory()) {
+      process.stderr.write(`Error: ${absPath} is not a directory\n`);
+      return false;
+    }
+    return true;
+  } catch {
+    process.stderr.write(`Error: path does not exist: ${absPath}\n`);
+    return false;
+  }
+}