Skip to content

feat(rules): cascade gating for rule evaluation - #148

Merged
mindsocket merged 2 commits into
mainfrom
issue-115-cascade-gating
Oct 13, 2026
Merged

mindsocket merged 2 commits into
mainfrom
issue-115-cascade-gating

Conversation

@mindsocket

@mindsocket mindsocket commented Oct 13, 2026 •

Copy link
Copy Markdown
Owner

Closes #115. 579 tests pass; typecheck and biome clean.

Second commit bumps biome to 2.5.15 and fixes one lint error in a test.

Mechanism

Gating only applies to rule evaluation ($metadata.rules), and only when the schema declares a main hierarchy. Without one, validateRules runs exactly as before.

  1. Seeds. Two always-run checks produce seeds, one per failing node:
    • schema validation failure (nodeErrors), reason schema
    • hierarchy structure violation (hierarchyViolations), reason hierarchy
  2. Traversal. evaluateRulesWithGating (src/schema/gating.ts) walks the main hierarchy breadth-first from roots and orphans. At each node:
    • schema seed: the node's own rules are skipped, and its subtree is gated
    • hierarchy seed: the node's own rules still run, and its subtree is gated
    • a rule violation where the rule gatesDescendants is true: the node's other rules still run, and its subtree is gated
    • already gated by an ancestor: the node is skipped, and inherits the original blocker (no new gate is created)
  3. Not gated, ever.
    • scope: global rules
    • non-hierarchy nodes (types outside the main hierarchy)
  4. Output. coverageGates: [{file, nodeTitle, reason: schema|hierarchy|rule, ruleId?, gatedFiles[]}] in --json, plus a "Coverage" section and a "Rule checks gated" count in text output.

Configurable

Control Where Effect
gatesDescendants per rule, in $metadata.rules whether violations of this rule gate the subtree. Default: true for error severity, false for warning/info. Explicit true/false overrides.
--include-gated sctx validate, sctx validate-file gated nodes' rules run anyway, and the gate is still reported
--depth <n> sctx validate removes hierarchy nodes deeper than n (roots and orphans = 1) before any validation. Reported as skippedByDepth.

--depth isn't gating. It's manual scoping, and it applies to every check, not just rules.

validate-file

Same gating as validate: rules run for the whole space and the output is restricted to the file, so validate-file F equals validate restricted to F (tested for every fixture file, with and without --include-gated). A gated file gets a gated:<file> info entry under warnings saying why its rules weren't checked. --depth is not supported.

What gating does NOT touch

  • Schema (AJV) validation: always runs on every node. Failures are seeds, never suppressed.
  • Hierarchy/graph validation (validateGraph: broken links, ordering, duplicates): always runs. Failures are seeds.
  • Orphans, content-link warnings, parse issues: unaffected.
  • Other hierarchies: only the main hierarchy gates. Schemas with several named hierarchies (new on main) get no cascade through the secondary ones.
  • Relationship edges (non-hierarchy parent refs) don't propagate gates.

Open points

  1. Depth + links. Checked: non-hierarchy references to nodes excluded by --depth do not surface as broken-link errors (covered by a test).
  2. Semantic rules (#114). Not in this PR. The plan: a judge consumes the gate output. For validate-file --semantic F, it lazily judges only gate-capable semantic rules on F's ancestors (top-down, stopping at the first gate), then F's own rules.
  3. Biome. tests/schema/schema-composition.test.ts trips noUnsafeOptionalChaining on biome 2.5.1. It's pre-existing on main and I haven't touched it.

Schema failures, hierarchy violations and gating rule violations suppress
rule evaluation for a node's main-hierarchy subtree, avoiding wasted
downstream checks on inputs already known to be bad. Gated coverage is
reported in validate output (human and --json) so callers can see what
wasn't evaluated and why.

Rules gain `gatesDescendants`, defaulting to true for error severity and
false for warning/info. `sctx validate-file` applies the same gating, so a
file's rule results match its entry in a full validate run, and reports a
`gated` info entry when its rules were skipped.

Adds `--depth <n>` to scope validation to a breadth-first hierarchy depth,
and `--include-gated` to evaluate gated rules while still reporting them.
@claude

claude Bot commented Oct 13, 2026

Copy link
Copy Markdown

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

@mindsocket
mindsocket merged commit df5da90 into main Oct 13, 2026
2 checks passed
@mindsocket
mindsocket deleted the issue-115-cascade-gating branch October 13, 2026 09:48
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.

Layered rule evaluation: cascade gating and coverage annotation

1 participant