audit-skip

/audit-skip — Append a False-Positive Exception to the Allowlist

Purpose

Append a structured exception entry to .claude/rules/audit-exceptions.md after the user has confirmed a finding is not exploitable. Future /audit runs consult this file in Phase 0 and skip matching findings.

Validation is hard-refusal — there is no --force flag. An exception against an untracked path or an out-of-range line is a moving target the Council cannot reason about.

---

Usage

/audit-skip <file:line> <rule> <reason...>
/audit-skip <file:line> <rule> --council=council_confirmed_fp <reason...>

Examples:

• /audit-skip src/foo.ts:42 SEC-XSS user input is escaped upstream by escapeHtml
• /audit-skip scripts/setup-security.sh:142 SEC-RAW-EXEC bash -c invocation runs hardcoded install commands, no user input
• /audit-skip api/users.ts:88 SEC-SQL --council=council_confirmed_fp prepared statement, scanner false-positive on string concat

---

When to Use

• After reviewing a /audit finding and confirming it is NOT exploitable in this codebase.
• After the Council (/council audit-review) returns FALSE_POSITIVE and prompts you to persist the exception (use --council=council_confirmed_fp in that case per D-09).
• DO NOT use to suppress findings you haven't read. The Reason field is your justification — vague reasons like "false positive" or "not real" are inadequate.

---

Process

Step 1 — Parse Arguments

Parse all tokens after the command. Require at least three positional tokens (file:line, rule, and at least one reason word). Extract the optional --council= flag from the reason-token stream.

set -euo pipefail

# All args after the command, in raw form
ARGS=("$@")

if [ "${#ARGS[@]}" -lt 3 ]; then
    printf 'audit-skip: usage: /audit-skip <file:line> <rule> <reason...>\n' >&2
    exit 2
fi

FILE_LINE="${ARGS[0]}"
RULE="${ARGS[1]}"

# Split file:line on the LAST colon so paths containing : still work.
PATH_PART="${FILE_LINE%:*}"
LINE_PART="${FILE_LINE##*:}"

# Line must be a positive integer.
case "$LINE_PART" in
    ''|*[!0-9]*)
        printf 'audit-skip: <file:line> must end with :<positive integer>, got %q\n' "$FILE_LINE" >&2
        exit 2
        ;;
esac

# Reason tokens = everything after the rule, with --council=... extracted.
COUNCIL="unreviewed"
REASON_TOKENS=()
for tok in "${ARGS[@]:2}"; do
    case "$tok" in
        --council=council_confirmed_fp)
            COUNCIL="council_confirmed_fp"
            ;;
        --council=*)
            printf 'audit-skip: --council= only accepts council_confirmed_fp (got %q)\n' "$tok" >&2
            exit 2
            ;;
        *)
            REASON_TOKENS+=("$tok")
            ;;
    esac
done

if [ "${#REASON_TOKENS[@]}" -eq 0 ]; then
    printf 'audit-skip: reason is required (every token after the rule is joined as Reason)\n' >&2
    exit 2
fi

# Join reason tokens with single spaces.
# Safety: always use printf '%s' to interpolate REASON — never echo (avoids
# backslash-escape interpretation on macOS).
REASON="$(printf '%s ' "${REASON_TOKENS[@]}")"
REASON="${REASON% }"  # strip trailing space