diff --git a/cmd/bd/rules.go b/cmd/bd/rules.go new file mode 100644 index 000000000..e85fb5640 --- /dev/null +++ b/cmd/bd/rules.go @@ -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 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 +} diff --git a/cmd/bd/rules_test.go b/cmd/bd/rules_test.go new file mode 100644 index 000000000..5f2c39e75 --- /dev/null +++ b/cmd/bd/rules_test.go @@ -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) +} diff --git a/docs/RULES_AUDIT_DESIGN.md b/docs/RULES_AUDIT_DESIGN.md new file mode 100644 index 000000000..f32cc0f5e --- /dev/null +++ b/docs/RULES_AUDIT_DESIGN.md @@ -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 ... # 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?