Actual-sync: Command for Claude Code

Run a source code-health audit for actual-sync and create GitHub issues for genuine findings.

Usage

Accepted arguments: [--full] [--dry-run]

• Default: cache-first. Skip findings already filed and recorded in the cache.
• --full: ignore the cache and re-triage every finding.
• --dry-run: print the report and the tickets that WOULD be filed, but create no tickets and write no cache. Use this for review.

This auditor is run MANUALLY on demand. It is NOT scheduled: never set up a GitHub Actions cron or a Claude Code scheduled routine for it. (Scope split: this owns SOURCE dead code and doc-to-code drift; /dep-auditor owns DEPENDENCY health. Do not re-file unused-dependency findings here.)

Provenance / canonical source

The canonical copy of this skill lives in the sibling project agigante80/actual-mcp-server (.claude/commands/code-health-auditor.md). This repo adopts the same shape under agigante80/Actual-sync#130; if the two diverge, reconcile against the sibling. Both carry <!-- code-health-auditor-version: 1 --> so divergence is detectable. Keep project-specific values (paths, labels, guard/script names) minimal so the two stay alignable; the auditing logic below must stay identical to the canonical.

Overview

One pass: read the cache, run Knip (dead code) with the committed config, run the drift guards, triage findings against the documented allowlist, then open gate-ready tickets for the genuine ones and update the cache. Never auto-remove code or auto-edit docs: file tickets only. Output uses no em or en dashes.

---

Step 1 - Read the cache

Read docs/audit/deadcode-audit-cache.json if it exists. Schema:

{
  "lastFullAudit": "<ISO timestamp>",
  "findings": {
    "<kind:path:symbol>": {
      "firstSeen": "<YYYY-MM-DD>",
      "lastSeen": "<YYYY-MM-DD>",
      "status": "filed|allowlisted|wontfix",
      "ticket": "<#NNN or null>",
      "notes": "<short reason>"
    }
  }
}