What causes "Unknown ignore-file flag: ${arg}" in pbakaus/impeccable?

Remove the unknown flag — ignore-file accepts only --shared and --local.

Unknown ignore-file flag

Error message

Unknown ignore-file flag: ${arg}

What it means

Thrown while parsing `hooks ignore-file` arguments when a `--`-prefixed token is neither --shared nor --local (nor --reason, which gets its own more specific error). Unknown flags are rejected rather than ignored so a typo cannot masquerade as a successful suppression.

Solutions

Remove the unknown flag — ignore-file accepts only --shared and --local.
The glob itself is positional, not a flag: `hooks ignore-file "src/legacy/**"`.
Use --shared or --local to pick which config file the glob is written to.

Example fix

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

# after
impeccable hooks ignore-file "src/legacy/**" --shared

Defensive patterns

Strategy: validation

Validate before calling

const IGNORE_FILE_FLAGS = new Set(['--shared', '--local']);
function sanitize(args) {
  const bad = args.filter(a => a.startsWith('--') && !IGNORE_FILE_FLAGS.has(a));
  if (bad.length) throw new Error(`remove ${bad.join(', ')}: ignore-file supports only --shared/--local`);
}

Prevention

The glob is positional — never invent a --glob flag.
Scope flags are --shared/--local, not --global/--project.
Validate generated command lines against a per-subcommand allowlist before executing them.

When it happens

Trigger: `hooks ignore-file "src/**" --force`; `--glob "src/**"` (inventing a flag for the positional glob); `--reasonx=...`; carrying over flags from other subcommands like --all-values.

Common situations: Agents guessing flag names; users assuming every ignore subcommand shares one flag vocabulary; autocomplete inserting --global instead of --shared.

Related errors

AI-assisted analysis of pbakaus/impeccable@f88b2837a7 (2026-08-18). Data as JSON: /api/errors/4b189de2f3d86df4. Report an issue: GitHub.

Appendix: source

Thrown at skill/scripts/hook-admin.mjs:603

  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);
  const glob = parsed.glob;
  if (!glob) throw new Error(`Pass a glob, e.g. ${IMPECCABLE_COMMAND} hooks ignore-file "src/legacy/**"`);

View on GitHub (pinned to f88b2837a7)