Configuration

Status: current (2026-07-26)

All project-specific surface lives in one file, {schema.config_file_name}, at the consuming repo’s root (override with --config). Every key is optional; an absent file yields defaults (doc root docs/, standard class vocabulary, count-drift and behavioral-claims skipped because they need project input).

The toolkit pins its own ruff version in pyproject.toml — this snippet is sliced live from the source file, so a drift in either place fails the build:

pyproject.toml

[tool.ruff]
line-length = 100
src = ["src", "tests"]

Ruff pin and line-length live in pyproject.toml.

Fields

The 12 fields of {schema.config_file_name} are projected directly from the Config dataclass in src/jk_standards/config.py:

Field	Type	Default
`claim_sources`	`list[ClaimSource]`	`[]`
`count_triggers`	`list[str]`	`[]`
`deps_only_manifests`	`list[str]`	`[]`
`doc_roots`	`list[DocRoot]`	`[{"extensions":[".md"],"path":"docs"}]`
`drift_map`	`str`	`".github/docs-drift-map.yml"`
`exempt_dirs`	`list[str]`	`[]`
`file_line_extensions`	`list[str]`	`["c","cc","cpp","h","hpp","py","js","mjs","ts","tsx","astro","md","mdx","sh","yml","yaml"]`
`file_line_source_roots`	`list[SourceRoot]`	`[]`
`generated`	`list[GeneratedDoc]`	`[]`
`status_forbidden_extra`	`list[ForbiddenPhrase]`	`[]`
`taxonomy_classes`	`list[str]`	`["generated","gated","archived"]`
`taxonomy_extra_files`	`list[str]`	`[]`

Example — this repo’s own config

jk-standards dogfoods itself, so its own jk-standards.yaml is a live example of every wired feature. Sliced from the source:

jk-standards.yaml

version: 1

doc_roots:
  - path: docs
    extensions: [".md"]
  - path: site/src/content/docs
    extensions: [".mdx"]

taxonomy:
  classes: [generated, gated, archived]

file_line_refs:
  source_roots:
    - path: src
      extensions: [".py"]

# Inventory facts about the toolkit itself (how many checks, hooks, skills)
# must not be restated as numerals in the docs — they change as checks land.
# region:count-triggers
count_drift:
  triggers:
    - 'checks?\s+(?:in\s+total|total)'
    - 'hooks?\s+(?:in\s+total|total)'
    - 'skills?\s+(?:in\s+total|total)'
    - 'checks?\s+ship(?:s|ped)?'
    - 'hooks?\s+ship(?:s|ped)?'
    - 'skills?\s+ship(?:s|ped)?'
    - 'fields?\s+(?:in|of)\s+(?:the\s+)?config'
    - '(?:checks?|skills?|hooks?|fields?)\s+are\s+available'
    - '(?:checks?|skills?|hooks?|fields?)\s+are\s+registered'
# endregion:count-triggers

drift_map: .github/docs-drift-map.yml

behavioral_claims:
  sources:
    - type: pytest
      path: tests

# Site JSON fixtures projected from Python source. `generated-freshness`
# runs each command, diffs against the tracked file, and restores the
# snapshot — so a source change without a regenerated fixture fails CI.
#
# coverage.json is intentionally NOT gated here: coverage numbers are
# environment-dependent (Python version, platform branches) and would drift
# between local dev and CI even with no source change. The emitter still
# runs at site-build time (site/package.json prebuild) so the site always
# shows current coverage; it just isn't diff-gated.
# region:generated-fixtures
generated:
  - doc: site/src/generated/checks.json
    command: jk-standards emit checks
  - doc: site/src/generated/config-schema.json
    command: jk-standards emit config-schema
  - doc: site/src/generated/skills.json
    command: jk-standards emit skills
# endregion:generated-fixtures

jk-standards.yaml — the toolkit gates itself with itself.

CLI

jk-standards <check-name> [--root DIR] [--config FILE] [--base REF]
jk-standards all            # every configured static check (+ doc-drift
                            # when --base or GITHUB_BASE_REF is available)
jk-standards list           # list check names
jk-standards emit <name>    # regenerate one drift-proof fixture under
                            # site/src/generated/; <name> is one of
                            # checks | config-schema | skills | coverage | all
jk-standards emit <name> --check
                            # exit 1 if the on-disk fixture differs from
                            # what would be emitted now (CI drift gate)

Exit codes: 0 clean, 1 violations, 2 usage/config error. Checks whose config section is empty report themselves as skipped rather than failing — adoption is incremental by design.

Consuming

Pre-commit (pin to a release tag):

- repo: https://github.com/JimAKennedy/jk-standards
  rev: v0.1.0
  hooks:
    - id: doc-taxonomy
    - id: status-prose
    - id: file-line-refs

CI (the reusable workflow supplies checkout depth and base-ref wiring):

.github/workflows/doc-discipline.yml

jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
        with:
          fetch-depth: 0

      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install jk-standards
        run: pip install "git+https://github.com/JimAKennedy/jk-standards@${{ inputs.toolkit-ref }}"

      - name: Run checks
        run: jk-standards all --config "${{ inputs.config }}"

The reusable doc-discipline workflow.