Skip to content

feat(gate): scan chosen folders for terms, and project codes outside their folder - #11

Merged
pasrom merged 2 commits into
mainfrom
feat/gate-term-scope
Sep 29, 2026
Merged

pasrom merged 2 commits into
mainfrom
feat/gate-term-scope

Conversation

@pasrom

@pasrom pasrom commented Sep 29, 2026

Copy link
Copy Markdown
Owner

Problem

The gate's leak check scans forbidden terms only in audience: customer docs. A customer name in an
internal doc in a customer-neutral folder passes CI, and that is the slip a team brain most needs
caught. The terms file is gitignored, so CI never has it, and fork PRs get no secrets to supply it.

Change

Three opt-in gate keys. With all three unset, the gate behaves exactly as before.

  • term_scan_prefixes (list): folders whose docs are term-scanned whatever their audience.
    bms and bms/ both match bms/..., never bmsx/....
  • project_prefix (str): each tracked subfolder under it is a project code. A code in any doc outside
    its own subfolder is a gate-leak:code error. It matches whole words, treating _ as a separator,
    and the code is redacted in the report. Files directly in the project folder, such as its
    _index.md, may list every code. This check needs no terms file, so it also runs in CI, fork PRs
    included.
  • project_code_pattern (regex): a subfolder name must fully match it to count as a code. This is for
    a project folder that also holds non-customer topics; without it, a folder named after a regulation
    flags every mention of that regulation. An invalid regex fails fast.

Both path-keyed scans run in the text pre-pass with the secret scan, so they also cover exempt files
and _index.md. Codes come from the tracked files, so a local-only folder never changes the result.
The needles are normalised once. The code regex runs only after a plain substring hit, because its
lookbehind makes a full scan slow (measured about 34 times faster on an 840-doc brain). Per-file paths
are made POSIX where they are built.

Verification

  • All four smoke tests pass: gate 50, index 30, team 96, encoding 4.
  • Every new behaviour was mutation-checked: scope, prefix slash, hub skip, own folder, tracked-only
    codes, pre-pass coverage, single report, word boundary, _ separator and pattern. Each mutation
    fails at least one test.
  • Run against a real team brain, main plus 11 open PRs, with project_prefix and a pattern: no
    false positives. A planted code in a neutral doc was reported and redacted.
  • Without a pattern, a topic folder such as projects/cra/ would flag every "CRA" in the brain. That
    case is why project_code_pattern exists.

A release is a separate version bump.

…their folder

The leak check only looked at forbidden terms in audience: customer docs. A
customer name in an internal doc in a customer-neutral folder passed, which
is the slip a team brain most needs caught. Three opt-in gate keys, all off
by default, so existing brains behave as before:

- term_scan_prefixes: folders whose docs are term-scanned whatever their
  audience. "bms" and "bms/" both match bms/..., never bmsx/....
- project_prefix: each tracked subfolder under it is a project code, and a
  code in any doc outside its own subfolder is a gate-leak:code error,
  matched as a whole word ('_' counts as a separator, so a code in a
  snake_case file name is caught) and redacted in the report. Files directly in
  the project folder, such as its _index.md, may list every code. The
  check needs no terms file, so it also runs in CI where that file is
  absent, such as on fork pull requests, which get no secrets.
- project_code_pattern: a regex a subfolder name must fully match to count
  as a code, for a project folder that also holds non-customer topics
  (otherwise a folder named after a regulation flags every mention of it).
  An invalid regex fails fast like the other gate keys.

Both path-keyed scans run in the text pre-pass with the secret scan, so
they also cover exempt files and _index.md, which carry no frontmatter.
Codes come from the tracked files, so a local-only folder never changes
the result. Term and code needles are normalised once; the code regex runs
only after a plain substring hit, since its lookbehind makes a full scan
slow. Per-file paths are made POSIX where they are built, so prefix checks
also hold on Windows.
…ders

With gate.project_prefix set, a project code in frontmatter counts like one
in the body, so the ripple step's related: entries and project: ranking
would make km fail its own gate. Ripple now skips paths under a project
folder for docs outside it, and a smoke case pins that related: counts.
@pasrom
pasrom merged commit a39f63b into main Sep 29, 2026
4 checks passed
@pasrom
pasrom deleted the feat/gate-term-scope branch September 29, 2026 19:33
@pasrom pasrom mentioned this pull request Sep 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant