Merge pull request #66 from dmoliveira/my_opencode-e9-rules-ops

feat: add rules command operations and diagnostics

Author: dmoliveira

CHANGELOG.md

@@ -29,6 +29,7 @@ All notable changes to this project are documented in this file.
 - 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.
 - Added `scripts/rules_engine.py` implementing frontmatter parsing, layered rule discovery, path-based matching, deterministic precedence sorting, and duplicate-id conflict reporting.
+- Added `scripts/rules_command.py` with `/rules status`, `/rules explain`, per-rule disable/enable controls, and `/rules doctor` diagnostics.
 
 ### Changes
 - Documented extension evaluation outcomes and when each tool is the better fit.
@@ -58,6 +59,7 @@ All notable changes to this project are documented in this file.
 - Added `/keyword-mode doctor --json` diagnostics and integrated keyword subsystem health into unified `/doctor` checks.
 - Expanded keyword mode verification for false-positive resistance (partial words and code-literal contexts) and opt-out/toggle smoke scenarios.
 - Expanded selftest coverage for conditional rule discovery and effective-stack resolution behavior.
+- Added `/doctor` rules subsystem integration and expanded install/selftest coverage for rules command workflows.
 
 ## v0.2.0 - 2026-02-12
 

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 | in_progress | High | E1 | bd-1q8, bd-3rj | Enforce project conventions with scoped rules |
+| E9 | Conditional Rules Injector | in_progress | High | E1 | bd-1q8, bd-3rj, bd-fo8 | 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 |
@@ -422,10 +422,11 @@ Every command-oriented epic must ship all of the following:
   - [x] Subtask 9.2.2: Match rules by file path and operation context
   - [x] Subtask 9.2.3: Inject effective rule set into execution context
   - [x] Notes: Added `scripts/rules_engine.py` with frontmatter parsing, layered discovery, deterministic precedence sorting, duplicate-id conflict reporting, and effective rule stack resolution helpers.
-- [ ] Task 9.3: Operations and diagnostics
-  - [ ] Subtask 9.3.1: Add `/rules status` and `/rules explain <path>` commands
-  - [ ] Subtask 9.3.2: Add per-rule disable list in config
-  - [ ] Subtask 9.3.3: Add doctor output for rule source and conflicts
+- [x] Task 9.3: Operations and diagnostics
+  - [x] Subtask 9.3.1: Add `/rules status` and `/rules explain <path>` commands
+  - [x] Subtask 9.3.2: Add per-rule disable list in config
+  - [x] Subtask 9.3.3: Add doctor output for rule source and conflicts
+  - [x] Notes: Added `scripts/rules_command.py` with status/explain/disable-id/enable-id/doctor workflows, wired `/doctor` integration for rules diagnostics, and added command aliases/install smoke coverage.
 - [ ] Task 9.4: Verification and docs
   - [ ] Subtask 9.4.1: Add tests for glob matching and precedence
   - [ ] Subtask 9.4.2: Add docs with examples for team rule packs

Makefile

@@ -56,6 +56,7 @@ install-test: ## Run installer smoke test in temp HOME
 	if [ -f "$$TMP_HOME/.config/opencode/my_opencode/scripts/hooks_command.py" ]; then HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/hooks_command.py" status; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/hooks_command.py" enable; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/hooks_command.py" disable-hook error-hints; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/hooks_command.py" run error-hints --json '{"command":"git status","exit_code":128,"stderr":"fatal: not a git repository"}'; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/hooks_command.py" enable-hook error-hints; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/hooks_command.py" doctor --json; fi; \
 	if [ -f "$$TMP_HOME/.config/opencode/my_opencode/scripts/model_routing_command.py" ]; then HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/model_routing_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/model_routing_command.py" resolve --category deep --override-model openai/nonexistent --available-models openai/gpt-5-mini,openai/gpt-5.3-codex --json; fi; \
 	if [ -f "$$TMP_HOME/.config/opencode/my_opencode/scripts/keyword_mode_command.py" ]; then HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/keyword_mode_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/keyword_mode_command.py" doctor --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/keyword_mode_command.py" disable-keyword ulw; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/keyword_mode_command.py" detect --prompt "ulw deep-analyze audit this change" --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/keyword_mode_command.py" detect --prompt "no-keyword-mode safe-apply deep-analyze" --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/keyword_mode_command.py" enable-keyword ulw; fi; \
+	if [ -f "$$TMP_HOME/.config/opencode/my_opencode/scripts/rules_command.py" ]; then HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/rules_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/rules_command.py" explain scripts/selftest.py --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/rules_command.py" disable-id style-python; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/rules_command.py" doctor --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/rules_command.py" enable-id style-python; fi; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/install_wizard.py" --non-interactive --skip-extras --plugin-profile lean --mcp-profile research --policy-profile balanced --notify-profile skip --telemetry-profile local --post-session-profile manual-validate; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/doctor_command.py" run --json
 

README.md

@@ -504,6 +504,29 @@ Anti-patterns:
 - avoid relying on partial words (`deep` or `safe`) because matching is exact-token only.
 - avoid forgetting local opt-outs in copied prompts; `no-keyword-mode` intentionally disables all activation for that request.
 
+## Conditional rules injector
+
+Epic 9 introduces a rules engine for conditional instruction injection:
+
+- schema contract: `instructions/conditional_rules_schema.md`
+- engine implementation: `scripts/rules_engine.py`
+- command wrapper: `scripts/rules_command.py`
+
+Use:
+```text
+/rules status
+/rules explain scripts/selftest.py --json
+/rules disable-id style-python
+/rules enable-id style-python
+/rules doctor --json
+```
+
+Rules are discovered from:
+- user scope: `~/.config/opencode/rules/**/*.md`
+- project scope: `.opencode/rules/**/*.md`
+
+Precedence is deterministic: priority desc, then scope (`project` before `user`), then lexical rule id.
+
 ## Background jobs inside OpenCode 🧵
 
 Use these directly in OpenCode:

install.sh

@@ -152,6 +152,8 @@ printf "  /keyword-mode status\n"
 printf "  /keyword-mode detect --prompt 'safe-apply deep-analyze investigate this refactor'\n"
 printf "  /keyword-mode disable-keyword ulw\n"
 printf "  /keyword-mode doctor --json\n"
+printf "  /rules status\n"
+printf "  /rules explain scripts/selftest.py --json\n"
 printf "  /stack apply focus\n"
 printf "  /nvim status\n"
 printf "  /devtools status\n"

opencode.json

@@ -190,6 +190,22 @@
       "description": "Run keyword mode diagnostics in JSON",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/keyword_mode_command.py\" doctor --json`\nShow only the command output."
     },
+    "rules": {
+      "description": "Inspect conditional rules (status|explain|disable-id|enable-id|doctor)",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/rules_command.py\" $ARGUMENTS`\nShow only the command output."
+    },
+    "rules-status": {
+      "description": "Show rules discovery and config status",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/rules_command.py\" status`\nShow only the command output."
+    },
+    "rules-explain": {
+      "description": "Explain effective rules for a target path",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/rules_command.py\" explain $ARGUMENTS --json`\nShow only the command output."
+    },
+    "rules-doctor": {
+      "description": "Run rules diagnostics in JSON",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/rules_command.py\" doctor --json`\nShow only the command output."
+    },
     "stack": {
       "description": "Apply cross-command profile bundles",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/stack_profile_command.py\" $ARGUMENTS`\nShow only the command output."

scripts/doctor_command.py

@@ -144,6 +144,18 @@ def script_path(name: str) -> Path:
             "--json",
         ],
     },
+    {
+        "name": "rules",
+        "kind": "doctor-json",
+        "optional": True,
+        "required_path": str(script_path("rules_command.py")),
+        "command": [
+            sys.executable,
+            str(script_path("rules_command.py")),
+            "doctor",
+            "--json",
+        ],
+    },
 ]