feat(B-0058): add retractibility audit tool#2108
Conversation
B-0058 responsibility #1: verify that factory surfaces (skills, agents, backlog items) preserve retractibility — git-tracked and one-commit-removable. The tool scans each surface for inbound references via git grep and classifies it as retractible (< 5 inbound refs), entangled (>= 5), or untracked. Emits --json / --md / human output. Optional --gate N flag fails if any surface has >= N inbound refs. Includes 26 Bun tests covering arg parsing, ref counting, audit shape, and CLI exit codes. All existing B-0058 tests pass. Build gate green (0 warnings, 0 errors). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0a84559152
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| } | ||
|
|
||
| export function countInboundRefs(filePath: string, root: string): { count: number; from: readonly string[] } { | ||
| const relPath = relative(root, `${root}/${filePath}`); |
There was a problem hiding this comment.
countInboundRefs builds the grep key with relative(root, ${root}/${filePath}), which produces incorrect strings for valid inputs such as absolute paths (e.g. /workspace/Zeta/... becomes workspace/Zeta/...) and, on Windows, backslash-separated paths. In both cases git grep misses real references and returns 0, so surfaces are misclassified as retractible and --gate can pass when it should fail. This breaks the tool’s core entanglement signal for common automation/cross-platform usage.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds a new alignment tool to audit “retractibility” of factory surfaces by checking (a) whether each surface is git-tracked and (b) how many inbound references it has, with multiple output formats and an optional gate mode.
Changes:
- Added
tools/alignment/audit_retractibility.tsCLI to scan skills/agents/backlog surfaces (or explicit paths) and report inbound reference counts viagit grep. - Added Bun test coverage for arg parsing, reference counting, audit output shape, and CLI exit codes.
- Documented the new tool in
tools/alignment/README.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| tools/alignment/README.md | Adds the new retractibility audit tool to the alignment tool index. |
| tools/alignment/audit_retractibility.ts | Implements git-tracking + inbound-ref counting and emits human/JSON/MD output with optional gating. |
| tools/alignment/audit_retractibility.test.ts | Adds Bun tests covering parsing, counting, auditing, and CLI exit codes. |
| export function countInboundRefs(filePath: string, root: string): { count: number; from: readonly string[] } { | ||
| const relPath = relative(root, `${root}/${filePath}`); | ||
|
|
||
| const result = spawnSync( |
| export function auditRetractibility(paths: readonly string[]): RetractResult { | ||
| const root = process.cwd(); | ||
| const surfaces: SurfaceRetract[] = []; | ||
|
|
||
| for (const p of paths) { | ||
| const gitTracked = isGitTracked(p); | ||
| const { count, from } = gitTracked ? countInboundRefs(p, root) : { count: 0, from: [] as string[] }; | ||
| const status = classifyStatus(gitTracked, count); | ||
|
|
||
| surfaces.push({ | ||
| path: p, | ||
| kind: kindFromPath(p), | ||
| name: nameFromPath(p), | ||
| gitTracked, | ||
| inboundRefs: count, | ||
| inboundFrom: from, |
| const { args } = parsed; | ||
|
|
||
| process.chdir(repoRoot()); | ||
|
|
||
| let paths: readonly string[]; | ||
| if (args.paths.length > 0) { | ||
| paths = args.paths; | ||
| } else { | ||
| paths = [...discoverSkills(), ...discoverAgents(), ...discoverBacklog()]; | ||
| } |
| expect(main(["--md", ".claude/agents/alignment-auditor.md"])).toBe(0); | ||
| }); | ||
|
|
||
| test("returns 0 with --gate 0 (trivially satisfied)", () => { |
Summary
tools/alignment/audit_retractibility.ts— B-0058 responsibility deps: Bump FsUnit.xUnit from 7.1.0 to 7.1.1 #1 (retractibility-and-log check)git grepretractible(< 5 inbound refs),entangled(>= 5), oruntracked--json,--md, and human output formats; optional--gate Nexit-code gateEvidence
Test plan
bun test tools/alignment/audit_retractibility.test.ts)dotnet build -c Release— 0 warnings, 0 errors🤖 Generated with Claude Code