feat(B-0058): add retractibility audit tool

tools/alignment/README.md

@@ -19,6 +19,7 @@ folder as the experimental loop.
 | `audit_archive_headers.sh` | Archive-header discipline (proposed §33) | Per-file lint (detect-only v0) |
 | `audit_clause_coverage.ts` | HC/SD/DIR clause citations in skills, agents, backlog P0/P1 | Per-surface coverage audit |
 | `audit_clause_drift.ts` | Clause additions/removals/changes + impact survey | Cross-ref drift detection |
+| `audit_retractibility.ts` | Git-tracked + inbound-ref entanglement per surface | Retractibility gate (B-0058 #1) |
 | `sd6_names.txt`       | SD-6 watchlist (per-host)                    | Data (not code)             |
 
 The three scripts form the gitops observability trio:

tools/alignment/audit_retractibility.test.ts

@@ -0,0 +1,196 @@
+// audit_retractibility.test.ts — tests for retractibility audit tool.
+//
+// B-0058 slice: adds test coverage for the retractibility check's
+// arg parsing, inbound-ref counting, audit shape, and CLI exit codes.
+//
+// Run: bun test tools/alignment/audit_retractibility.test.ts
+
+import { describe, expect, test } from "bun:test";
+import {
+  auditRetractibility,
+  countInboundRefs,
+  main,
+  parseArgs,
+} from "./audit_retractibility.ts";
+
+describe("parseArgs", () => {
+  test("returns help for -h", () => {
+    expect(parseArgs(["-h"])).toEqual({ kind: "help" });
+  });
+
+  test("returns help for --help", () => {
+    expect(parseArgs(["--help"])).toEqual({ kind: "help" });
+  });
+
+  test("parses --json flag", () => {
+    const result = parseArgs(["--json"]);
+    expect(result.kind).toBe("args");
+    if (result.kind === "args") {
+      expect(result.args.json).toBe(true);
+      expect(result.args.md).toBe(false);
+    }
+  });
+
+  test("parses --md flag", () => {
+    const result = parseArgs(["--md"]);
+    expect(result.kind).toBe("args");
+    if (result.kind === "args") {
+      expect(result.args.md).toBe(true);
+      expect(result.args.json).toBe(false);
+    }
+  });
+
+  test("parses --gate with value", () => {
+    const result = parseArgs(["--gate", "10"]);
+    expect(result.kind).toBe("args");
+    if (result.kind === "args") {
+      expect(result.args.gate).toBe(10);
+    }
+  });
+
+  test("errors on --gate without value", () => {
+    const result = parseArgs(["--gate"]);
+    expect(result.kind).toBe("error");
+  });
+
+  test("errors on --gate with non-numeric value", () => {
+    const result = parseArgs(["--gate", "abc"]);
+    expect(result.kind).toBe("error");
+  });
+
+  test("errors on unknown flag", () => {
+    const result = parseArgs(["--bad-flag"]);
+    expect(result.kind).toBe("error");
+  });
+
+  test("collects positional paths", () => {
+    const result = parseArgs(["foo.md", "bar.md"]);
+    expect(result.kind).toBe("args");
+    if (result.kind === "args") {
+      expect(result.args.paths).toEqual(["foo.md", "bar.md"]);
+    }
+  });
+
+  test("combines flags and paths", () => {
+    const result = parseArgs(["--json", "--gate", "5", "a.md", "b.md"]);
+    expect(result.kind).toBe("args");
+    if (result.kind === "args") {
+      expect(result.args.json).toBe(true);
+      expect(result.args.gate).toBe(5);
+      expect(result.args.paths).toEqual(["a.md", "b.md"]);
+    }
+  });
+});
+
+describe("countInboundRefs", () => {
+  test("returns a count and from array for a known file", () => {
+    const result = countInboundRefs("docs/ALIGNMENT.md", process.cwd());
+    expect(typeof result.count).toBe("number");
+    expect(result.count).toBeGreaterThan(0);
+    expect(Array.isArray(result.from)).toBe(true);
+    expect(result.from.length).toBe(result.count);
+  });
+
+  test("excludes self from inbound refs", () => {
+    const result = countInboundRefs("docs/ALIGNMENT.md", process.cwd());
+    expect(result.from).not.toContain("docs/ALIGNMENT.md");
+  });
+
+  test("returns zero for a nonexistent path pattern", () => {
+    const result = countInboundRefs("this/path/definitely/does/not/exist/anywhere.md", process.cwd());
+    expect(result.count).toBe(0);
+    expect(result.from).toEqual([]);
+  });
+});
+
+describe("auditRetractibility", () => {
+  test("returns valid shape for a known skill", () => {
+    const result = auditRetractibility([".claude/skills/alignment-auditor/SKILL.md"]);
+    expect(result.schema).toBe("retractibility-v1");
+    expect(result.totalSurfaces).toBe(1);
+    expect(result.entanglementThreshold).toBe(5);
+    expect(result.surfaces).toHaveLength(1);
+
+    const surface = result.surfaces[0]!;
+    expect(surface.kind).toBe("skill");
+    expect(surface.name).toBe("alignment-auditor");
+    expect(surface.gitTracked).toBe(true);
+    expect(typeof surface.inboundRefs).toBe("number");
+    expect(["retractible", "entangled"]).toContain(surface.status);
+  });
+
+  test("returns valid shape for a known agent", () => {
+    const result = auditRetractibility([".claude/agents/alignment-auditor.md"]);
+    expect(result.totalSurfaces).toBe(1);
+    const surface = result.surfaces[0]!;
+    expect(surface.kind).toBe("agent");
+    expect(surface.name).toBe("alignment-auditor");
+    expect(surface.gitTracked).toBe(true);
+  });
+
+  test("classifies untracked file correctly", () => {
+    const result = auditRetractibility(["definitely-not-a-real-file-xyz.md"]);
+    expect(result.totalSurfaces).toBe(1);
+    expect(result.untracked).toBe(1);
+    const surface = result.surfaces[0]!;
+    expect(surface.status).toBe("untracked");
+    expect(surface.gitTracked).toBe(false);
+    expect(surface.inboundRefs).toBe(0);
+  });
+
+  test("counts add up correctly", () => {
+    const result = auditRetractibility([
+      ".claude/skills/alignment-auditor/SKILL.md",
+      ".claude/agents/alignment-auditor.md",
+      "definitely-not-a-real-file-xyz.md",
+    ]);
+    expect(result.totalSurfaces).toBe(3);
+    expect(result.retractible + result.entangled + result.untracked).toBe(result.totalSurfaces);
+  });
+
+  test("sorts surfaces by descending inbound refs", () => {
+    const result = auditRetractibility([
+      ".claude/skills/alignment-auditor/SKILL.md",
+      ".claude/agents/alignment-auditor.md",
+    ]);
+    if (result.surfaces.length >= 2) {
+      expect(result.surfaces[0]!.inboundRefs).toBeGreaterThanOrEqual(
+        result.surfaces[1]!.inboundRefs,
+      );
+    }
+  });
+});
+
+describe("main() CLI", () => {
+  test("returns 0 with --help", () => {
+    expect(main(["--help"])).toBe(0);
+  });
+
+  test("returns 2 for unknown flag", () => {
+    expect(main(["--bad-flag"])).toBe(2);
+  });
+
+  test("returns 2 when --gate has no value", () => {
+    expect(main(["--gate"])).toBe(2);
+  });
+
+  test("returns 0 with specific paths", () => {
+    expect(main([".claude/agents/alignment-auditor.md"])).toBe(0);
+  });
+
+  test("returns 0 with --json and specific path", () => {
+    expect(main(["--json", ".claude/agents/alignment-auditor.md"])).toBe(0);
+  });
+
+  test("returns 0 with --md and specific path", () => {
+    expect(main(["--md", ".claude/agents/alignment-auditor.md"])).toBe(0);
+  });
+
+  test("returns 0 with --gate 0 (trivially satisfied)", () => {
+    expect(main(["--gate", "0", ".claude/agents/alignment-auditor.md"])).toBe(1);
+  });
+
+  test("returns 0 with --gate 9999 (impossible threshold)", () => {
+    expect(main(["--gate", "9999", ".claude/agents/alignment-auditor.md"])).toBe(0);
+  });
+});