Merge pull request #64 from dmoliveira/my_opencode-e9-rule-schema

docs: define conditional rules schema contract

Author: dmoliveira

CHANGELOG.md

@@ -27,6 +27,7 @@ All notable changes to this project are documented in this file.
 - Added `scripts/keyword_mode_schema.py` and `scripts/keyword_mode_command.py` to parse prompt keywords, resolve precedence-aware mode flags, and persist keyword mode runtime context.
 - Added `/keyword-mode` aliases (`status|detect|apply`) to inspect and apply keyword-triggered execution modes.
 - Added keyword mode controls for global enable/disable and per-keyword toggles (`disable-keyword` / `enable-keyword`) with persisted config state.
+- Added `instructions/conditional_rules_schema.md` defining rule frontmatter schema, discovery precedence, conflict resolution, and validation requirements for Epic 9 Task 9.1.
 
 ### Changes
 - Documented extension evaluation outcomes and when each tool is the better fit.

IMPLEMENTATION_ROADMAP.md

@@ -45,7 +45,7 @@ Use this map to avoid overlapping implementations.
 | E6 | Session Intelligence and Resume Tooling | paused | Medium | E2 | TBD | Resume when core orchestration stabilizes |
 | E7 | Tmux Visual Multi-Agent Mode | postponed | Low | E2 | TBD | Optional power-user feature |
 | E8 | Keyword-Triggered Execution Modes | done | High | E1, E4 | bd-302, bd-2fb, bd-2zq, bd-3dp | Fast power-mode activation from prompt text |
-| E9 | Conditional Rules Injector | planned | High | E1 | TBD | Enforce project conventions with scoped rules |
+| E9 | Conditional Rules Injector | in_progress | High | E1 | bd-1q8 | Enforce project conventions with scoped rules |
 | E10 | Auto Slash Command Detector | paused | Medium | E1, E8 | TBD | Resume only if intent precision stays high in prototypes |
 | E11 | Context-Window Resilience Toolkit | planned | High | E4 | TBD | Improve long-session stability and recovery |
 | E12 | Provider/Model Fallback Visibility | planned | Medium | E5 | TBD | Explain why model routing decisions happen |
@@ -407,15 +407,16 @@ Every command-oriented epic must ship all of the following:
 
 ## Epic 9 - Conditional Rules Injector
 
-**Status:** `planned`
+**Status:** `in_progress`
 **Priority:** High
 **Goal:** Load project/user rule files with optional glob conditions to enforce coding conventions contextually.
 **Depends on:** Epic 1
 
-- [ ] Task 9.1: Define rule file schema and precedence
-  - [ ] Subtask 9.1.1: Define frontmatter fields (`globs`, `alwaysApply`, `description`, `priority`)
-  - [ ] Subtask 9.1.2: Define project/user rule search paths
-  - [ ] Subtask 9.1.3: Define rule conflict resolution strategy
+- [x] Task 9.1: Define rule file schema and precedence
+  - [x] Subtask 9.1.1: Define frontmatter fields (`globs`, `alwaysApply`, `description`, `priority`)
+  - [x] Subtask 9.1.2: Define project/user rule search paths
+  - [x] Subtask 9.1.3: Define rule conflict resolution strategy
+  - [x] Notes: Added `instructions/conditional_rules_schema.md` with deterministic discovery, matching, precedence, conflict handling, and validation requirements.
 - [ ] Task 9.2: Implement rule discovery and matching engine
   - [ ] Subtask 9.2.1: Discover markdown rule files recursively
   - [ ] Subtask 9.2.2: Match rules by file path and operation context

instructions/conditional_rules_schema.md

@@ -0,0 +1,73 @@
+# Conditional Rules Schema
+
+Epic 9 Task 9.1 defines the schema and precedence contract for conditional rule injection.
+
+## Rule sources and discovery
+
+Rules are discovered from layered scopes in deterministic order:
+
+1. user scope: `~/.config/opencode/rules/**/*.md`
+2. project scope: `.opencode/rules/**/*.md`
+
+Project scope has higher precedence when two rules have equivalent priority and target overlap.
+
+## Rule file format
+
+Each rule file is markdown with YAML frontmatter.
+
+Required frontmatter fields:
+
+- `description`: short purpose summary
+- `priority`: integer from `0` to `100` (higher applies first)
+
+Optional frontmatter fields:
+
+- `globs`: list of file globs where rule applies
+- `alwaysApply`: boolean forcing rule application regardless of file path
+- `id`: stable rule identifier (fallback: normalized file stem)
+- `tags`: list of category tags for diagnostics/reporting
+
+Rule body (markdown after frontmatter) is the instruction payload injected at runtime.
+
+## Matching semantics
+
+- If `alwaysApply` is `true`, the rule always applies.
+- Else if `globs` is present, any glob match applies the rule.
+- Else the rule is considered inactive by default.
+
+Glob matching uses workspace-relative POSIX-style paths.
+
+## Conflict resolution
+
+Sort and merge rules by deterministic key:
+
+1. descending `priority`
+2. scope precedence (`project` before `user`)
+3. lexical `id`
+
+Conflicts are resolved by first-writer-wins over normalized rule ids after sorting.
+
+Diagnostics must surface:
+
+- winning rule id and source
+- overridden/conflicting rule ids
+- effective ordered rule stack for any target path
+
+## Config controls (for Task 9.3)
+
+Planned config controls:
+
+- `rules.enabled` (default `true`)
+- `rules.disabled_ids` (list)
+- `rules.extra_paths` (additional discovery roots)
+
+## Validation requirements
+
+Reject and report rules when:
+
+- required frontmatter keys are missing
+- `priority` is out of range or non-numeric
+- `globs` is not a list of strings
+- `alwaysApply` is non-boolean
+
+Validation errors should include rule path and actionable remediation.