feat(hygiene): mechanize razor-cadence item 4 — audit-rule-cross-refs.ts

[AceHack]

Summary

Mechanizes the 12-batch manual razor-cadence item 4 (composes-with audit) work that ran on 2026-05-14, producing a CLI tool that future ticks (or a daily CI cron) can run instead of the per-tick manual audit.

What ships

tools/hygiene/audit-rule-cross-refs.ts — first slice (Layer A mechanical only):

• Scans all .claude/rules/*.md
• Pulls backtick'd path refs + B-NNNN IDs (dedup'd per the lesson from PR shard(tick): 1841Z — razor-cadence batch 4 (4 more rules, 29/29 LIVE) #3179 / Codex catch)
• Tests existence via direct path + glob + per-row backlog file lookup
• Reports stale-pointer candidates as a markdown table

tools/hygiene/audit-rule-cross-refs.test.ts — 12 tests / 22 expect calls, all passing.

First-run output

Rules scanned: 50
References pulled: 281
Resolved: 239
Stale-pointer candidates: 42

Of the 42 candidates, the canonical defect B-0514's missing feedback_aaron_wwjd_keeps_the_grey_in_aaron_honest_devil_lives_in_the_grey_in_numbers_2026_05_12.md is correctly surfaced — validating the tool against the manual audit's single finding.

Most other candidates are bare-filename references that would resolve with a path prefix (e.g., claude.ts → tools/peer-call/claude.ts) or RANE references (rule-acknowledged-not-exists per the taxonomy). Layer B semantic classification is out of scope for this first slice.

Out of scope (Layer B — semantic classification)

The 9-variant reference-classification taxonomy from the 12-batch manual audit:

1. Concrete file ref → test -e
2. Glob ref → ls | wc -l >= 1
3. Template path → surface dir + ≥1 instance
4. Backlog ID → ls docs/backlog/P*/B-NNNN-*.md; dedup when row file is also referenced
5. Legacy-noted ref → file may exist for historical anchor
6. Transient/ephemeral → rule says "DON'T rely on this"
7. Anti-pattern ref → rule mentions for contrast
8. Conditional ref → "would exist IF..."
9. Alternative-location ref → repo uses different valid path

Requires reading the rule's prose context around each reference. ~5% of MISSes are rule-acknowledged-not-exists (healthy). The first slice produces the candidate list; humans/Otto apply the taxonomy during triage.

See docs/hygiene-history/ticks/2026/05/14/1920Z.md for full taxonomy + final audit results.

Composes with

• B-0506 (worktree-prune cadence) — another factory-hygiene mechanization
• Razor-cadence Razor cadence due -- 2026-05-23 #3128 daily fire — this tool replaces item 4's manual per-tick work
• encoding-rules-without-mechanizing.md — the rule the work satisfies

Test plan

• bun test tools/hygiene/audit-rule-cross-refs.test.ts — 12 pass / 22 expect calls
• CLI run produces correctly-shaped markdown report
• Tool catches B-0514's genuine stale pointer (validates against manual audit)
• All taxonomy variants documented in the tool's docstring + report's reminder section

🤖 Generated with Claude Code
EOF
)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d091b7e1d9

ℹ️ 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".

[Copilot]

Pull request overview

Adds a new Bun CLI under tools/hygiene/ to mechanize the razor-cadence “composes-with cross-ref audit” by extracting file/backlog references from .claude/rules/*.md, checking whether they resolve, and emitting a markdown report, with a small Bun test suite for the core helpers.

Changes:

• Introduces tools/hygiene/audit-rule-cross-refs.ts to scan rules, extract backtick’d path refs + B-NNNN IDs, and render a report of unresolved candidates.
• Adds tools/hygiene/audit-rule-cross-refs.test.ts to validate pullRefs, refExists, and renderReport.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
tools/hygiene/audit-rule-cross-refs.ts	New CLI + library helpers to audit .claude/rules cross-references and output a markdown report.
tools/hygiene/audit-rule-cross-refs.test.ts	New Bun tests for reference extraction, resolution checks, and report rendering.

Comments suppressed due to low confidence (4)

tools/hygiene/audit-rule-cross-refs.ts:42

• P1: typescript.md isn’t a repo-root file; the canonical TypeScript conventions doc is docs/best-practices/typescript.md. Consider updating this xref to the full path to avoid confusion and to keep cross-refs mechanically checkable.

// DST-friendliness:
//
//   Read-only audit. The "Generated" timestamp in markdown reports is the only
//   non-deterministic surface. Per `typescript.md` universal-DST gate.

tools/hygiene/audit-rule-cross-refs.ts:37

• P1: The script documentation says exit code 0 is returned “always” (except arg errors), but readFileSync / writeFileSync / readdirSync can throw and will currently terminate the process with a non-0 code. Either wrap the main path in a try/catch to enforce the documented behavior (emit an error + exit 0), or document the additional non-zero failure mode(s).

// Exit codes:
//
//   0   always (detect-only; no enforcement; humans triage stale-pointer candidates)
//   64  argument error
//

tools/hygiene/audit-rule-cross-refs.ts:120

• P0: refExists treats any * ref as a “glob”, but this implementation only works when the wildcard is in the final path segment. For patterns like docs/backlog/P*/B-*.md (used in .claude/rules/), dir becomes docs/backlog/P* which will never exist, so these will be false stale-pointer candidates. Consider using Bun’s Glob (used elsewhere under tools/hygiene) or extending glob support to directory segments.

        if (ref.raw.includes("*")) {
            const lastSlash = ref.raw.lastIndexOf("/");
            const dir = lastSlash >= 0 ? ref.raw.slice(0, lastSlash) : ".";
            const filePart = lastSlash >= 0 ? ref.raw.slice(lastSlash + 1) : ref.raw;
            if (!existsSync(dir) || !statSync(dir).isDirectory()) return false;

tools/hygiene/audit-rule-cross-refs.ts:197

• P1: The report text links the 9-variant taxonomy to docs/hygiene-history/ticks/2026/05/14/1920Z.md, but that file doesn’t exist (taxonomy is captured in 1908Z/1916Z). Update this pointer so the report’s “how to triage candidates” guidance is actionable.

    lines.push("Candidates listed below failed direct path / glob / backlog-row lookup. Apply the");
    lines.push("9-variant taxonomy from `docs/hygiene-history/ticks/2026/05/14/1920Z.md` to classify");
    lines.push("each candidate before fixing — ~5% are healthy MISSes (rule-acknowledged-transient,");

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5728487851

ℹ️ 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".

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (4)

tools/hygiene/audit-rule-cross-refs.ts:316

• P1 (codebase convention): This tool relies on relative paths (e.g., .claude/rules) but never chdirs to the repo root. Many Zeta tools make repo-rooted invocation reliable by process.chdir(repoRoot()) (see docs/best-practices/repo-scripting.md “Repo-rooted invocation”). Consider resolving paths from repo root (via git rev-parse --show-toplevel or import.meta.url-relative) so running from a subdirectory or CI step with a different CWD doesn’t silently report everything as missing.

    const result = audit(RULES_DIR);
    const report = renderReport(result, new Date());

tools/hygiene/audit-rule-cross-refs.ts:83

• P1 (codebase convention): This CLI parser doesn’t support -h/--help, even though the repo scripting conventions call out -h/--help as a standard flag and expect unknown flags to exit 64 with an error to stderr. Adding help output (stdout) will make the tool consistent with other tools/hygiene/* CLIs.

function parseArgs(argv: string[]): { kind: "args"; args: Args } | { kind: "error"; message: string } {
    let report: string | null = null;
    let i = 0;
    while (i < argv.length) {
        const a = argv[i]!;
        if (a === "--report") {
            const next = argv[i + 1];
            if (!next) return { kind: "error", message: "--report requires a path" };
            report = next;
            i += 2;
        } else {
            return { kind: "error", message: `Unknown argument: ${a}` };
        }
    }
    return { kind: "args", args: { report } };
}

tools/hygiene/audit-rule-cross-refs.ts:41

• P2 (documentation/xref): This comment references typescript.md, but the TypeScript best-practices doc lives at docs/best-practices/typescript.md. Using the full path here would avoid suggesting a non-existent repo-root typescript.md file.

// DST-friendliness:
//
//   Read-only audit. The "Generated" timestamp in markdown reports is the only
//   non-deterministic surface. Per `typescript.md` universal-DST gate.

tools/hygiene/audit-rule-cross-refs.ts:322

• P1 (codebase convention): console.log(\wrote …`)` writes progress chatter to stdout, which makes stdout non-pipeable if callers want to consume the markdown report from stdout. The repo scripting conventions prefer stdout for data output and stderr for progress/status; consider sending the “wrote …” line to stderr instead.

    if (parsed.args.report) {
        writeFileSync(parsed.args.report, report);
        console.log(`wrote ${parsed.args.report}`);
    } else {
        console.log(report);
    }