Add bd rules audit and bd rules compact commands (#2810)

Filesystem-only tooling to detect contradictions, near-duplicates,
and merge opportunities in .claude/rules/*.md files.

- `bd rules audit` scans rules for contradictions and merge candidates
  using Jaccard similarity, antonym detection, and scope analysis
- `bd rules compact` merges related rules into composites (manual or auto)
- 20 tests, no new dependencies (stdlib + cobra only)
- CheckReadonly guard on compact for consistency with other write commands

Resubmission of #1625, rebased cleanly on current main.

Co-authored-by: anupamchugh <anupamchugh@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Anupam Chugh 2026-04-03 08:59:34 +05:30 • committed by GitHub
commit 6863ca7be8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 1923 additions and 0 deletions

898
cmd/bd/rules.go Normal file
View file

@ -0,0 +1,898 @@
package main
import (
"fmt"
"os"
"path/filepath"
"regexp"
"sort"
"strings"
"text/tabwriter"
"unicode"
"github.com/spf13/cobra"
)
// --- Types ---
// RuleFile represents a parsed .claude/rules/*.md file.
type RuleFile struct {
Path string `json:"path"`
Name string `json:"name"`
Title string `json:"title"`
DoLines []string `json:"do_lines"`
DontLines []string `json:"dont_lines"`
Body string `json:"body,omitempty"`
Keywords []string `json:"keywords"`
Tokens int `json:"tokens"`
}
// ContradictionReport describes a tension between two rules.
type ContradictionReport struct {
RuleA string `json:"rule_a"`
RuleB string `json:"rule_b"`
Tension string `json:"tension"`
DoLineA string `json:"do_line_a"`
DontLineB string `json:"dont_line_b"`
ScopeScore float64 `json:"scope_score"`
}
// MergeCandidate represents a group of rules that could be combined.
type MergeCandidate struct {
GroupLabel string `json:"group_label"`
Rules []string `json:"rules"`
Score float64 `json:"score"`
}
// AuditResult is the full output of `bd rules audit`.
type AuditResult struct {
TotalRules int `json:"total_rules"`
TokenEstimate int `json:"token_estimate"`
Contradictions []ContradictionReport `json:"contradictions"`
MergeCandidates []MergeCandidate `json:"merge_candidates"`
Rules []RuleFile `json:"rules,omitempty"`
}
// --- Stop Words ---
var stopWords = map[string]bool{
"the": true, "a": true, "is": true, "to": true, "for": true,
"and": true, "or": true, "in": true, "of": true, "it": true,
"that": true, "this": true, "with": true, "be": true, "not": true,
"do": true, "don't": true, "use": true, "when": true, "before": true,
"after": true, "should": true, "must": true, "always": true, "never": true,
"an": true, "are": true, "as": true, "at": true, "by": true,
"from": true, "has": true, "have": true, "if": true, "on": true,
"was": true, "were": true, "will": true, "you": true, "your": true,
}
// --- Antonym Pairs ---
// antonymPairs maps words to their antonyms for contradiction detection.
var antonymPairs = map[string][]string{
"block": {"proceed", "parallel"},
"proceed": {"block"},
"parallel": {"block"},
"verbose": {"minimize", "concise"},
"minimize": {"verbose"},
"concise": {"verbose"},
"spawn": {"reuse"},
"reuse": {"spawn"},
"wait": {"skip"},
"skip": {"wait"},
"log": {"suppress"},
"suppress": {"log"},
}
// --- Regex Patterns ---
var (
headingRe = regexp.MustCompile(`(?m)^#\s+(.+)`)
doRe = regexp.MustCompile(`(?i)^\*\*Do:?\*\*:?\s*(.*)`)
dontRe = regexp.MustCompile(`(?i)^\*\*Don'?t:?\*\*:?\s*(.*)`)
)
// --- Core Functions ---
// ParseRuleFile reads a .md file and extracts structured rule data.
func ParseRuleFile(path string) (RuleFile, error) {
data, err := os.ReadFile(path)
if err != nil {
return RuleFile{}, fmt.Errorf("read rule file %s: %w", path, err)
}
content := string(data)
name := strings.TrimSuffix(filepath.Base(path), ".md")
rf := RuleFile{
Path: path,
Name: name,
Body: content,
// Rough token estimate: 1 token ~ 4 chars
Tokens: len(content) / 4,
}
// Extract title from first heading
if m := headingRe.FindStringSubmatch(content); len(m) > 1 {
rf.Title = strings.TrimSpace(m[1])
} else {
rf.Title = name
}
// Extract Do and Don't blocks
rf.DoLines, rf.DontLines = extractAllDirectives(content)
// Extract keywords from Do/Don't lines first, fallback to body
allDirectives := append(rf.DoLines, rf.DontLines...)
if len(allDirectives) > 0 {
rf.Keywords = ExtractKeywords(allDirectives)
} else {
rf.Keywords = ExtractKeywords([]string{content})
}
return rf, nil
}
// extractAllDirectives parses Do and Don't blocks from rule content.
// Don't patterns are checked first to avoid false matches (since "Don't" contains "Do").
func extractAllDirectives(content string) (doLines, dontLines []string) {
lines := strings.Split(content, "\n")
// blockType: 0=none, 1=do, 2=dont
blockType := 0
for _, line := range lines {
trimmed := strings.TrimSpace(line)
// Check Don't first (it contains "Do", so must be checked before Do)
if m := dontRe.FindStringSubmatch(line); len(m) > 1 {
blockType = 2
text := strings.TrimSpace(m[1])
if text != "" {
dontLines = append(dontLines, text)
}
continue
}
if m := doRe.FindStringSubmatch(line); len(m) > 1 {
blockType = 1
text := strings.TrimSpace(m[1])
if text != "" {
doLines = append(doLines, text)
}
continue
}
if blockType != 0 {
// Continuation: line starts with - or is non-empty non-heading text
if strings.HasPrefix(trimmed, "-") || (strings.HasPrefix(trimmed, "*") && !strings.HasPrefix(trimmed, "**")) {
// Strip leading bullet
text := strings.TrimLeft(trimmed, "-* ")
if text != "" {
if blockType == 1 {
doLines = append(doLines, text)
} else {
dontLines = append(dontLines, text)
}
}
} else if trimmed == "" || strings.HasPrefix(trimmed, "#") || strings.HasPrefix(trimmed, "**") {
// End of block
blockType = 0
} else {
// Plain continuation text
if blockType == 1 {
doLines = append(doLines, trimmed)
} else {
dontLines = append(dontLines, trimmed)
}
}
}
}
return doLines, dontLines
}
// ExtractKeywords tokenizes lines, removes stop words, lowercases, and deduplicates.
func ExtractKeywords(lines []string) []string {
seen := make(map[string]bool)
var keywords []string
for _, line := range lines {
words := tokenizeWords(line)
for _, w := range words {
w = strings.ToLower(w)
if len(w) < 2 {
continue
}
if stopWords[w] {
continue
}
if !seen[w] {
seen[w] = true
keywords = append(keywords, w)
}
}
}
sort.Strings(keywords)
return keywords
}
// tokenize splits text into words, stripping punctuation.
func tokenizeWords(s string) []string {
return strings.FieldsFunc(s, func(r rune) bool {
return !unicode.IsLetter(r) && !unicode.IsDigit(r) && r != '\''
})
}
// JaccardSimilarity computes keyword overlap between two keyword sets.
func JaccardSimilarity(a, b []string) float64 {
if len(a) == 0 && len(b) == 0 {
return 0.0
}
setA := make(map[string]bool, len(a))
for _, w := range a {
setA[w] = true
}
setB := make(map[string]bool, len(b))
for _, w := range b {
setB[w] = true
}
intersection := 0
for w := range setA {
if setB[w] {
intersection++
}
}
union := len(setA)
for w := range setB {
if !setA[w] {
union++
}
}
if union == 0 {
return 0.0
}
return float64(intersection) / float64(union)
}
// DetectContradictions finds opposing directives across rule pairs.
// Two rules contradict when they share scope (jaccard >= scopeThreshold)
// and have opposing directives (same verb in Do vs Don't, or antonym pairs).
func DetectContradictions(rules []RuleFile, scopeThreshold float64) []ContradictionReport {
var reports []ContradictionReport
for i := 0; i < len(rules); i++ {
for j := i + 1; j < len(rules); j++ {
a, b := rules[i], rules[j]
score := JaccardSimilarity(a.Keywords, b.Keywords)
if score < scopeThreshold {
continue
}
// Check for direct contradictions: verb in A's Do appears in B's Don't
if c := findDirectContradiction(a, b, score); c != nil {
reports = append(reports, *c)
continue
}
// Check reverse direction
if c := findDirectContradiction(b, a, score); c != nil {
// Swap labels since we checked b->a
c.RuleA, c.RuleB = a.Name+".md", b.Name+".md"
reports = append(reports, *c)
continue
}
// Check for antonym pair contradictions in Do vs Do
if c := findAntonymContradiction(a, b, score); c != nil {
reports = append(reports, *c)
}
}
}
return reports
}
// findDirectContradiction checks if a verb from A's Do appears in B's Don't.
func findDirectContradiction(a, b RuleFile, scopeScore float64) *ContradictionReport {
aDoWords := extractActionWords(a.DoLines)
bDontWords := extractActionWords(b.DontLines)
for word, doLine := range aDoWords {
if dontLine, ok := bDontWords[word]; ok {
tension := truncateTension(
fmt.Sprintf("%q vs %q", summarizeLine(doLine), summarizeLine(dontLine)),
)
return &ContradictionReport{
RuleA: a.Name + ".md",
RuleB: b.Name + ".md",
Tension: tension,
DoLineA: doLine,
DontLineB: dontLine,
ScopeScore: scopeScore,
}
}
}
return nil
}
// findAntonymContradiction checks if A's Do words have antonyms in B's Do words.
func findAntonymContradiction(a, b RuleFile, scopeScore float64) *ContradictionReport {
aDoWords := extractActionWords(a.DoLines)
bDoWords := extractActionWords(b.DoLines)
for wordA, lineA := range aDoWords {
antonyms, ok := antonymPairs[wordA]
if !ok {
continue
}
for _, ant := range antonyms {
if lineB, ok := bDoWords[ant]; ok {
tension := truncateTension(
fmt.Sprintf("%q vs %q", summarizeLine(lineA), summarizeLine(lineB)),
)
return &ContradictionReport{
RuleA: a.Name + ".md",
RuleB: b.Name + ".md",
Tension: tension,
DoLineA: lineA,
DontLineB: lineB,
ScopeScore: scopeScore,
}
}
}
}
return nil
}
// extractActionWords returns a map of lowercase action words to their source line.
func extractActionWords(lines []string) map[string]string {
result := make(map[string]string)
for _, line := range lines {
words := tokenizeWords(line)
for _, w := range words {
w = strings.ToLower(w)
if len(w) >= 2 && !stopWords[w] {
if _, exists := result[w]; !exists {
result[w] = line
}
}
}
}
return result
}
// summarizeLine truncates a line for display in tension descriptions.
func summarizeLine(line string) string {
if len(line) > 40 {
return line[:37] + "..."
}
return line
}
// truncateTension ensures tension string fits in a table cell.
func truncateTension(s string) string {
if len(s) > 60 {
return s[:57] + "..."
}
return s
}
// FindMergeCandidates groups rules by keyword overlap using single-linkage clustering.
func FindMergeCandidates(rules []RuleFile, threshold float64) []MergeCandidate {
n := len(rules)
if n < 2 {
return nil
}
// Build adjacency: which pairs exceed the threshold
type pair struct {
i, j int
score float64
}
var pairs []pair
for i := 0; i < n; i++ {
for j := i + 1; j < n; j++ {
score := JaccardSimilarity(rules[i].Keywords, rules[j].Keywords)
if score >= threshold {
pairs = append(pairs, pair{i, j, score})
}
}
}
if len(pairs) == 0 {
return nil
}
// Union-Find for single-linkage clustering
parent := make([]int, n)
for i := range parent {
parent[i] = i
}
var find func(int) int
find = func(x int) int {
if parent[x] != x {
parent[x] = find(parent[x])
}
return parent[x]
}
union := func(x, y int) {
px, py := find(x), find(y)
if px != py {
parent[px] = py
}
}
for _, p := range pairs {
union(p.i, p.j)
}
// Collect groups
groups := make(map[int][]int)
for i := 0; i < n; i++ {
root := find(i)
groups[root] = append(groups[root], i)
}
// Build merge candidates (only groups with 2+ members)
var candidates []MergeCandidate
for _, members := range groups {
if len(members) < 2 {
continue
}
// Compute average pairwise score
var totalScore float64
var pairCount int
for mi := 0; mi < len(members); mi++ {
for mj := mi + 1; mj < len(members); mj++ {
totalScore += JaccardSimilarity(rules[members[mi]].Keywords, rules[members[mj]].Keywords)
pairCount++
}
}
avgScore := 0.0
if pairCount > 0 {
avgScore = totalScore / float64(pairCount)
}
// Collect rule names
var ruleNames []string
for _, idx := range members {
ruleNames = append(ruleNames, rules[idx].Name+".md")
}
sort.Strings(ruleNames)
// Find most frequent keyword for group label
label := findGroupLabel(rules, members)
candidates = append(candidates, MergeCandidate{
GroupLabel: label,
Rules: ruleNames,
Score: roundTo2(avgScore),
})
}
// Sort by score descending
sort.Slice(candidates, func(i, j int) bool {
return candidates[i].Score > candidates[j].Score
})
return candidates
}
// findGroupLabel finds the most common keyword across a group of rules.
func findGroupLabel(rules []RuleFile, indices []int) string {
freq := make(map[string]int)
for _, idx := range indices {
for _, kw := range rules[idx].Keywords {
freq[kw]++
}
}
bestWord := "rules"
bestCount := 0
for w, c := range freq {
if c > bestCount || (c == bestCount && w < bestWord) {
bestWord = w
bestCount = c
}
}
return bestWord
}
// roundTo2 rounds a float to 2 decimal places.
func roundTo2(f float64) float64 {
return float64(int(f*100+0.5)) / 100
}
// CompactRules merges a group of rules into a single composite markdown file.
func CompactRules(rules []RuleFile, groupLabel string) (string, error) {
if len(rules) == 0 {
return "", fmt.Errorf("no rules to compact")
}
// Collect and deduplicate Do/Don't lines
seenDo := make(map[string]bool)
seenDont := make(map[string]bool)
var doLines, dontLines []string
for _, r := range rules {
for _, line := range r.DoLines {
trimmed := strings.TrimSpace(line)
if trimmed != "" && !seenDo[trimmed] {
seenDo[trimmed] = true
doLines = append(doLines, trimmed)
}
}
for _, line := range r.DontLines {
trimmed := strings.TrimSpace(line)
if trimmed != "" && !seenDont[trimmed] {
seenDont[trimmed] = true
dontLines = append(dontLines, trimmed)
}
}
}
// Build composite
var sb strings.Builder
sb.WriteString("# ")
sb.WriteString(titleCase(groupLabel))
sb.WriteString("\n")
if len(doLines) > 0 {
sb.WriteString("**Do:** ")
sb.WriteString(strings.Join(doLines, ". "))
sb.WriteString("\n")
}
if len(dontLines) > 0 {
sb.WriteString("**Don't:** ")
sb.WriteString(strings.Join(dontLines, ". "))
sb.WriteString("\n")
}
// Source attribution
var sourceNames []string
for _, r := range rules {
sourceNames = append(sourceNames, r.Name+".md")
}
sb.WriteString("\nSource rules: ")
sb.WriteString(strings.Join(sourceNames, ", "))
sb.WriteString("\n")
return sb.String(), nil
}
// RunAudit is the top-level orchestrator for `bd rules audit`.
func RunAudit(rulesDir string, threshold float64) (*AuditResult, error) {
entries, err := os.ReadDir(rulesDir)
if err != nil {
if os.IsNotExist(err) {
return &AuditResult{}, nil
}
return nil, fmt.Errorf("read rules directory: %w", err)
}
var rules []RuleFile
totalTokens := 0
for _, entry := range entries {
if entry.IsDir() {
continue
}
if !strings.HasSuffix(entry.Name(), ".md") {
continue
}
path := filepath.Join(rulesDir, entry.Name())
rf, err := ParseRuleFile(path)
if err != nil {
// Skip files that can't be parsed
fmt.Fprintf(os.Stderr, "Warning: skipping %s: %v\n", entry.Name(), err)
continue
}
rules = append(rules, rf)
totalTokens += rf.Tokens
}
result := &AuditResult{
TotalRules: len(rules),
TokenEstimate: totalTokens,
}
if len(rules) < 2 {
result.Contradictions = []ContradictionReport{}
result.MergeCandidates = []MergeCandidate{}
result.Rules = rules
return result, nil
}
result.Contradictions = DetectContradictions(rules, 0.3)
result.MergeCandidates = FindMergeCandidates(rules, threshold)
result.Rules = rules
if result.Contradictions == nil {
result.Contradictions = []ContradictionReport{}
}
if result.MergeCandidates == nil {
result.MergeCandidates = []MergeCandidate{}
}
return result, nil
}
// --- Cobra Commands ---
var rulesCmd = &cobra.Command{
Use: "rules",
Short: "Audit and compact Claude rules",
GroupID: "maint",
}
var rulesAuditCmd = &cobra.Command{
Use: "audit",
Short: "Scan rules for contradictions and merge opportunities",
Run: runRulesAudit,
}
var rulesCompactCmd = &cobra.Command{
Use: "compact",
Short: "Merge related rules into composites",
Run: runRulesCompact,
}
func init() {
// Audit command flags
rulesAuditCmd.Flags().String("path", ".claude/rules/", "Path to rules directory")
rulesAuditCmd.Flags().Float64("threshold", 0.6, "Jaccard similarity threshold")
// Compact command flags
rulesCompactCmd.Flags().String("path", ".claude/rules/", "Path to rules directory")
rulesCompactCmd.Flags().StringSlice("group", nil, "Rule names to merge")
rulesCompactCmd.Flags().Bool("auto", false, "Apply audit suggestions")
rulesCompactCmd.Flags().Bool("dry-run", false, "Preview without applying")
// Register subcommands
rulesCmd.AddCommand(rulesAuditCmd)
rulesCmd.AddCommand(rulesCompactCmd)
rootCmd.AddCommand(rulesCmd)
}
func runRulesAudit(cmd *cobra.Command, args []string) {
rulesPath, _ := cmd.Flags().GetString("path")
threshold, _ := cmd.Flags().GetFloat64("threshold")
result, err := RunAudit(rulesPath, threshold)
if err != nil {
FatalErrorRespectJSON("rules audit failed: %v", err)
}
if jsonOutput {
outputJSON(result)
return
}
// Human-readable output
fmt.Printf("Rules Audit — %s\n", rulesPath)
fmt.Println(strings.Repeat("=", 60))
fmt.Println()
fmt.Println("Summary:")
fmt.Printf(" Total rules: %d\n", result.TotalRules)
fmt.Printf(" Token estimate: ~%d\n", result.TokenEstimate)
fmt.Printf(" Contradictions: %d\n", len(result.Contradictions))
mergeRuleCount := 0
for _, mc := range result.MergeCandidates {
mergeRuleCount += len(mc.Rules)
}
if len(result.MergeCandidates) > 0 {
fmt.Printf(" Merge candidates: %d groups (%d rules)\n",
len(result.MergeCandidates), mergeRuleCount)
} else {
fmt.Println(" Merge candidates: 0")
}
fmt.Println()
// Contradictions table
if len(result.Contradictions) > 0 {
fmt.Println("Contradictions:")
tw := tabwriter.NewWriter(os.Stdout, 2, 4, 2, ' ', 0)
fmt.Fprintf(tw, " Rule A\tRule B\tTension\n")
fmt.Fprintf(tw, " ------\t------\t-------\n")
for _, c := range result.Contradictions {
fmt.Fprintf(tw, " %s\t%s\t%s\n", c.RuleA, c.RuleB, c.Tension)
}
tw.Flush()
fmt.Println()
}
// Merge candidates
if len(result.MergeCandidates) > 0 {
fmt.Printf("Merge Candidates (similarity > %.2f):\n", threshold)
for i, mc := range result.MergeCandidates {
fmt.Printf(" Group %d — %q (score: %.2f)\n", i+1, mc.GroupLabel, mc.Score)
for _, r := range mc.Rules {
fmt.Printf(" → %s\n", r)
}
suggested := strings.ReplaceAll(mc.GroupLabel, " ", "-") + ".md"
fmt.Printf(" Suggested: merge into %s\n\n", suggested)
}
fmt.Printf("Run `bd rules compact --auto` to apply suggested merges.\n")
}
}
func runRulesCompact(cmd *cobra.Command, args []string) {
CheckReadonly("rules compact")
rulesPath, _ := cmd.Flags().GetString("path")
groupNames, _ := cmd.Flags().GetStringSlice("group")
autoMode, _ := cmd.Flags().GetBool("auto")
dryRun, _ := cmd.Flags().GetBool("dry-run")
if !autoMode && len(groupNames) == 0 {
FatalErrorRespectJSON("specify --group <rule1,rule2,...> or --auto")
}
if autoMode {
// Run audit to get merge candidates
result, err := RunAudit(rulesPath, 0.6)
if err != nil {
FatalErrorRespectJSON("audit for auto-compact failed: %v", err)
}
if len(result.MergeCandidates) == 0 {
if jsonOutput {
outputJSON(map[string]string{"status": "no merge candidates found"})
} else {
fmt.Println("No merge candidates found.")
}
return
}
type compactResult struct {
Group string `json:"group"`
Output string `json:"output"`
Rules int `json:"rules_merged"`
Applied bool `json:"applied"`
}
var results []compactResult
for _, mc := range result.MergeCandidates {
// Parse the actual rule files for this group
var groupRules []RuleFile
for _, ruleName := range mc.Rules {
path := filepath.Join(rulesPath, ruleName)
rf, err := ParseRuleFile(path)
if err != nil {
fmt.Fprintf(os.Stderr, "Warning: skipping %s: %v\n", ruleName, err)
continue
}
groupRules = append(groupRules, rf)
}
merged, err := CompactRules(groupRules, mc.GroupLabel)
if err != nil {
fmt.Fprintf(os.Stderr, "Warning: compact group %q failed: %v\n", mc.GroupLabel, err)
continue
}
applied := false
if !dryRun {
outName := strings.ReplaceAll(mc.GroupLabel, " ", "-") + ".md"
outPath := filepath.Join(rulesPath, outName)
if err := os.WriteFile(outPath, []byte(merged), 0644); err != nil {
fmt.Fprintf(os.Stderr, "Error writing %s: %v\n", outPath, err)
continue
}
// Delete source files
for _, ruleName := range mc.Rules {
srcPath := filepath.Join(rulesPath, ruleName)
_ = os.Remove(srcPath)
}
applied = true
}
results = append(results, compactResult{
Group: mc.GroupLabel,
Output: merged,
Rules: len(groupRules),
Applied: applied,
})
if !jsonOutput {
if dryRun {
fmt.Printf("Preview merge → %s.md:\n", mc.GroupLabel)
} else {
fmt.Printf("Merged → %s.md:\n", mc.GroupLabel)
}
fmt.Println(strings.Repeat("─", 40))
fmt.Print(merged)
fmt.Println(strings.Repeat("─", 40))
fmt.Println()
}
}
if jsonOutput {
outputJSON(results)
}
return
}
// Manual --group mode
var groupRules []RuleFile
for _, name := range groupNames {
if !strings.HasSuffix(name, ".md") {
name = name + ".md"
}
path := filepath.Join(rulesPath, name)
rf, err := ParseRuleFile(path)
if err != nil {
FatalErrorRespectJSON("cannot read rule %s: %v", name, err)
}
groupRules = append(groupRules, rf)
}
if len(groupRules) < 2 {
FatalErrorRespectJSON("need at least 2 rules to merge")
}
label := findGroupLabel(groupRules, makeRange(len(groupRules)))
merged, err := CompactRules(groupRules, label)
if err != nil {
FatalErrorRespectJSON("compact failed: %v", err)
}
if jsonOutput {
outputJSON(map[string]interface{}{
"group": label,
"output": merged,
"rules": len(groupRules),
"dry_run": dryRun,
})
return
}
outName := strings.ReplaceAll(label, " ", "-") + ".md"
if dryRun {
fmt.Printf("Preview merge → %s:\n", outName)
} else {
fmt.Printf("Merged → %s:\n", outName)
}
fmt.Println(strings.Repeat("─", 40))
fmt.Print(merged)
fmt.Println(strings.Repeat("─", 40))
if !dryRun {
outPath := filepath.Join(rulesPath, outName)
if err := os.WriteFile(outPath, []byte(merged), 0644); err != nil {
FatalErrorRespectJSON("write merged file: %v", err)
}
for _, rf := range groupRules {
_ = os.Remove(rf.Path)
}
fmt.Printf("\nCreated %s, deleted %d source files.\n", outName, len(groupRules))
}
}
// titleCase capitalizes the first letter of each word.
func titleCase(s string) string {
words := strings.Fields(s)
for i, w := range words {
if len(w) > 0 {
words[i] = strings.ToUpper(w[:1]) + w[1:]
}
}
return strings.Join(words, " ")
}
// makeRange returns a slice [0, 1, ..., n-1].
func makeRange(n int) []int {
r := make([]int, n)
for i := range r {
r[i] = i
}
return r
}

590
cmd/bd/rules_test.go Normal file
View file

@ -0,0 +1,590 @@
package main
import (
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
)
// --- Helpers ---
// writeRule creates a synthetic rule file in the given directory.
func writeRule(t *testing.T, dir, name, content string) string {
t.Helper()
path := filepath.Join(dir, name+".md")
if err := os.WriteFile(path, []byte(content), 0644); err != nil {
t.Fatalf("write rule %s: %v", name, err)
}
return path
}
// tempRulesDir creates a temporary directory for test rule files.
func tempRulesDir(t *testing.T) string {
t.Helper()
dir, err := os.MkdirTemp("", "rules-test-*")
if err != nil {
t.Fatalf("create temp dir: %v", err)
}
t.Cleanup(func() { os.RemoveAll(dir) })
return dir
}
// --- ParseRuleFile Tests ---
func TestRulesParseRuleFile_Basic(t *testing.T) {
dir := tempRulesDir(t)
content := `# Context-First Rule
**Do:** Check breadcrumb/aliases/recent git BEFORE Grep/Glob when user references past work.
**Don't:** Search immediately without checking context files first.
`
path := writeRule(t, dir, "context-first", content)
rf, err := ParseRuleFile(path)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if rf.Name != "context-first" {
t.Errorf("name = %q, want %q", rf.Name, "context-first")
}
if rf.Title != "Context-First Rule" {
t.Errorf("title = %q, want %q", rf.Title, "Context-First Rule")
}
if len(rf.DoLines) != 1 {
t.Errorf("do lines = %d, want 1", len(rf.DoLines))
}
if len(rf.DontLines) != 1 {
t.Errorf("dont lines = %d, want 1", len(rf.DontLines))
}
if rf.Tokens <= 0 {
t.Error("tokens should be > 0")
}
if len(rf.Keywords) == 0 {
t.Error("keywords should not be empty")
}
}
func TestRulesParseRuleFile_NoDoBlocks(t *testing.T) {
dir := tempRulesDir(t)
content := `# General Guidelines
Keep code clean and well-documented.
Follow the project conventions for naming and structure.
`
path := writeRule(t, dir, "general", content)
rf, err := ParseRuleFile(path)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if len(rf.DoLines) != 0 {
t.Errorf("do lines = %d, want 0", len(rf.DoLines))
}
if len(rf.DontLines) != 0 {
t.Errorf("dont lines = %d, want 0", len(rf.DontLines))
}
// Should still have keywords from body
if len(rf.Keywords) == 0 {
t.Error("keywords should be extracted from body when no Do/Don't blocks")
}
}
func TestRulesParseRuleFile_MultilineDo(t *testing.T) {
dir := tempRulesDir(t)
content := `# Multi Rule
**Do:**
- Check context files first
- Use existing tools before manual work
- Verify output matches expected format
**Don't:**
- Skip verification steps
- Use raw bash when tools exist
`
path := writeRule(t, dir, "multi-rule", content)
rf, err := ParseRuleFile(path)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if len(rf.DoLines) != 3 {
t.Errorf("do lines = %d, want 3; got: %v", len(rf.DoLines), rf.DoLines)
}
if len(rf.DontLines) != 2 {
t.Errorf("dont lines = %d, want 2; got: %v", len(rf.DontLines), rf.DontLines)
}
}
// --- ExtractKeywords Tests ---
func TestRulesExtractKeywords(t *testing.T) {
lines := []string{
"Check the context files before searching",
"Use existing tools and verify the output",
}
keywords := ExtractKeywords(lines)
if len(keywords) == 0 {
t.Fatal("keywords should not be empty")
}
// Should not contain stop words
for _, kw := range keywords {
if stopWords[kw] {
t.Errorf("keyword %q is a stop word", kw)
}
}
// Should be lowercase
for _, kw := range keywords {
if kw != kw {
t.Errorf("keyword %q is not lowercase", kw)
}
}
// Should contain expected words
kwSet := make(map[string]bool)
for _, kw := range keywords {
kwSet[kw] = true
}
expected := []string{"check", "context", "files", "searching", "existing", "tools", "verify", "output"}
for _, e := range expected {
if !kwSet[e] {
t.Errorf("missing expected keyword %q in %v", e, keywords)
}
}
}
// --- JaccardSimilarity Tests ---
func TestRulesJaccardSimilarity_Identical(t *testing.T) {
a := []string{"context", "files", "check", "search"}
b := []string{"context", "files", "check", "search"}
score := JaccardSimilarity(a, b)
if score != 1.0 {
t.Errorf("identical sets: score = %f, want 1.0", score)
}
}
func TestRulesJaccardSimilarity_Disjoint(t *testing.T) {
a := []string{"context", "files", "check"}
b := []string{"deploy", "server", "build"}
score := JaccardSimilarity(a, b)
if score != 0.0 {
t.Errorf("disjoint sets: score = %f, want 0.0", score)
}
}
func TestRulesJaccardSimilarity_Partial(t *testing.T) {
a := []string{"context", "files", "check", "search"}
b := []string{"context", "files", "load", "import"}
// intersection = {context, files} = 2
// union = {context, files, check, search, load, import} = 6
// jaccard = 2/6 = 0.333...
score := JaccardSimilarity(a, b)
expected := 2.0 / 6.0
if diff := score - expected; diff > 0.01 || diff < -0.01 {
t.Errorf("partial overlap: score = %f, want ~%f", score, expected)
}
}
// --- DetectContradictions Tests ---
func TestRulesDetectContradictions_Direct(t *testing.T) {
rules := []RuleFile{
{
Name: "rule-a",
DoLines: []string{"Block PR merges until all issues resolved"},
Keywords: []string{"block", "issues", "merges", "pr", "resolved"},
},
{
Name: "rule-b",
DontLines: []string{"Don't block PR merges for minor issues"},
Keywords: []string{"block", "issues", "merges", "minor", "pr"},
},
}
contradictions := DetectContradictions(rules, 0.3)
if len(contradictions) == 0 {
t.Fatal("expected at least 1 contradiction, got 0")
}
c := contradictions[0]
if c.RuleA != "rule-a.md" || c.RuleB != "rule-b.md" {
t.Errorf("contradiction rules = (%q, %q), want (rule-a.md, rule-b.md)", c.RuleA, c.RuleB)
}
if c.ScopeScore < 0.3 {
t.Errorf("scope score = %f, should be >= 0.3", c.ScopeScore)
}
}
func TestRulesDetectContradictions_Antonym(t *testing.T) {
rules := []RuleFile{
{
Name: "blocker-first",
DoLines: []string{"Block deployment pipeline until tests pass"},
Keywords: []string{"block", "deployment", "pipeline", "tests", "pass"},
},
{
Name: "fast-deploy",
DoLines: []string{"Proceed with deployment pipeline even if tests fail"},
Keywords: []string{"proceed", "deployment", "pipeline", "tests", "fail"},
},
}
// Jaccard: intersection={deployment,pipeline,tests}=3, union={block,deployment,pipeline,tests,pass,proceed,fail}=7
// Score = 3/7 = 0.43 > 0.3 threshold
contradictions := DetectContradictions(rules, 0.3)
if len(contradictions) == 0 {
t.Fatal("expected antonym contradiction (block vs proceed), got 0")
}
}
func TestRulesDetectContradictions_NoFalsePositive(t *testing.T) {
rules := []RuleFile{
{
Name: "context-first",
DoLines: []string{"Check breadcrumbs before searching"},
Keywords: []string{"breadcrumbs", "check", "context", "searching"},
},
{
Name: "tool-first",
DoLines: []string{"Use existing MCP tools before manual work"},
Keywords: []string{"existing", "manual", "mcp", "tools", "work"},
},
}
contradictions := DetectContradictions(rules, 0.3)
if len(contradictions) != 0 {
t.Errorf("expected 0 contradictions for unrelated rules, got %d: %+v",
len(contradictions), contradictions)
}
}
// --- FindMergeCandidates Tests ---
func TestRulesFindMergeCandidates_Grouping(t *testing.T) {
rules := []RuleFile{
{
Name: "agent-spawn",
Keywords: []string{"agent", "check", "existing", "spawn", "tool"},
},
{
Name: "agent-efficiency",
Keywords: []string{"agent", "efficiency", "existing", "reuse", "tool"},
},
{
Name: "agent-tokens",
Keywords: []string{"agent", "minimize", "output", "token", "tool"},
},
{
Name: "deploy-guide",
Keywords: []string{"build", "deploy", "production", "server", "staging"},
},
}
candidates := FindMergeCandidates(rules, 0.4)
// The three agent rules should cluster together
found := false
for _, mc := range candidates {
if len(mc.Rules) >= 2 {
// Check that deploy-guide is not in any agent group
for _, r := range mc.Rules {
if r == "deploy-guide.md" {
t.Error("deploy-guide should not be grouped with agent rules")
}
}
found = true
}
}
if !found {
t.Error("expected at least one merge group with 2+ agent rules")
}
}
func TestRulesFindMergeCandidates_Threshold(t *testing.T) {
rules := []RuleFile{
{
Name: "rule-a",
Keywords: []string{"alpha", "beta", "gamma", "delta"},
},
{
Name: "rule-b",
Keywords: []string{"alpha", "beta", "epsilon", "zeta"},
},
}
// jaccard = 2/6 = 0.333
// With threshold 0.3, should find a candidate
candidates := FindMergeCandidates(rules, 0.3)
if len(candidates) == 0 {
t.Error("expected merge candidate at threshold 0.3")
}
// With threshold 0.5, should not find a candidate
candidates = FindMergeCandidates(rules, 0.5)
if len(candidates) != 0 {
t.Errorf("expected no merge candidate at threshold 0.5, got %d", len(candidates))
}
}
// --- CompactRules Tests ---
func TestRulesCompactRules_Dedup(t *testing.T) {
rules := []RuleFile{
{
Name: "rule-a",
DoLines: []string{"Check context first", "Use existing tools"},
DontLines: []string{"Skip verification"},
},
{
Name: "rule-b",
DoLines: []string{"Check context first", "Verify output format"},
DontLines: []string{"Skip verification", "Use raw bash"},
},
}
merged, err := CompactRules(rules, "combined")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
// "Check context first" should appear only once
count := 0
for _, line := range strings.Split(merged, "\n") {
if rulesContains(line, "Check context first") {
count++
}
}
if count != 1 {
t.Errorf("'Check context first' appears %d times, want 1", count)
}
// "Skip verification" should appear only once
count = 0
for _, line := range strings.Split(merged, "\n") {
if rulesContains(line, "Skip verification") {
count++
}
}
if count != 1 {
t.Errorf("'Skip verification' appears %d times, want 1", count)
}
}
func TestRulesCompactRules_PreservesOrder(t *testing.T) {
rules := []RuleFile{
{
Name: "rule-a",
DoLines: []string{"First directive", "Second directive"},
},
{
Name: "rule-b",
DoLines: []string{"Third directive"},
},
}
merged, err := CompactRules(rules, "ordered")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
// All three should appear in order
if !rulesContains(merged, "First directive") {
t.Error("missing 'First directive'")
}
if !rulesContains(merged, "Second directive") {
t.Error("missing 'Second directive'")
}
if !rulesContains(merged, "Third directive") {
t.Error("missing 'Third directive'")
}
// Check order: First before Second before Third
idx1 := rulesIndexOf(merged, "First directive")
idx2 := rulesIndexOf(merged, "Second directive")
idx3 := rulesIndexOf(merged, "Third directive")
if idx1 >= idx2 || idx2 >= idx3 {
t.Errorf("directives not in order: First@%d, Second@%d, Third@%d", idx1, idx2, idx3)
}
}
// --- RunAudit Integration Tests ---
func TestRulesRunAudit_EmptyDir(t *testing.T) {
dir := tempRulesDir(t)
result, err := RunAudit(dir, 0.6)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result.TotalRules != 0 {
t.Errorf("total rules = %d, want 0", result.TotalRules)
}
if result.TokenEstimate != 0 {
t.Errorf("token estimate = %d, want 0", result.TokenEstimate)
}
}
func TestRulesRunAudit_SingleRule(t *testing.T) {
dir := tempRulesDir(t)
writeRule(t, dir, "only-rule", `# Only Rule
**Do:** Check context first.
**Don't:** Skip verification.
`)
result, err := RunAudit(dir, 0.6)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result.TotalRules != 1 {
t.Errorf("total rules = %d, want 1", result.TotalRules)
}
if len(result.Contradictions) != 0 {
t.Errorf("contradictions = %d, want 0 (single rule)", len(result.Contradictions))
}
if len(result.MergeCandidates) != 0 {
t.Errorf("merge candidates = %d, want 0 (single rule)", len(result.MergeCandidates))
}
}
func TestRulesRunAudit_JSON(t *testing.T) {
dir := tempRulesDir(t)
writeRule(t, dir, "rule-a", `# Rule Alpha
**Do:** Check breadcrumbs before searching.
**Don't:** Search immediately without context.
`)
writeRule(t, dir, "rule-b", `# Rule Beta
**Do:** Use existing tools before manual work.
**Don't:** Manually run commands when tools exist.
`)
result, err := RunAudit(dir, 0.6)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
// Verify JSON marshaling works
data, err := json.Marshal(result)
if err != nil {
t.Fatalf("JSON marshal failed: %v", err)
}
// Verify it can be unmarshaled back
var decoded AuditResult
if err := json.Unmarshal(data, &decoded); err != nil {
t.Fatalf("JSON unmarshal failed: %v", err)
}
if decoded.TotalRules != result.TotalRules {
t.Errorf("decoded total_rules = %d, want %d", decoded.TotalRules, result.TotalRules)
}
// Verify expected JSON fields exist
var raw map[string]interface{}
if err := json.Unmarshal(data, &raw); err != nil {
t.Fatalf("JSON unmarshal to map failed: %v", err)
}
for _, field := range []string{"total_rules", "token_estimate", "contradictions", "merge_candidates"} {
if _, ok := raw[field]; !ok {
t.Errorf("missing JSON field %q", field)
}
}
}
// --- Integration: Full audit with contradictions and merges ---
func TestRulesRunAudit_Integration(t *testing.T) {
dir := tempRulesDir(t)
// Create rules that should contradict
writeRule(t, dir, "blocker-first", `# Blocker First
**Do:** Block PR merges until all issues are resolved.
**Don't:** Allow merges with open blockers.
`)
writeRule(t, dir, "parallel-workflow", `# Parallel Workflow
**Do:** Proceed with merges in parallel even if minor issues exist.
**Don't:** Block the pipeline for non-critical issues.
`)
// Create rules that should be merge candidates
writeRule(t, dir, "agent-spawn", `# Agent Spawn Discipline
**Do:** Check for existing agent before spawning new ones.
**Don't:** Spawn redundant agents for the same task.
`)
writeRule(t, dir, "agent-efficiency", `# Agent Efficiency
**Do:** Reuse existing agent context and tools.
**Don't:** Spawn new agents when existing ones can handle the task.
`)
// Create an unrelated rule
writeRule(t, dir, "deploy-guide", `# Deploy Guide
**Do:** Run integration tests before deploying to production.
**Don't:** Deploy without passing CI checks.
`)
result, err := RunAudit(dir, 0.4)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result.TotalRules != 5 {
t.Errorf("total rules = %d, want 5", result.TotalRules)
}
// Should find contradiction between blocker-first and parallel-workflow
if len(result.Contradictions) == 0 {
t.Error("expected at least 1 contradiction between blocker-first and parallel-workflow")
}
// Should find merge candidates for agent rules
if len(result.MergeCandidates) == 0 {
t.Error("expected at least 1 merge group for agent rules")
}
}
func TestRulesRunAudit_NonexistentDir(t *testing.T) {
result, err := RunAudit("/tmp/nonexistent-rules-dir-xyz", 0.6)
if err != nil {
t.Fatalf("should not error on nonexistent dir, got: %v", err)
}
if result.TotalRules != 0 {
t.Errorf("total rules = %d, want 0", result.TotalRules)
}
}
func TestRulesRunAudit_SkipsNonMarkdown(t *testing.T) {
dir := tempRulesDir(t)
writeRule(t, dir, "valid-rule", `# Valid
**Do:** Something useful.
`)
// Write a non-markdown file
os.WriteFile(filepath.Join(dir, "notes.txt"), []byte("not a rule"), 0644)
os.WriteFile(filepath.Join(dir, ".hidden"), []byte("hidden file"), 0644)
result, err := RunAudit(dir, 0.6)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result.TotalRules != 1 {
t.Errorf("total rules = %d, want 1 (should skip non-.md files)", result.TotalRules)
}
}
// --- Helpers ---
func rulesContains(s, substr string) bool {
return strings.Contains(s, substr)
}
func rulesIndexOf(s, substr string) int {
return strings.Index(s, substr)
}

435
docs/RULES_AUDIT_DESIGN.md Normal file
View file

@ -0,0 +1,435 @@
# `bd rules audit` / `bd rules compact` Design Doc
> **Status:** Ready | **Target:** Upstream PR to `steveyegge/beads`
> **Companion spec:** SESSION-OUTPUT-SPEC Items 2 & 6
---
## Problem Statement
Claude Code projects accumulate rules in `.claude/rules/*.md` over time. Each rule starts small and focused, but after a few months of active development, a real project can hit 40+ rule files with:
- **Contradictions** — Rule A says "always do X", Rule B says "never do X" (same scope, opposing directives)
- **Near-duplicates** — Three rules about agent efficiency that could be one file
- **Bloat** — 40 files, ~12K tokens of system prompt. Every Claude session loads all of them. Token cost scales linearly.
- **No auditing** — No tooling exists to detect any of the above. Discovery is manual.
Beads already tracks issues, specs, skills, and comments. Rules are the missing entity. `bd rules audit` fills this gap.
### Motivating Example
A real production project with 40+ rules had:
- 4 rules touching "agent discipline" (spawn, efficiency, token usage, verification) — all overlapping
- 2 rules with direct contradictions: one enforcing a strict blocking workflow, another allowing flexible parallel execution
- 8 rules that could merge into 3 composites, saving ~3K tokens per session
- Total rule token cost: ~12K tokens — reducible to ~7K with compaction
Nobody noticed until manual review. This should be automated.
---
## CLI Interface
### `bd rules audit`
Scan rules and report problems.
```
bd rules audit [--path .claude/rules/] [--json] [--threshold 0.6]
Flags:
--path Path to rules directory (default: .claude/rules/)
--json Structured JSON output for agent consumption
--threshold Jaccard similarity threshold for merge candidates (default: 0.6)
```
**Output (human-readable):**
```
Rules Audit — .claude/rules/
============================================================
Summary:
Total rules: 42
Token estimate: ~11,800
Contradictions: 2
Merge candidates: 3 groups (12 rules → 4 files)
Contradictions:
┌─────────────────────────┬─────────────────────────┬───────────────────────────────┐
│ Rule A │ Rule B │ Tension │
├─────────────────────────┼─────────────────────────┼───────────────────────────────┤
│ blocker-first.md │ parallel-workflow.md │ "block until resolved" vs │
│ │ │ "proceed in parallel" │
├─────────────────────────┼─────────────────────────┼───────────────────────────────┤
│ verbose-logging.md │ token-efficiency.md │ "log all decisions" vs │
│ │ │ "minimize output tokens" │
└─────────────────────────┴─────────────────────────┴───────────────────────────────┘
Merge Candidates (similarity > 0.60):
Group 1 — "agent discipline" (score: 0.78)
→ agent-spawn-discipline.md
→ agent-efficiency.md
→ agent-token-efficiency.md
→ agent-verification.md
Suggested: merge into agent-discipline.md
Group 2 — "context management" (score: 0.65)
→ context-first.md
→ context-loading.md
Suggested: merge into context-management.md
Run `bd rules compact --auto` to apply suggested merges.
```
### `bd rules compact`
Merge related rules into composites.
```
bd rules compact --group <rule1> <rule2> ... # Merge specific rules
bd rules compact --auto # Apply audit suggestions
bd rules compact --dry-run # Show diff without applying
Flags:
--path Path to rules directory (default: .claude/rules/)
--group List of rule filenames (without .md) to merge
--auto Use merge candidates from last audit
--dry-run Preview merged output without writing files
--json Structured JSON output
```
**Compact workflow:**
```
$ bd rules compact --group agent-spawn-discipline agent-efficiency agent-token-efficiency
Preview merge → agent-discipline.md:
────────────────────────────────────
# Agent Discipline
**Do:** Check for existing skill/tool before spawning. Reuse context. Minimize token output.
**Don't:** Spawn redundant agents. Repeat work across sessions. Log verbose reasoning.
Source rules: agent-spawn-discipline.md, agent-efficiency.md, agent-token-efficiency.md
────────────────────────────────────
Apply? [y/N]: y
✓ Created .claude/rules/agent-discipline.md
✓ Deleted 3 source files
```
---
## Algorithm
### Step 1: Parse Rules
Each `.md` file in the rules directory is parsed into a `RuleFile`:
1. Read file content
2. Extract the first `#` heading as the rule name (fallback: filename)
3. Extract **Do blocks**: lines matching `**Do:**` (with continuation lines)
4. Extract **Don't blocks**: lines matching `**Don't:**` (with continuation lines)
5. Extract all other content as `body` (for keyword extraction fallback)
6. Estimate token count: `len(content) / 4` (rough approximation)
### Step 2: Keyword Extraction
For each rule, extract a keyword set:
1. Tokenize Do/Don't lines into words (lowercase, strip punctuation)
2. Remove stop words (`the`, `a`, `is`, `to`, `for`, `and`, `or`, `in`, `of`, `it`, `that`, `this`, `with`, `be`, `not`, `do`, `don't`, `use`, `when`, `before`, `after`, `should`, `must`, `always`, `never`)
3. Keep remaining words as the keyword set
4. If Do/Don't blocks are empty, fall back to body keywords (same process)
No NLP libraries needed — simple tokenization is sufficient for `.claude/rules/` files which are short, imperative, and use consistent vocabulary.
### Step 3: Overlap Scoring (Merge Candidates)
For every pair of rules `(A, B)`:
```
jaccard(A, B) = |keywords(A) ∩ keywords(B)| / |keywords(A) ∪ keywords(B)|
```
If `jaccard(A, B) >= threshold` (default 0.6), they're a merge candidate.
**Grouping:** Build merge groups using single-linkage clustering:
- Start with all pairs above threshold
- If A overlaps B and B overlaps C, group {A, B, C}
- Label each group by the most frequent keyword
### Step 4: Contradiction Detection
Two rules contradict when they share scope but give opposing directives.
**Scope overlap:** `jaccard(A, B) >= 0.3` (lower than merge threshold — contradictions can exist between loosely related rules)
**Opposing directives check:**
1. Extract action verbs from Do blocks of rule A
2. Extract action verbs from Don't blocks of rule B
3. If the same verb appears in A's Do and B's Don't (or vice versa) on overlapping keyword scope → contradiction
**Antonym pairs** (hardcoded for MVP):
- `block` / `proceed`, `parallel`
- `verbose` / `minimize`, `concise`
- `always` / `never`
- `spawn` / `reuse`
- `wait` / `skip`
- `log` / `suppress`
If a Do directive from rule A uses a word, and a Do directive from rule B uses its antonym, with shared scope keywords → contradiction.
**Tension description:** Generated from the conflicting Do/Don't lines, truncated to ~60 chars.
### Step 5: Compaction (for `bd rules compact`)
Given a group of rules to merge:
1. Collect all Do blocks across source rules
2. Collect all Don't blocks across source rules
3. Deduplicate identical entries (exact string match after trimming)
4. Generate a merged heading from the group label
5. Output the composite rule in standard format:
```markdown
# {Group Label}
**Do:** {deduplicated do entries, newline-separated}
**Don't:** {deduplicated don't entries, newline-separated}
```
6. Show diff before applying
7. On confirmation: write merged file, delete source files
---
## Go Implementation Sketch
### File: `cmd/bd/rules.go`
```go
package main
// --- Types ---
// RuleFile represents a parsed .claude/rules/*.md file.
type RuleFile struct {
Path string // absolute path
Name string // filename without .md
Title string // first # heading or filename
DoLines []string // extracted "Do:" directives
DontLines []string // extracted "Don't:" directives
Body string // full file content
Keywords []string // extracted keywords (deduped, lowered)
Tokens int // estimated token count
}
// ContradictionReport describes a tension between two rules.
type ContradictionReport struct {
RuleA string `json:"rule_a"`
RuleB string `json:"rule_b"`
Tension string `json:"tension"`
DoLineA string `json:"do_line_a"`
DontLineB string `json:"dont_line_b"`
ScopeScore float64 `json:"scope_score"`
}
// MergeCandidate represents a group of rules that could be combined.
type MergeCandidate struct {
GroupLabel string `json:"group_label"`
Rules []string `json:"rules"`
Score float64 `json:"score"` // average pairwise Jaccard
}
// AuditResult is the full output of `bd rules audit`.
type AuditResult struct {
TotalRules int `json:"total_rules"`
TokenEstimate int `json:"token_estimate"`
Contradictions []ContradictionReport `json:"contradictions"`
MergeCandidates []MergeCandidate `json:"merge_candidates"`
Rules []RuleFile `json:"rules,omitempty"` // only in --json
}
// --- Key Functions ---
// ParseRuleFile reads a .md file and extracts structured rule data.
func ParseRuleFile(path string) (RuleFile, error)
// ExtractKeywords tokenizes Do/Don't lines, removes stop words.
func ExtractKeywords(lines []string) []string
// JaccardSimilarity computes keyword overlap between two rules.
func JaccardSimilarity(a, b []string) float64
// DetectContradictions finds opposing directives across rule pairs.
func DetectContradictions(rules []RuleFile, scopeThreshold float64) []ContradictionReport
// FindMergeCandidates groups rules by keyword overlap.
func FindMergeCandidates(rules []RuleFile, threshold float64) []MergeCandidate
// CompactRules merges a group of rules into a single composite file.
func CompactRules(rules []RuleFile, groupLabel string) (string, error)
// RunAudit is the top-level orchestrator for `bd rules audit`.
func RunAudit(rulesDir string, threshold float64) (*AuditResult, error)
```
### Cobra Commands
```go
var rulesCmd = &cobra.Command{
Use: "rules",
Short: "Audit and compact Claude rules",
GroupID: GroupMaintenance,
}
var rulesAuditCmd = &cobra.Command{
Use: "audit",
Short: "Scan rules for contradictions and merge opportunities",
Run: runRulesAudit,
}
var rulesCompactCmd = &cobra.Command{
Use: "compact",
Short: "Merge related rules into composites",
Run: runRulesCompact,
}
func init() {
rulesAuditCmd.Flags().String("path", ".claude/rules/", "Path to rules directory")
rulesAuditCmd.Flags().Bool("json", false, "JSON output")
rulesAuditCmd.Flags().Float64("threshold", 0.6, "Jaccard similarity threshold")
rulesCompactCmd.Flags().String("path", ".claude/rules/", "Path to rules directory")
rulesCompactCmd.Flags().StringSlice("group", nil, "Rule names to merge")
rulesCompactCmd.Flags().Bool("auto", false, "Apply audit suggestions")
rulesCompactCmd.Flags().Bool("dry-run", false, "Preview without applying")
rulesCompactCmd.Flags().Bool("json", false, "JSON output")
rulesCmd.AddCommand(rulesAuditCmd)
rulesCmd.AddCommand(rulesCompactCmd)
rootCmd.AddCommand(rulesCmd)
}
```
### Patterns (matching existing codebase)
- **One file per command tree**: `rules.go` contains both `audit` and `compact` subcommands (like `spec.go` contains scan/cleanup/duplicates)
- **`--json` everywhere**: All output structs have JSON tags, `--json` flag switches rendering
- **GroupID**: Uses `GroupMaintenance` (same as `wobble`, `doctor`)
- **No daemon dependency**: Rules audit is purely local file analysis — no RPC, no SQLite
- **`tabwriter` for tables**: Human output uses `text/tabwriter` (same as `spec report`)
---
## Output Formats
### Human-Readable (default)
See the CLI Interface section above. Uses:
- `tabwriter` for the contradiction table
- Indented groups for merge candidates
- Color via `internal/ui` package (green for OK, yellow for warnings, red for contradictions)
### JSON (`--json`)
```json
{
"total_rules": 42,
"token_estimate": 11800,
"contradictions": [
{
"rule_a": "blocker-first.md",
"rule_b": "parallel-workflow.md",
"tension": "\"block until resolved\" vs \"proceed in parallel\"",
"do_line_a": "Block PR merges until all issues resolved",
"dont_line_b": "Don't wait for blocking issues, proceed in parallel",
"scope_score": 0.45
}
],
"merge_candidates": [
{
"group_label": "agent discipline",
"rules": [
"agent-spawn-discipline.md",
"agent-efficiency.md",
"agent-token-efficiency.md",
"agent-verification.md"
],
"score": 0.78
}
]
}
```
---
## Test Plan
### Unit Tests (`cmd/bd/rules_test.go`)
| Test | What it verifies |
|------|-----------------|
| `TestParseRuleFile_Basic` | Extracts title, Do/Don't lines from well-formed rule |
| `TestParseRuleFile_NoDoBlocks` | Falls back to body keywords when no Do/Don't |
| `TestParseRuleFile_MultilineDo` | Handles continuation lines after `**Do:**` |
| `TestExtractKeywords` | Stop word removal, lowercasing, dedup |
| `TestJaccardSimilarity_Identical` | Returns 1.0 for same keyword sets |
| `TestJaccardSimilarity_Disjoint` | Returns 0.0 for no overlap |
| `TestJaccardSimilarity_Partial` | Returns correct score for partial overlap |
| `TestDetectContradictions_Direct` | Finds "Do X" vs "Don't X" across rules |
| `TestDetectContradictions_Antonym` | Finds "block" vs "proceed" antonym pair |
| `TestDetectContradictions_NoFalsePositive` | Unrelated rules don't trigger contradiction |
| `TestFindMergeCandidates_Grouping` | Clusters overlapping rules into groups |
| `TestFindMergeCandidates_Threshold` | Respects --threshold flag |
| `TestCompactRules_Dedup` | Removes identical Do lines from merged output |
| `TestCompactRules_PreservesOrder` | Merged output keeps stable ordering |
| `TestRunAudit_EmptyDir` | Handles directory with no .md files |
| `TestRunAudit_SingleRule` | No contradictions or merge candidates with 1 rule |
| `TestRunAudit_JSON` | JSON output matches expected schema |
### Edge Cases
- **Empty rules directory** — report 0 rules, no errors
- **Rule with only a title, no Do/Don't** — still appears in count, keywords from body
- **Binary/non-markdown files in rules dir** — skip gracefully
- **Symlinked rules** — follow symlinks (match Claude Code behavior)
- **Very long rules (>10K chars)** — keyword extraction still works, flag as bloated
- **UTF-8 with emoji** — handle gracefully in keyword extraction
- **Single rule** — no pairs to compare, clean report
### Integration Tests
- Create a temp directory with 5-6 synthetic rules (known contradictions and overlaps)
- Run full `RunAudit()` and verify the expected contradictions and merge groups
- Run `CompactRules()` and verify the merged file content
- Verify `--json` output parses as valid JSON
---
## Files to Create/Modify
| File | Action | Lines (est.) |
|------|--------|-------------|
| `cmd/bd/rules.go` | Create | ~450 |
| `cmd/bd/rules_test.go` | Create | ~350 |
| `docs/RULES_AUDIT.md` | Create (user docs) | ~80 |
| `CHANGELOG.md` | Update | +5 |
No new packages needed. No database changes. No daemon integration. Pure file analysis.
---
## Non-Goals (v1)
- **NLP/embeddings**: No semantic similarity — Jaccard on extracted keywords is sufficient for rule files
- **Auto-fix contradictions**: Only `compact` merges related rules. Resolving contradictions requires human judgment.
- **Cross-project rules**: Only scans one rules directory per invocation
- **Rule dependency tracking**: No DAG of rule relationships (future work)
- **MCP mode**: Standalone MCP wrapper is a separate project (SESSION-OUTPUT-SPEC Item 4)
---
## Open Questions
1. **Should `--fix` be a flag on `audit` or a separate `compact` command?** Current design: separate command. Reasoning: audit is read-only and safe to run anytime; compact modifies files and needs explicit intent.
2. **Threshold tuning**: 0.6 default is a guess. Needs calibration against real rule sets. Should we ship with 0.5 and let users tune up?
3. **Antonym list**: Hardcoded for MVP. Should this be configurable via a YAML file?