keystones

Force SME review of load-bearing code by pinning a review gate to an AST node instead of a file path.

Mark a function with a one-line comment. A CODEOWNERS-guarded sidecar file records its canonical hash, its source and the reason it matters. Change the function and the hash stops matching, so the only way to get a green build is to edit the sidecar, which puts its owner on the pull request.

CODEOWNERS can only say "someone owns this file", which means protecting one 20-line function also drags its owner into every typo fix in the other 800 lines. That is why those rules get deleted. A keystone protects the function.

Install

pip install keystones          # Python only, zero dependencies
pip install 'keystones[all]'   # adds TypeScript, JavaScript, Go and Terraform

As a pre-commit hook:

repos:
  - repo: https://github.com/KyleJamesWalker/keystones
    rev: v0.1.0
    hooks:
      - id: keystones          # staged files, warns on drift
      - id: keystones-all      # whole repo, blocking
        additional_dependencies: ["tree-sitter-language-pack==1.20.0"]

Pin the grammar pack in your own config, not via this package. The hooks run in an environment pre-commit builds for them, so additional_dependencies fixes the grammar version for your repo without colliding with anything your project itself depends on, and without waiting for a keystones release to move it. The package declares a range; your repo decides the version.

The local hook is advisory: --no-verify skips it. The gate is keystones check --all running in CI, which cannot be skipped. Put .pre-commit-config.yaml in CODEOWNERS, or the gate can be removed by deleting three lines of YAML.

Quickstart

keystones add billing/payout.py::compute_payout \
    --id payout-rounding --category finance \
    -m "GAAP rounding, see the 2026 finance sign-off"

That writes the marker into the source and the sidecar entry:

# keystone(finance): payout-rounding
def compute_payout(amount: Decimal) -> Decimal:
    return amount.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

Change the rounding mode and keystones check --all fails. Acknowledge it:

keystones fix -m "switched to banker's rounding per policy review"

fix refuses to run without -m when the change is semantic. The resulting sidecar diff contains the old and new source, so the owner reviews code rather than a hash.

Dependencies and staleness

A keystone can name same-repo symbols it depends on, so a change one call frame away is still an owner-review event:

keystones add billing/payout.py::compute_payout --id payout-rounding \
    --category finance -m "GAAP rounding" \
    --depends billing/helpers.py::BASE_RATE \
    --depends billing/helpers.py::quantize

review_every = "180d" sets a staleness budget. There is deliberately no reviewed field: a stored date would be whatever fix last wrote, so the age comes from git log on the sidecar itself. Going stale warns and shows up in keystones list --stale; it never fails the build.

Configuration

[tool.keystones]
root = "keystones"
categories = ["default", "finance"]
exclude = ["**/generated/**"]

One sidecar file per keystone, inside a per-category directory, so each category gets its own reviewers and two concurrent changes can never conflict:

keystones/
  finance/payout-rounding.md
  INDEX.md                     # generated by `keystones index`

# CODEOWNERS
/keystones/finance/  @org/finance-eng

What changing "the code" means

The hash is taken over a canonical rendering of the AST node, not its text.

Markers are found by lexing, so a marker-shaped string literal is not a marker. A marker above a decorator attaches to the function it decorates.

What this is not

A process control, not a security control. Someone who wants around it can delete the marker and the entry in one pull request. That pull request is CODEOWNERS-gated and the deletion is legible in the diff. Known gaps:

• Indirection. A keystone on compute_payout says nothing about a helper it calls, unless you name that helper in depends. Naming it is opt-in and manual, so the hole is narrowed rather than closed.
• Copy and repoint. Copying the body to a new unmarked function and repointing callers is undetectable.
• CODEOWNERS is not self-executing. It requests a reviewer. The block only exists when branch protection requires Code Owner review and dismisses stale approvals. keystones doctor audits that, and needs a token with admin:repo to do it. With no token it skips; with a token it cannot use, it fails rather than reporting success it cannot vouch for.
• A keystone protects one definition, not a name. It records the target it covers and fails if the marker moves off it, but nothing stops a caller being repointed at different code entirely.

Any file type

Python gets AST granularity. Everything else gets whole-file or region keystones, with no parser and no dependency:

# keystone:start(infra): vpc-peering-cidrs
resource "google_compute_network_peering" "prod" {
  peer_network  = var.peer
  export_routes = true
}
# keystone:end

Editing inside the region trips the gate; editing elsewhere in the file does not. That is the point of regions - a whole-file keystone on a formatter-managed YAML or Terraform file trips on every unrelated edit, which gets the tool uninstalled.

#, //, --, /* */ and <!-- --> all work. Region bodies are compared as normalised text (LF, no trailing whitespace, no runs of blank lines), so a reformat inside a region does trip it. Only the Python adapter is reformat-immune.

A file that documents markers rather than carrying them opts out with a keystones: ignore-file directive anywhere in it. This README has one.

A marker already written into a file is adopted without passing a target:

keystones add --id vpc-peering-cidrs -m "Peering CIDRs are load bearing"

Languages

tree-sitter languages need the all extra, which declares a range rather than a pin. The grammar version is recorded in each entry's hasher id, and that, not the install requirement, is what makes hashes deterministic.

A version difference is only reported when it actually matters. On a mismatch the hash is recomputed first: if it still reproduces, the grammar emits the same thing and nothing is said. Only when the two genuinely disagree does it surface, and then as a hasher mismatch rather than as code drift, because from there it is not possible to tell a moved basis from changed code.

keystones fix refuses to write from an environment whose hasher differs from the one an entry records. Without that, running fix with the wrong grammar pack installed would store a hash CI cannot reproduce, and the next check would ask for another fix, forever.

An entry this install cannot verify is an error, not a warning: skipping the hash checks on an unrecognised hasher would make that field a way to switch them off. keystones migrate then moves those entries across, and proves the move rather than asserting it: the stored canonical source is re-rendered under the new hasher, and only when that matches the new hash of the live code does the entry migrate, with no note and no owner review. Where the code changed too, the entry is left alone for the normal gate. A hasher version is a wire format; versions are never removed.

For JavaScript and TypeScript the hash also folds away the things prettier changes on its own: quote style, number spelling (1.50 and 1.5), redundant parentheses, arrow-parameter parens, and a trailing separator. Operators and interior separators are kept, so a + b and a - b differ, and so do [a,,b] and [a,b]. The export keyword and a const/let/var binding are inside the hash, so un-exporting a symbol is a change.

Status

Phase 2 in progress.

The hasher is versioned (keystones-ast/1) and treated as a wire format. A pinned-hash test runs on every supported CPython minor, because a hash basis that moves would fail every keystone at once.

License

MIT