You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Define the acceptance contract for file-content matching #44
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.
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.
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.
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.
Activity
frap129 commentedon Aug 29, 2026
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
fileContainsaccepts one YAML string or an array of strings. A scalar is shorthand for a one-element array.fileContainsis durable and may be used withoutglobs.globsandfileContainsform 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 existingmatch: any|allalgebra. Other condition families retain their current algebra; for example,globs+fileContains+keywordsundermatch: anymeans(globs AND fileContains) OR keywords.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:
A successful observation of
src/lib.rscontainingunsafe {matches. A Rust file without that literal does not; a non-Rust file containing it does not..rsis 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.
oldStringplus addednewString, keyed to the submitted file path.No results foundresult, keyed only to the queried file path. Paths or URIs mentioned in the result do not create additional observations.Multi-file coverage must prove same-observation correlation: if one file's path satisfies
globswhile another file's text satisfiesfileContains, 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
unmatched → pending; this observation seam is the only activation path.Compatibility and user surfaces
fileContainsretain their matching algebra, lifetime, identity, framing, and delivery behavior.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.fileContainsto the existing TUI condition summary without introducing a new interface.docs/rules.md, and the crafting-rules skill.Required architecture and sequencing
RuleDeliveryowns the single match-submission seam, activation transitions, serialization, deduplication, history reconciliation, and ledger acknowledgement. Observation producers do not manipulate delivery state.Non-goals
Regular expressions, case-insensitive matching, all-literals semantics,
fileContainsin hooks, unsupported content sources, proactive workspace scans, historical event replay, a new diagnostics/UI surface, and the OpenCode v2 migration are outside this specification.