@kontourai/flow-agents 0.1.1

package/src/cli/veritas-governance.ts

@@ -0,0 +1,322 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import { flagBool, flagString, parseArgs } from "../lib/args.js";
+
+type EvidenceStatus = "pass" | "fail" | "not_verified" | "skip";
+type EvidenceVerdict = "pass" | "partial" | "fail" | "not_verified";
+
+type EvidenceCheck = {
+  id: string;
+  kind: "policy";
+  status: EvidenceStatus;
+  command?: string;
+  summary: string;
+  artifact_refs?: EvidenceRef[];
+  standard_refs?: Array<{ standard: "veritas"; ref: string; role: "native"; summary: string }>;
+};
+
+type EvidencePayload = {
+  schema_version: "1.0";
+  task_slug: string;
+  verdict: EvidenceVerdict;
+  checks: EvidenceCheck[];
+  external_evidence?: Array<{ system: "veritas"; ref: EvidenceRef; summary: string; standard: "veritas" }>;
+  not_verified_gaps?: string[];
+};
+
+type EvidenceRef = {
+  kind: "source" | "command" | "artifact" | "provider" | "external";
+  url?: string;
+  file?: string;
+  line_start?: number;
+  line_end?: number;
+  excerpt?: string;
+  summary?: string;
+};
+
+type EvidenceOptions = {
+  artifactDir: string;
+  evidencePath: string;
+  taskSlug: string;
+  veritasBin: string;
+  repoRoot: string;
+  veritasRoot?: string;
+  nativeArtifact?: string;
+  maxAgeSeconds?: number;
+  skip: boolean;
+  notConfigured: boolean;
+};
+
+const OUTPUT_SUMMARY_MAX_BYTES = 2048;
+const OUTPUT_SUMMARY_MAX_LINES = 20;
+const REDACTED = "[REDACTED]";
+
+function usage(): void {
+  console.error(
+    [
+      "usage: flow-agents veritas-governance evidence --artifact-dir DIR [options]",
+      "",
+      "Options:",
+      "  --artifact-dir DIR              Workflow artifact directory containing sidecars.",
+      "  --evidence-path FILE            Evidence sidecar path. Defaults to DIR/evidence.json.",
+      "  --task-slug SLUG                Defaults to state.json task_slug or artifact dir name.",
+      "  --veritas-bin PATH              Veritas executable. Defaults to veritas.",
+      "  --repo-root DIR                 Repository root used as Veritas working directory.",
+      "  --veritas-root DIR              Append --root DIR to the Veritas command.",
+      "  --veritas-artifact FILE         Native Veritas artifact to reference and freshness-check.",
+      "  --max-age-seconds N             Mark the check not_verified when the artifact is stale.",
+      "  --skip                         Record a skipped policy check without invoking Veritas.",
+      "  --not-configured               Record not_verified for an intentionally unconfigured provider.",
+    ].join("\n")
+  );
+}
+
+function readTaskSlug(artifactDir: string, fallback?: string): string {
+  if (fallback) return fallback;
+  const statePath = path.join(artifactDir, "state.json");
+  if (fs.existsSync(statePath)) {
+    const parsed = JSON.parse(fs.readFileSync(statePath, "utf8")) as { task_slug?: string };
+    if (parsed.task_slug) return parsed.task_slug;
+  }
+  return path.basename(path.resolve(artifactDir));
+}
+
+function ensureParent(file: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+}
+
+function commandString(veritasBin: string, veritasRoot?: string): string {
+  return ["veritas", "readiness", "--check", "evidence", "--working-tree", veritasRoot ? `--root ${veritasRoot}` : ""]
+    .filter(Boolean)
+    .join(" ")
+    .replace(/^veritas/, veritasBin);
+}
+
+function artifactEvidenceRef(file: string): EvidenceRef {
+  return { kind: "artifact", file, summary: file };
+}
+
+function resolveFromBase(file: string, base: string): string {
+  return path.isAbsolute(file) ? file : path.resolve(base, file);
+}
+
+function artifactRef(file: string, repoRoot: string): string {
+  return resolveFromBase(file, repoRoot);
+}
+
+function notVerifiedPayload(taskSlug: string, command: string, summary: string, repoRoot: string, artifact?: string): EvidencePayload {
+  return {
+    schema_version: "1.0",
+    task_slug: taskSlug,
+    verdict: "not_verified",
+    checks: [
+      {
+        id: "veritas-governance-evidence",
+        kind: "policy",
+        status: "not_verified",
+        command,
+        summary,
+        ...(artifact ? { artifact_refs: [artifactEvidenceRef(artifactRef(artifact, repoRoot))] } : {}),
+      },
+    ],
+    not_verified_gaps: [summary],
+  };
+}
+
+function writeEvidence(file: string, payload: EvidencePayload): void {
+  ensureParent(file);
+  fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+function artifactProblem(nativeArtifact: string | undefined, maxAgeSeconds: number | undefined, repoRoot: string): string | undefined {
+  if (!nativeArtifact) return undefined;
+  const resolved = resolveFromBase(nativeArtifact, repoRoot);
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(resolved);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    return code === "ENOENT"
+      ? `Veritas readiness completed, but the expected native artifact is missing: ${resolved}.`
+      : `Veritas readiness completed, but the expected native artifact is unreadable: ${resolved}.`;
+  }
+  if (!stat.isFile()) return `Veritas readiness completed, but the expected native artifact is not a file: ${resolved}.`;
+  try {
+    fs.accessSync(resolved, fs.constants.R_OK);
+  } catch {
+    return `Veritas readiness completed, but the expected native artifact is unreadable: ${resolved}.`;
+  }
+  if (maxAgeSeconds !== undefined && maxAgeSeconds >= 0) {
+    const ageSeconds = (Date.now() - stat.mtimeMs) / 1000;
+    if (ageSeconds > maxAgeSeconds) {
+      return `Veritas native artifact is stale: ${resolved} is ${Math.floor(ageSeconds)}s old, max age is ${maxAgeSeconds}s.`;
+    }
+  }
+  return undefined;
+}
+
+function successPayload(taskSlug: string, command: string, repoRoot: string, nativeArtifact?: string): EvidencePayload {
+  const ref = nativeArtifact ? artifactRef(nativeArtifact, repoRoot) : "veritas://readiness/evidence";
+  const evidenceRef: EvidenceRef = nativeArtifact ? artifactEvidenceRef(ref) : { kind: "external", url: ref, summary: "Veritas readiness evidence." };
+  return {
+    schema_version: "1.0",
+    task_slug: taskSlug,
+    verdict: "pass",
+    checks: [
+      {
+        id: "veritas-governance-evidence",
+        kind: "policy",
+        status: "pass",
+        command,
+        summary: "Veritas readiness evidence completed without blocking findings.",
+        artifact_refs: nativeArtifact ? [evidenceRef] : undefined,
+        standard_refs: [
+          {
+            standard: "veritas",
+            ref,
+            role: "native",
+            summary: "Native Veritas readiness evidence artifact.",
+          },
+        ],
+      },
+    ],
+    external_evidence: nativeArtifact
+      ? [
+          {
+            system: "veritas",
+            ref: evidenceRef,
+            summary: "Native Veritas readiness evidence artifact.",
+            standard: "veritas",
+          },
+        ]
+      : undefined,
+  };
+}
+
+function skipPayload(taskSlug: string, command: string, notConfigured: boolean): EvidencePayload {
+  const summary = notConfigured
+    ? "Veritas governance evidence was requested, but Veritas is not configured for this repository."
+    : "Veritas governance evidence was explicitly skipped by caller request.";
+  return {
+    schema_version: "1.0",
+    task_slug: taskSlug,
+    verdict: notConfigured ? "not_verified" : "partial",
+    checks: [
+      {
+        id: "veritas-governance-evidence",
+        kind: "policy",
+        status: notConfigured ? "not_verified" : "skip",
+        command,
+        summary,
+      },
+    ],
+    ...(notConfigured ? { not_verified_gaps: [summary] } : {}),
+  };
+}
+
+function parseEvidenceOptions(argv: string[]): EvidenceOptions | undefined {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== "evidence") {
+    usage();
+    return undefined;
+  }
+  const { flags } = parseArgs(rest);
+  const artifactDirFlag = flagString(flags, "artifact-dir");
+  if (!artifactDirFlag) {
+    usage();
+    return undefined;
+  }
+  const artifactDir = path.resolve(artifactDirFlag);
+  const repoRoot = path.resolve(flagString(flags, "repo-root", ".") ?? ".");
+  const evidencePathFlag = flagString(flags, "evidence-path");
+  const maxAgeRaw = flagString(flags, "max-age-seconds");
+  const maxAgeSeconds = maxAgeRaw === undefined ? undefined : Number(maxAgeRaw);
+  if (maxAgeRaw !== undefined && !Number.isFinite(maxAgeSeconds)) throw new Error("--max-age-seconds must be a number");
+  return {
+    artifactDir,
+    evidencePath: path.resolve(evidencePathFlag ?? path.join(artifactDir, "evidence.json")),
+    taskSlug: readTaskSlug(artifactDir, flagString(flags, "task-slug")),
+    veritasBin: flagString(flags, "veritas-bin", "veritas") ?? "veritas",
+    repoRoot,
+    veritasRoot: flagString(flags, "veritas-root"),
+    nativeArtifact: flagString(flags, "veritas-artifact"),
+    maxAgeSeconds,
+    skip: flagBool(flags, "skip"),
+    notConfigured: flagBool(flags, "not-configured"),
+  };
+}
+
+function outputSummary(result: ReturnType<typeof spawnSync>): string {
+  const raw = `${result.stdout ?? ""}${result.stderr ? `\n${result.stderr}` : ""}`.trim();
+  if (!raw) return "";
+  const redacted = redactSecrets(raw);
+  const bounded = boundOutput(redacted);
+  return bounded.truncated ? `${bounded.text}\n[Output truncated for evidence sidecar.]` : bounded.text;
+}
+
+function redactSecrets(value: string): string {
+  return value
+    .replace(/\b(?:api[_-]?key|token|secret|password|passwd|pwd|authorization)\s*[:=]\s*["']?[^"'\s]+/gi, (match) => {
+      const separator = match.includes("=") ? "=" : ":";
+      return `${match.slice(0, match.indexOf(separator) + 1)}${REDACTED}`;
+    })
+    .replace(/\b(?:sk|pk|ghp|github_pat|xox[baprs]|glpat)-[A-Za-z0-9_=-]{12,}\b/g, REDACTED)
+    .replace(/\b[A-Za-z0-9+/]{32,}={0,2}\b/g, REDACTED);
+}
+
+function boundOutput(value: string): { text: string; truncated: boolean } {
+  const lines = value.split(/\r?\n/);
+  const lineBounded = lines.slice(0, OUTPUT_SUMMARY_MAX_LINES).join("\n");
+  const bytes = Buffer.byteLength(lineBounded, "utf8");
+  if (lines.length <= OUTPUT_SUMMARY_MAX_LINES && bytes <= OUTPUT_SUMMARY_MAX_BYTES) {
+    return { text: lineBounded, truncated: false };
+  }
+  let text = lineBounded;
+  if (bytes > OUTPUT_SUMMARY_MAX_BYTES) {
+    text = Buffer.from(lineBounded, "utf8").subarray(0, OUTPUT_SUMMARY_MAX_BYTES).toString("utf8");
+  }
+  return { text, truncated: true };
+}
+
+function runEvidence(options: EvidenceOptions): number {
+  const commandText = commandString(options.veritasBin, options.veritasRoot);
+
+  if (options.skip || options.notConfigured) {
+    writeEvidence(options.evidencePath, skipPayload(options.taskSlug, commandText, options.notConfigured));
+    console.log(`Wrote Veritas governance evidence sidecar: ${options.evidencePath}`);
+    return 0;
+  }
+
+  const args = ["readiness", "--check", "evidence", "--working-tree", ...(options.veritasRoot ? ["--root", options.veritasRoot] : [])];
+  const result = spawnSync(options.veritasBin, args, { cwd: options.repoRoot, encoding: "utf8" });
+  if (result.error) {
+    const summary = `Unable to run Veritas executable '${options.veritasBin}': ${result.error.message}. Configure --veritas-bin or run with --not-configured when governance evidence is optional.`;
+    writeEvidence(options.evidencePath, notVerifiedPayload(options.taskSlug, commandText, summary, options.repoRoot, options.nativeArtifact));
+    console.log(`Wrote Veritas governance evidence sidecar: ${options.evidencePath}`);
+    return 0;
+  }
+  if ((result.status ?? 1) !== 0) {
+    const output = outputSummary(result);
+    const summary = `Veritas readiness returned exit status ${result.status ?? "unknown"}${output ? ` with summarized output:\n${output}` : "."}`;
+    writeEvidence(options.evidencePath, notVerifiedPayload(options.taskSlug, commandText, summary, options.repoRoot, options.nativeArtifact));
+    console.log(`Wrote Veritas governance evidence sidecar: ${options.evidencePath}`);
+    return 0;
+  }
+  const problem = artifactProblem(options.nativeArtifact, options.maxAgeSeconds, options.repoRoot);
+  if (problem) {
+    writeEvidence(options.evidencePath, notVerifiedPayload(options.taskSlug, commandText, problem, options.repoRoot, options.nativeArtifact));
+    console.log(`Wrote Veritas governance evidence sidecar: ${options.evidencePath}`);
+    return 0;
+  }
+  writeEvidence(options.evidencePath, successPayload(options.taskSlug, commandText, options.repoRoot, options.nativeArtifact));
+  console.log(`Wrote Veritas governance evidence sidecar: ${options.evidencePath}`);
+  return 0;
+}
+
+export function main(argv = process.argv.slice(2)): number {
+  const options = parseEvidenceOptions(argv);
+  return options ? runEvidence(options) : 2;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());

package/src/cli/workflow-artifact-cleanup-audit.ts

@@ -0,0 +1,281 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { flagBool, flagString, parseArgs } from "../lib/args.js";
+
+type Classification =
+  | "active_wip"
+  | "cleanup_candidate"
+  | "terminal_done"
+  | "active_learning_followup"
+  | "invalid";
+
+type AuditItem = {
+  slug: string;
+  path: string;
+  classification: Classification;
+  state_status: string | null;
+  phase: string | null;
+  next_action_status: string | null;
+  reasons: string[];
+};
+
+type AuditResult = {
+  artifact_root: string;
+  buckets: Record<Classification, AuditItem[]>;
+  totals: Record<Classification | "scanned", number>;
+};
+
+const ACTIVE_STATUSES = new Set([
+  "planning",
+  "planned",
+  "in_progress",
+  "verifying",
+  "blocked",
+  "failed",
+  "not_verified",
+  "needs_decision",
+]);
+
+const KNOWN_LEARNING_STATUSES = new Set(["pending", "learned", "followup_required", "blocked"]);
+const KNOWN_LEARNING_ROUTE_TARGETS = new Set(["rule", "skill", "power", "agent", "eval", "doc", "backlog", "knowledge", "none"]);
+const KNOWN_LEARNING_ROUTE_STATUSES = new Set(["completed", "open", "deferred", "accepted", "rejected"]);
+const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history"]);
+const MAX_SIDECAR_BYTES = 1024 * 1024;
+
+function printHelp(): void {
+  console.log("Usage: flow-agents workflow-artifact-cleanup-audit [--artifact-root <path>] [--json]");
+  console.log("");
+  console.log("Read-only dry-run audit for local workflow artifact directories.");
+  console.log("");
+  console.log("Options:");
+  console.log("  --artifact-root <path>  Local artifact root to scan (default: .flow-agents)");
+  console.log("  --json                  Print stable JSON buckets instead of text");
+  console.log("  --help                  Show this help");
+  console.log("");
+  console.log("The command classifies active WIP, cleanup candidates, terminal done records,");
+  console.log("active learning follow-ups, and invalid sidecars. It does not delete, archive,");
+  console.log("move, or rewrite workflow artifacts.");
+}
+
+function readJson(file: string, label: string): { ok: true; value: unknown } | { ok: false; reason: string } {
+  let fd: number | null = null;
+  try {
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile()) return { ok: false, reason: `${label} must be a regular file` };
+    if (stat.size > MAX_SIDECAR_BYTES) {
+      return { ok: false, reason: `${label} exceeds max size of ${MAX_SIDECAR_BYTES} bytes` };
+    }
+    const buffer = Buffer.alloc(stat.size);
+    const bytesRead = fs.readSync(fd, buffer, 0, stat.size, 0);
+    if (bytesRead !== stat.size) {
+      return { ok: false, reason: `${label} changed while being read` };
+    }
+    return { ok: true, value: JSON.parse(buffer.toString("utf8")) };
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ELOOP") {
+      return { ok: false, reason: `${label} must not be a symlink` };
+    }
+    return { ok: false, reason: `${label} is unreadable: ${error instanceof Error ? error.message : String(error)}` };
+  } finally {
+    if (fd !== null) fs.closeSync(fd);
+  }
+}
+
+function objectValue(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function validateNextAction(state: Record<string, unknown>): { ok: true; status: string } | { ok: false; reason: string } {
+  const nextAction = objectValue(state.next_action);
+  if (!nextAction) return { ok: false, reason: "state.next_action is missing or invalid" };
+  const status = stringField(nextAction, "status");
+  if (!status) return { ok: false, reason: "state.next_action.status is missing or invalid" };
+  return { ok: true, status };
+}
+
+function routeStatuses(learning: Record<string, unknown>): { ok: true; statuses: string[] } | { ok: false; reason: string } {
+  if (!Array.isArray(learning.records)) return { ok: false, reason: "learning.records is missing or invalid" };
+  const statuses: string[] = [];
+  for (const record of learning.records) {
+    const item = objectValue(record);
+    if (!item) return { ok: false, reason: "learning record must be an object" };
+    if (!Array.isArray(item.routing)) return { ok: false, reason: "learning record routing is missing or invalid" };
+    const routing = item.routing;
+    for (const route of routing) {
+      const routeObject = objectValue(route);
+      if (!routeObject) return { ok: false, reason: "learning routing entry must be an object" };
+      const target = stringField(routeObject, "target");
+      if (!target) return { ok: false, reason: "learning routing target is missing or invalid" };
+      if (!KNOWN_LEARNING_ROUTE_TARGETS.has(target)) return { ok: false, reason: `learning routing has unknown target: ${target}` };
+      const action = stringField(routeObject, "action");
+      if (!action) return { ok: false, reason: "learning routing action is missing or invalid" };
+      const status = stringField(routeObject, "status");
+      if (!status) return { ok: false, reason: "learning routing status is missing or invalid" };
+      statuses.push(status);
+    }
+  }
+  return { ok: true, statuses };
+}
+
+function learningSignals(workflowDir: string): { open: boolean; reasons: string[]; invalidReason?: string } {
+  const learningPath = path.join(workflowDir, "learning.json");
+  if (!fs.existsSync(learningPath)) return { open: false, reasons: [] };
+  const parsed = readJson(learningPath, "learning.json");
+  if (!parsed.ok) return { open: false, reasons: [], invalidReason: parsed.reason };
+  const learning = objectValue(parsed.value);
+  if (!learning) return { open: false, reasons: [], invalidReason: "learning.json must be an object" };
+
+  const reasons: string[] = [];
+  const status = stringField(learning, "status");
+  if (!status) return { open: false, reasons: [], invalidReason: "learning.status is missing or invalid" };
+  if (!KNOWN_LEARNING_STATUSES.has(status)) return { open: false, reasons: [], invalidReason: `learning.status is unknown: ${status}` };
+  if (status === "followup_required") reasons.push("learning.status is followup_required");
+  const routesResult = routeStatuses(learning);
+  if (!routesResult.ok) return { open: false, reasons: [], invalidReason: routesResult.reason };
+  const routes = routesResult.statuses;
+  if (routes.includes("open")) reasons.push("learning routing has an open route");
+  const unknown = routes.filter((routeStatus) => !KNOWN_LEARNING_ROUTE_STATUSES.has(routeStatus));
+  if (unknown.length) return { open: false, reasons: [], invalidReason: `learning routing has unknown status: ${unknown.join(", ")}` };
+  return { open: reasons.length > 0, reasons };
+}
+
+function invalidItem(slug: string, workflowPath: string, reason: string): AuditItem {
+  return {
+    slug,
+    path: workflowPath,
+    classification: "invalid",
+    state_status: null,
+    phase: null,
+    next_action_status: null,
+    reasons: [reason],
+  };
+}
+
+function classifyWorkflow(slug: string, workflowPath: string): AuditItem {
+  const statePath = path.join(workflowPath, "state.json");
+  if (!fs.existsSync(statePath)) return invalidItem(slug, workflowPath, "missing state.json");
+  const parsed = readJson(statePath, "state.json");
+  if (!parsed.ok) return invalidItem(slug, workflowPath, parsed.reason);
+  const state = objectValue(parsed.value);
+  if (!state) return invalidItem(slug, workflowPath, "state.json must be an object");
+
+  const status = stringField(state, "status");
+  const phase = stringField(state, "phase");
+  if (!status) return invalidItem(slug, workflowPath, "state.status is missing or invalid");
+  if (!phase) return invalidItem(slug, workflowPath, "state.phase is missing or invalid");
+  const nextAction = validateNextAction(state);
+  if (!nextAction.ok) return invalidItem(slug, workflowPath, nextAction.reason);
+  const nextStatus = nextAction.status;
+
+  const base = { slug, path: workflowPath, state_status: status, phase, next_action_status: nextStatus };
+  const learning = learningSignals(workflowPath);
+  if (learning.invalidReason) return { ...base, classification: "invalid", reasons: [learning.invalidReason] };
+  if (learning.open) {
+    return { ...base, classification: "active_learning_followup", reasons: learning.reasons };
+  }
+
+  if (ACTIVE_STATUSES.has(status)) {
+    return { ...base, classification: "active_wip", reasons: [`state.status is active: ${status}`] };
+  }
+  if (status === "verified" && nextStatus === "continue") {
+    return { ...base, classification: "active_wip", reasons: ["verified workflow still has next_action.status continue"] };
+  }
+  if (status === "verified" && nextStatus === "done") {
+    return { ...base, classification: "cleanup_candidate", reasons: ["verified workflow has next_action.status done"] };
+  }
+  if (["delivered", "accepted", "archived"].includes(status) && phase === "done") {
+    return { ...base, classification: "terminal_done", reasons: [`${status} workflow is in phase done`] };
+  }
+  if ((status === "accepted" || status === "archived") && learning.reasons.length === 0) {
+    return { ...base, classification: "terminal_done", reasons: [`${status} workflow has no open learning routing`] };
+  }
+  return { ...base, classification: "invalid", reasons: [`unrecognized lifecycle shape: status=${status}, phase=${phase}, next_action.status=${nextStatus ?? "missing"}`] };
+}
+
+function childWorkflowDirs(root: string): string[] {
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => !name.startsWith(".") && !SKIPPED_ROOT_ENTRIES.has(name))
+    .sort();
+}
+
+function emptyBuckets(): Record<Classification, AuditItem[]> {
+  return {
+    active_wip: [],
+    cleanup_candidate: [],
+    terminal_done: [],
+    active_learning_followup: [],
+    invalid: [],
+  };
+}
+
+function audit(root: string): AuditResult {
+  const artifactRoot = path.resolve(root);
+  const stat = fs.statSync(artifactRoot);
+  if (!stat.isDirectory()) throw new Error(`artifact root is not a directory: ${artifactRoot}`);
+  const buckets = emptyBuckets();
+  for (const slug of childWorkflowDirs(artifactRoot)) {
+    const item = classifyWorkflow(slug, path.join(artifactRoot, slug));
+    buckets[item.classification].push(item);
+  }
+  return {
+    artifact_root: artifactRoot,
+    buckets,
+    totals: {
+      scanned: Object.values(buckets).reduce((sum, items) => sum + items.length, 0),
+      active_wip: buckets.active_wip.length,
+      cleanup_candidate: buckets.cleanup_candidate.length,
+      terminal_done: buckets.terminal_done.length,
+      active_learning_followup: buckets.active_learning_followup.length,
+      invalid: buckets.invalid.length,
+    },
+  };
+}
+
+function printBucket(title: string, items: AuditItem[]): void {
+  console.log(`${title}: ${items.length}`);
+  for (const item of items) {
+    console.log(`  - ${item.slug} (${item.state_status ?? "unknown"} / ${item.phase ?? "unknown"} / next=${item.next_action_status ?? "missing"})`);
+    for (const reason of item.reasons) console.log(`    reason: ${reason}`);
+  }
+}
+
+function printText(result: AuditResult): void {
+  console.log("Workflow artifact cleanup audit (dry run, read-only)");
+  console.log(`Artifact root: ${result.artifact_root}`);
+  console.log(`Scanned workflow directories: ${result.totals.scanned}`);
+  console.log("");
+  printBucket("Active WIP", result.buckets.active_wip);
+  printBucket("Active learning follow-ups", result.buckets.active_learning_followup);
+  printBucket("Cleanup candidates", result.buckets.cleanup_candidate);
+  printBucket("Terminal done", result.buckets.terminal_done);
+  printBucket("Invalid sidecars", result.buckets.invalid);
+}
+
+export function main(argv = process.argv.slice(2)): number {
+  const args = parseArgs(argv);
+  if (flagBool(args.flags, "help") || flagBool(args.flags, "h")) {
+    printHelp();
+    return 0;
+  }
+  let result: AuditResult;
+  try {
+    result = audit(flagString(args.flags, "artifact-root", ".flow-agents") ?? ".flow-agents");
+  } catch (error) {
+    console.error(`workflow-artifact-cleanup-audit: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  if (flagBool(args.flags, "json")) console.log(JSON.stringify(result, null, 2));
+  else printText(result);
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());