--reason is not supported for ignore-file because detector.i

Error message

--reason is not supported for ignore-file because detector.ignoreFiles stores globs only; use ignore-value when a documented rule-specific exception fits

What it means

ignore-file stores file/path globs in detector.ignoreFiles and has no reason field. Passing `--reason` would be silently dropped (data loss), so the parser rejects it explicitly and points the user to ignore-value, which does persist a reason when a documented rule-specific exception applies.

Source

Thrown at plugin/skills/impeccable/scripts/hook-admin.mjs:601

  const config = mergeDetectorConfig(readRawDetectorConfig(cwd));
  if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
  writeDetectorConfig(cwd, config);
  return `Added "${rule}" to detector.ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
}

function parseIgnoreFileArgs(args) {
  const positionals = [];
  let shared = false;
  let local = false;

  for (const raw of args) {
    const arg = String(raw || '');
    if (arg === '--shared') {
      shared = true;
    } else if (arg === '--local') {
      local = true;
    } else if (arg === '--reason' || arg.startsWith('--reason=')) {
      throw new Error('--reason is not supported for ignore-file because detector.ignoreFiles stores globs only; use ignore-value when a documented rule-specific exception fits');
    } else if (arg.startsWith('--')) {
      throw new Error(`Unknown ignore-file flag: ${arg}`);
    } else {
      positionals.push(arg);
    }
  }

  if (shared && local) throw new Error('Pass only one scope flag: --shared or --local');
  if (positionals.length > 1) throw new Error('Pass exactly one glob to ignore-file');

  return {
    glob: positionals[0],
    local,
  };
}

function addIgnoreFile(cwd, args) {
  const parsed = parseIgnoreFileArgs(args);

View on GitHub (pinned to d14711ae3d)

Solutions

Drop --reason from the ignore-file invocation (store the rationale elsewhere, e.g. a commit message or comment).
If a documented rule-specific exception with a reason is what you need, use `hooks ignore-value <rule> <value> --reason "..."` instead.

Example fix

# before
impeccable hooks ignore-file "src/legacy/**" --reason "legacy"

# after
cd /tmp/errlookup-RbNU9j && impeccable hooks ignore-file "src/legacy/**"

Defensive patterns

Strategy: validation

Validate before calling

if (args.some(a => a === '--reason' || String(a).startsWith('--reason='))) {
  throw new Error('--reason is not supported for ignore-file; use ignore-value for a documented exception');
}

Prevention

Remember ignore-file stores only globs — there is no reason field to populate.
If a reason matters, check whether a documented ignore-value exception fits instead.

When it happens

Trigger: Running `hooks ignore-file "<glob>" --reason "..."` (space form) or `--reason=...`.

Common situations: User wants to record why a file is ignored and reaches for the reason flag that ignore-value supports; copy-pasting an ignore-value invocation pattern onto ignore-file.

Related errors

AI-assisted analysis of pbakaus/impeccable@d14711ae3d (2026-08-13). Data as JSON: /api/errors/c462647951aca393. Report an issue: GitHub.