Skip to content

Define the acceptance contract for file-content matching #44

Closed

Description

@frap129

Part of #38

Question

Which externally observable scenarios, compatibility guarantees, and non-goals must the final GitHub specification contain so an implementation agent can build fileContains without making unresolved product or lifecycle decisions? Include the .rs plus unsafe { scenario and representative Read, Write, Apply Patch, LSP, multi-file, failure, composition, durability, and timing cases.

Activity

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

    @frap129
    OwnerAuthor

    Resolution

    The acceptance contract is behavior-first and normative: implementations may choose unit or integration test placement, but every scenario below requires automated coverage. Internal structure is prescribed only where earlier decisions established a mandatory ownership boundary.

    Public rule contract

    • fileContains accepts one YAML string or an array of strings. A scalar is shorthand for a one-element array.
    • Normalize by trimming entries, dropping non-strings and empty entries, and deduplicating exact strings. Matching is case-sensitive literal substring matching with OR semantics across valid literals; metacharacters have no special meaning and literals may span lines.
    • A declared field that yields no valid literal is an invalid condition: the rule never matches and emits one warning through the existing warning seam and visibility policy. It must never degrade into an unconditional rule.
    • fileContains is durable and may be used without globs.
    • globs and fileContains form one file-observation family. When both are present, one observation must satisfy both its path and content checks. The family is one check in the existing match: any|all algebra. Other condition families retain their current algebra; for example, globs + fileContains + keywords under match: any means (globs AND fileContains) OR keywords.
    • Session-retained observations remain current context. Under match: all, an earlier matching file observation may combine with a later condition such as a keyword to make the rule matched; this is retained live context, not historical-event replay.

    Canonical Rust scenario

    The public example is:

    globs: ["**/*.rs"]
    fileContains: "unsafe {"

    A successful observation of src/lib.rs containing unsafe { matches. A Rust file without that literal does not; a non-Rust file containing it does not. .rs is a path condition, not a content literal.

    File-observation scenarios

    Only successful Read, Write, Edit, Apply Patch, and LSP events produce observations. Paths remain in the verbatim form supplied by the after-hook.

    • Read: Strip result wrapper tags and line-number prefixes, join returned lines with newlines, and match only the returned slice. Truncated or continuation reads never reconstruct omitted text. Binary/image/PDF reads and successful but unparseable file results produce path-only observations; directories produce none.
    • Write: Use the verbatim submitted content, keyed to the submitted file path.
    • Edit: Use removed oldString plus added newString, keyed to the submitted file path.
    • Apply Patch: Produce one observation per touched file. Added files contribute full content; updated files contribute added, removed, and context hunk lines without patch syntax; moved files use the destination path; deleted files are path-only. A successfully applied but unparseable patch falls back to path-only observations from the model-visible summary.
    • LSP: Use the raw successful output, including a No results found result, keyed only to the queried file path. Paths or URIs mentioned in the result do not create additional observations.
    • Failed calls produce no observation. Grep, Glob, Bash, shell, arbitrary/custom/MCP tools, user or assistant prose, attachments, metadata, diagnostics, and other unsupported sources contribute neither paths nor content.

    Multi-file coverage must prove same-observation correlation: if one file's path satisfies globs while another file's text satisfies fileContains, the rule does not match. Multiple matching files, literals, observations, or concurrent tool completions still coalesce to one delivery per rule identity.

    Delivery and lifecycle scenarios

    • A successful matching observation admits the rule synchronously into unmatched → pending; this observation seam is the only activation path.
    • The rule is available at the immediately following provider dispatch under the universal earliest-dispatch contract. Persistence and in-memory transform insertion follow Specify earliest-dispatch delivery for every newly matched rule.
    • A persistence failure leaves the rule pending, exposes it in the applicable dispatch when possible, and retries on later dispatches without turning the successful tool call into a failure. Ledger acknowledgement occurs only after persistence succeeds.
    • Concurrent admissions are serialized per session and deduplicated by the existing rule identity. Ordering and grouping of synthetic messages are unspecified.
    • After delivery, later nonmatching observations never retract or re-arm the rule.
    • Pending activation is in-memory only and may be lost on process restart. A new matching observation can reactivate it.
    • Delivered activation survives resume through the delivery ledger. Message removal and compaction rebuild and re-append from rule identity and source, never by replaying observations. A compaction summary mentioning rule text is not delivery evidence.
    • No startup, proactive, hidden, filesystem, or historical event scan is permitted.
    • Matched-rule sidebar state refreshes when a mid-session durable rule is admitted.

    Compatibility and user surfaces

    • Rules without fileContains retain their matching algebra, lifetime, identity, framing, and delivery behavior.
    • Normalized file observations become the sole path source for globs. The intentional compatibility change is that prose path mentions and excluded-tool arguments/results no longer trigger glob rules; supported file-handling observations continue to do so.
    • Add fileContains to the existing TUI condition summary without introducing a new interface.
    • Update every existing public condition reference: README matching/field/lifetime sections, docs/rules.md, and the crafting-rules skill.

    Required architecture and sequencing

    • Implement Concentrate Working context behind a runtime-owned module, or at minimum its SessionStore/Working-context separation, first.
    • File-observation capture and evaluation live in a separate runtime-owned per-session module, not in SessionStore's Working-context fields.
    • RuleDelivery owns the single match-submission seam, activation transitions, serialization, deduplication, history reconciliation, and ledger acknowledgement. Observation producers do not manipulate delivery state.
    • The contract targets the supported OpenCode v1.x hooks and does not prescribe additional classes, method names, or test-file layout.

    Non-goals

    Regular expressions, case-insensitive matching, all-literals semantics, fileContains in hooks, unsupported content sources, proactive workspace scans, historical event replay, a new diagnostics/UI surface, and the OpenCode v2 migration are outside this specification.

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