Skip to main content

Configuration Strategy

This page is a troubleshooting guide for the most common configuration problems. For the full configuration model — file precedence, field definitions, and defaults — see Configuration Reference.

Two-file model summary: .zenzic.toml holds shared project defaults; .zenzic.local.toml holds machine-local overrides and is not committed. Scalar fields follow last-write-wins. List fields (forbidden_patterns, excluded_dirs) are additive.

Troubleshooting Matrix​

External link validation only runs when --strict is passed. Omitting the flag disables all network requests entirely. To permanently suppress specific URLs without removing strict mode, add their prefixes to excluded_external_urls in .zenzic.toml:

.zenzic.toml
excluded_external_urls = [
    "https://internal.company.com",
    "https://github.com/MyOrg/private-repo",
]

zenzic:ignore does not suppress a Z2xx finding​

Z2xx codes (Z201, Z202, Z203, Z204) are non-suppressible. They bypass the suppression system entirely. The zenzic:ignore directive has no effect on these codes.

Resolution: Remove the content that triggers the finding. There is no configuration flag to disable Z2xx rules.

Forbidden pattern declared in .zenzic.local.toml is not detected​

Possible causes:

CauseDiagnosticFix
File not foundzenzic config show → check forbidden_patterns listVerify path: .zenzic.local.toml must be in the repo root
Pattern uses PCRE syntaxPattern silently not matchedUse RE2 DFA syntax. Lookaheads and backreferences are not supported
File is git-ignored and not present in CIZ204 only fires locallyProvision patterns via CI secret (see Privacy Gate)

Files that should be excluded are still scanned​

excluded_dirs and excluded_file_patterns in .zenzic.toml apply only to documentation source files. They do not interact with .gitignore.

System-excluded paths (never need to be declared):

  • Build output: build/, dist/, temp/, tmp/, .tox/, mutants/
  • Toolchain: .git/, .venv/, node_modules/
  • Config files: *.toml, *.yaml, *.json, *.lock, Makefile, justfile

Only repo-specific entries not in the system exclusion list belong in excluded_dirs.

fail_under threshold not respected​

fail_under applies to the Documentation Quality Score (DQS), not to individual finding counts. A score of 0 from the Security Override (Z2xx present) always exits 2 regardless of fail_under.

Verify the effective threshold:

zenzic config show | grep fail_under

Score is 0 but no credentials are present​

Z204 (FORBIDDEN_TERM) also triggers the Security Override. Run:

zenzic check all --verbose

Look for Z204 in the output. If forbidden_patterns in .zenzic.local.toml matches content in your documentation, the score collapses to 0.

Local override not applied in CI​

.zenzic.local.toml is git-ignored and not present in CI checkouts by default. This is expected. To apply overrides in CI, write the file from a secret before running Zenzic:

- name: Write local zenzic overlay
  env:
    FORBIDDEN: ${{ secrets.ZENZIC_FORBIDDEN_PATTERNS }}
  run: printf '[governance]\nforbidden_patterns = %s\n' "$FORBIDDEN" > .zenzic.local.toml

For the full field specification, see Configuration Reference.