Skip to content

Define the fileContains frontmatter contract #41

Closed

Description

@frap129

Part of #38

Question

What exact public frontmatter shape, validation rules, and matcher algebra should expose fileContains while preserving compatibility with existing rule files? Incorporate the map’s standing preferences for OR literals, AND composition across matcher types, standalone use, case sensitivity, empty values, duplicates, and same-observation correlation.

Activity

  1. self-assigned this
    on Aug 28, 2026
  2. frap129 commented on Aug 29, 2026

    @frap129
    OwnerAuthor

    Resolution

    The fileContains public contract, settled against the map's standing preferences and the current parser/matcher behavior:

    Field syntax

    • Accepts a single YAML string scalar (shorthand for one literal) or a string array of literals: fileContains: "TODO" ≡ fileContains: ["TODO"].
    • OR semantics across literals: the content check passes when any literal matches.
    • Non-string, non-array YAML values (number, boolean, map) are invalid entries and are dropped, matching the existing per-entry leniency in extractStringArray.

    Normalization and validation (fail-closed)

    • Each literal is trimmed; entries empty after trimming are dropped; exact (case-sensitive) duplicates are deduplicated. "Foo" and "foo" remain distinct literals.
    • Empty literals are invalid: if the field is declared but yields no valid literal (empty scalar, null, or every entry empty/invalid), the condition fails closed — the rule never matches and a warning is logged. It must not silently degrade to unconditional injection. This is deliberately stricter than today's fail-open behavior for unparseable frontmatter.

    Matching semantics

    • Case-sensitive literal substring test (includes) on the observation text. Spans lines naturally; no glob, regex, or anchor syntax — regex metacharacters are matched literally.

    Composition: file-observation family

    • globs and fileContains form a file-observation family that always composes with AND over the same single successful file observation: the observation's path matches a glob AND the same observation's text contains a literal. The family counts as one condition check inside the existing match: any|all algebra.
    • fileContains without globs is a family of one: content alone, no path condition (standalone use, per the standing preference).
    • Backward compatible: rules without fileContains behave exactly as today. Other fields remain flat checks. Example: globs + fileContains + keywords under match: any evaluates as (globs AND fileContains) OR keywords.

    Lifetime and correlation

    Spec obligations surfaced

    • The specification must document field syntax with examples, fail-closed validation, and the family algebra (including the (globs AND fileContains) OR keywords example), and enumerate doc surfaces to update in the same change: README matcher sections, docs/rules.md, skills/crafting-rules/SKILL.md.
    • No migration needed for existing rule files; compatibility is preserved by construction.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions