Add Rule Conflict Detection to LevelUp Extension

[kanfil]

Summary

Add rule conflict detection capabilities to the LevelUp extension to ensure team-ai-directives rules don't contradict each other, aligning with the "World-Class Agentic Engineer" principle of periodic rule cleanup.

Context

The "World-Class Agentic Engineer" article states:

Iterate and Clean Up: Periodically review and clean these files up to ensure they don't contradict each other and cause performance degradation.

Currently, the platform:

• ✅ Validates constitution for conflicts (validate-constitution.sh)
• ❌ Does NOT validate rules for conflicts across team-ai-directives
• ✅ Checks for duplicates in levelup (rule coverage)
• ⚠️ Flagged as "Future enhancement" in constitution-levelup.sh:232

Proposed Solution

Overview

Add two conflict detection mechanisms:

1. During CDR Clarification (/levelup.clarify): Check new rule CDRs against existing directives
2. Standalone Validation (/levelup.validate): Scan entire team-ai-directives and create CDRs for resolution

Key Design Decisions

Decision	Choice	Rationale
Conflict Resolution Strategy	B: Warn but let user decide	Flexible - users know best
Remediation Suggestions	A: Generic suggestions (edit rules, add exception)	Simple, customizable
Constitution Conflicts	Higher severity (CRITICAL)	Constitution wins over rules
Workflow	Validate → CDR → Implement → PR	Aligns with existing levelup flow

Architecture

extensions/levelup/
├── commands/
│   ├── clarify.md       [MODIFY] Add conflict detection phase
│   └── validate.md      [CREATE]  Standalone validation command
├── scripts/
│   ├── bash/
│   │   ├── validate-directives.sh          [CREATE] Main validation
│   │   ├── validate-rule-conflicts.sh      [CREATE] Helper
│   │   └── conflict-resolution-templates.sh [CREATE] Suggestions
│   └── powershell/     [CREATE equivalents]
└── templates/
    ├── conflict-cdr-template.md            [CREATE] CDR template
    └── conflict-report-template.md         [CREATE] Markdown report

Conflict Levels

Level	Pattern	Example	Severity
1: Direct Contradiction	must X vs never X	"Must cache" vs "Never cache"	CRITICAL
2: Implicit Contradiction	Logical impossibility	"Cache <50ms" vs "Cache >100ms"	ERROR
3: Exception Conflict	Base vs exception	"No secrets in logs" vs "Log for debug"	WARNING
4: Scope Overlap	Overlapping rules	"All services stateless" vs "DB service stateful"	INFO
5: Constitution Conflict	Rule vs principle	"Must cache" vs Principle: "No caching"	CRITICAL

/levelup.validate Command

Purpose: Scan entire team-ai-directives for conflicts

Execution Flow:

1. Load all rules from context_modules/rules/**/*.md
2. Pairwise comparison for contradictions
3. Constitution principle check
4. Generate conflict report (JSON or Markdown)
5. Create CDRs for each detected conflict

Output Example:

{
  "overall_status": "warn",
  "total_rules": 42,
  "conflicts_detected": 3,
  "conflicts": [
    {
      "id": "conflict-001",
      "level": "critical",
      "type": "direct_contradiction",
      "rule_a": "cache/strategy.md: Must cache for 5min",
      "rule_b": "data-freshness.md: Never cache sensitive data",
      "contradiction": "Must cache vs Never cache",
      "created_cdr": "CDR-001"
    }
  ]
}

/levelup.clarify Integration

Modification: Add conflict detection phase for rule-type CDRs

User Experience:

11. Does this rule conflict with existing rules or constitution?
   - [ ] No conflicts detected
   - [ ] Direct contradiction found
   - [ ] Semantic conflict found
   - [ ] Constitution principle conflict

12-15. Resolution questions:
    - Add documented exception
    - Edit wording
    - Reject this CDR
    - Defer to other rule
    - Accept and update existing rule

CDR Creation Workflow

Template (conflict-cdr-template.md):

## CDR-{ID}: Resolve Rule Conflict: {title}

### Status: Proposed
### Date: {TODAY}

### Conflict Details
- Rule A: {path}:{line} - "{statement}"
- Rule B: {path}:{line} - "{statement}"
- Type: {critical|error|warning|info}

### Remediation Options
1. Add Exception: Modify rule to document exception
2. Edit Rule: Reword to avoid conflict
3. Mark Intentional: Document overlap
4. Depricate Rule: Remove one rule

### Proposed Content
{Generic rewrite suggestions}

End State: /levelup.implement creates PR with conflict resolutions

Implementation Plan

Files to Create

File	Purpose
extensions/levelup/commands/validate.md	Command spec
extensions/levelup/scripts/bash/validate-directives.sh	Main validation
extensions/levelup/scripts/bash/validate-rule-conflicts.sh	Clarify helper
extensions/levelup/templates/conflict-cdr-template.md	CDR template

Files to Modify

File	Changes
extensions/levelup/commands/clarify.md	Add conflict detection phase
extensions/levelup/extension.yml	Register validate command
extensions/catalog.json	Update command list
extensions/levelup/README.md	Document feature
extensions/levelup/CHANGELOG.md	Add changelog entry

Testing Strategy

• Unit tests: Direct contradiction, semantic conflict detection
• Integration tests: Full validate → CDR → implement → PR workflow
• Manual tests: 5+ conflict scenarios

Alternatives Considered

Option	Pros	Cons
Add to validate-constitution.sh	Reuse existing code	Constitution-specific, not rules
Pure CLI-based detection	No Python dependency	Can't use skills registry tools
AI-based detection	Sophisticated semantic analysis	Overkill, introduces LLM dependency

Dependencies

• Existing: setup-levelup.sh, validate-constitution.sh
• External: None (uses jq, grep, find - already present)

Acceptance Criteria

• /levelup.validate scans team-ai-directives and reports conflicts
• /levelup.clarify warns on rule conflicts with resolution options
• CDRs created for detected conflicts with generic remediation
• /levelup.implement creates PR with conflict resolutions
• Conflict levels: critical, error, warning, info, constitution
• Integration tests pass (coverage >80%)

Estimated Effort

Phase	Effort
Scripts & Commands	1 day
Unit Tests	0.5 day
Integration Tests	0.5 day
Documentation	0.5 day
Total	2.5 days

Questions

1. Constitution format: Assume template (### I. Principle) or detect dynamically?
2. Semantic depth: Start with keyword-based or more sophisticated?
3. CDR overflow: What if >50 conflicts (limit vs fail-fast)?
4. Mandatory vs optional: Validate required before accepting rule CDRs?

References

• "How To Be A World-Class Agentic Engineer" article (overall rule cleanup principle)
• /levelup extension architecture
• Existing validate-constitution.sh (constitution conflict detection)
• constitution-levelup.sh:232 (future enhancement comment)