Intent Alignment Audit

What This Does

Cross-references your recorded intents (see /intent-db) against codebase references to surface:

• Uncovered intents -- intents exist in the store but no code or tests reference them
• Orphaned references -- code references an intent slug that doesn't exist in the store
• Missing playbooks -- intents without resolution playbooks for systemic fixes
• Coverage gaps -- intents with code but no tests, or tests but no code

If you have no recorded intents yet, this audit has nothing to compare code against and will say so plainly rather than printing a table of zeros. Start by recording a few with /intent-db — it can also draft candidates from your own past sessions and existing test names for you to confirm.

When to Use

• Before starting work on a feature area -- see what intents govern it
• After a bug fix -- check if the intent has a resolution playbook (author one if not)
• During review -- verify committed code references the intents it implements
• Periodic audit -- scan the full codebase for coverage gaps

How to Use

The script ships alongside this skill (intent-alignment-audit.js in this skill's folder — use <path-to-this-skill>/intent-alignment-audit.js) and reads the same local file store /intent-db writes to — no database or server needed. Run it from anywhere; it defaults to scanning your current directory, or pass --repo (repeatably) to scan one or more specific project roots.

# Scan staged files
node <path-to-this-skill>/intent-alignment-audit.js --staged

# Scan a specific commit
node <path-to-this-skill>/intent-alignment-audit.js --commit abc123

# Scan last 7 days of changes
node <path-to-this-skill>/intent-alignment-audit.js --last 7

# Full scan (capped at 10 rows shown) — this is the mode where "Uncovered" is meaningful,
# because it loads every non-deprecated recorded intent, not just ones already tagged in code
node <path-to-this-skill>/intent-alignment-audit.js --all --max 10

# Filter to a specific area (tag)
node <path-to-this-skill>/intent-alignment-audit.js --all --area auth

# Scan more than one repo in one pass
node <path-to-this-skill>/intent-alignment-audit.js --all --repo ../api --repo ../web

# Also merge in the company-strategy intent store (see /company-intent-db), if you keep one
node <path-to-this-skill>/intent-alignment-audit.js --all --include-company

# JSON output for programmatic use
node <path-to-this-skill>/intent-alignment-audit.js --last 7 --json

Agent worktrees and copies of the repo (.claude/worktrees, .worktrees, anything git worktree list reports) are skipped automatically, so a machine with several checkouts of the same repo doesn't get the same file counted several times over.

Coverage Categories

Category	Symbol	Meaning
COVERED	+	Intent has both code references AND test coverage
CODE_ONLY	~	Intent has code references but no test
TEST_ONLY	?	Intent has test coverage but no code references
UNCOVERED	X	Intent is in scope but has no code or test references
ORPHANED	!	Code references an intent slug that doesn't exist in the store

Resolution Playbooks

When an intent has a resolutionPlaybook field, the audit reports it. Playbooks describe:

• Pattern: The systemic implementation pattern (files, architecture)
• Mechanism: Why it works
• Failure modes: What typically breaks it
• Restoration: How to restore the pattern (NOT a point fix)
• Verify with: Test file that confirms the intent holds

Authoring a Playbook

After fixing an intent violation, add a resolutionPlaybook to that intent's own record. Since intents live as plain JSON files (one per slug, in the folder alignment-harness records intents prints), this is just editing that file:

INTENT_DIR=$(alignment-harness records intents)
node -e '
const fs = require("fs"), path = require("path");
const file = path.join(process.argv[2], process.argv[3] + ".json");
const intent = JSON.parse(fs.readFileSync(file, "utf8"));
intent.resolutionPlaybook = {
  pattern: "Every fetch/axios call to auth endpoints includes credentials: \"include\"",
  mechanism: "Browsers only send httpOnly cookies when a request opts in. Without this, cookie-based auth silently fails.",
  failureModes: ["New fetch call added without credentials", "Axios instance missing withCredentials"],
  restoration: "Grep ALL fetch/axios calls to your auth endpoints. Each must have credentials configured.",
  verifyWith: "__tests__/intents/systemic-auth-credentials-guarantee.test.js",
  canonicalFiles: ["src/auth/Login.js", "src/utils/tokenRefresh.js"]
};
fs.writeFileSync(file, JSON.stringify(intent, null, 2));
' "$INTENT_DIR" auth-credentials-guarantee

If you have your own database-backed intent store instead (see /alignment-harness:harness-setup), update the record there the same way, using its own API or client.

What This Is NOT

• NOT a CI gate -- never blocks commits
• NOT injected into agent context automatically -- invoked on demand
• NOT expensive -- runs locally, no LLM calls, ~2 seconds for staged files

Implementation Details

• Script: intent-alignment-audit.js in this skill's folder
• Intent store: the local file store /intent-db writes to (alignment-harness records intents) — or a database-backed store you've pointed /intent-db at instead
• Secondary store (optional): a company-strategy intent store (see /company-intent-db), merged in with --include-company
• Regex patterns scanned:
  • @intent: <slug> in code comments
  • @intents-covered: <slug1>, <slug2> in test file headers
  • intentSlug: '<slug>' in logger/console calls
• Repos scanned: your current directory by default, or every path passed with --repo
• Excludes: node_modules, build, dist, .next, .git, coverage, public, and any worktree checkout of the same repo

Persisting Audit Findings

When an alignment audit surfaces significant coverage gaps or regressions, it's worth keeping a record so the next person (or agent) doesn't have to re-discover the same gap.

If you have your own findings store (a database, a research-notes tool — see /alignment-harness:harness-setup), search it first to check whether a similar audit was already done, then record this one there with a linkedIntentIds field pointing at the gap intents.

Local fallback:

FINDINGS_DIR=$(alignment-harness records research-findings)
mkdir -p "$FINDINGS_DIR"
cat > "$FINDINGS_DIR/$(date +%Y-%m-%d)-intent-coverage.json" <<'EOF'
{
  "researchType": "decision-audit",
  "title": "Intent coverage audit",
  "summary": "<what you found>",
  "linkedIntentSlugs": ["<slug-1>", "<slug-2>"]
}
EOF

Grep that folder (grep -ril "intent coverage" "$FINDINGS_DIR") before running a fresh audit, the same way you'd check a remote store first.