fix: reduce false positives in validate REF-001 and SEC-001 rules (#38)

REF-001: Only validate related: references that look like DevTrail
document IDs (AILOG-*, AIDEC-*, ADR-*, etc.). Skip task IDs (T025),
requirement IDs (FR-019, US2), risk IDs (RISK-001), external paths,
and other non-document references that caused noisy false positives.

SEC-001: Move 'Bearer' and 'token:' from hard errors to soft warnings,
since these patterns are common in documentation describing auth flows.
Actual secret patterns (password:, api_key:, PRIVATE KEY, etc.) remain
as errors.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: montfort

cli/src/validation.rs

@@ -49,10 +49,18 @@ const VALID_RISK_LEVELS: &[&str] = &["low", "medium", "high", "critical"];
 /// Valid confidence levels
 const VALID_CONFIDENCES: &[&str] = &["low", "medium", "high"];
 
-/// Patterns that indicate sensitive information
+/// Patterns that indicate sensitive information.
+/// These are checked against the document body. Patterns should be specific enough
+/// to avoid false positives in documentation that describes auth flows.
 const SENSITIVE_PATTERNS: &[&str] = &[
-    "password:", "api_key:", "secret:", "token:", "private_key:",
-    "credentials:", "Bearer ", "AWS_SECRET", "PRIVATE KEY",
+    "password:", "api_key:", "secret:", "private_key:",
+    "credentials:", "AWS_SECRET", "PRIVATE KEY",
+];
+
+/// Patterns that are suspicious but common in documentation describing auth flows.
+/// These produce warnings instead of errors.
+const SOFT_SENSITIVE_PATTERNS: &[&str] = &[
+    "token:", "Bearer ",
 ];
 
 /// Validate all documents found under a .devtrail/ directory
@@ -489,12 +497,20 @@ fn check_type_specific(result: &mut ValidationResult, doc: &DevTrailDocument) {
 }
 
 /// REF-001: Check that documents listed in related: exist
+/// Only validates references that look like DevTrail document IDs (e.g., AILOG-2025-01-27-001).
+/// Skips task IDs (T025), requirement IDs (FR-019, US2), risk IDs (RISK-001),
+/// external paths, and other non-document references to avoid false positives.
 fn check_related_exist(result: &mut ValidationResult, doc: &DevTrailDocument, devtrail_dir: &Path) {
     if let Some(related) = &doc.frontmatter.related {
         for rel_id in related {
             if rel_id.is_empty() {
                 continue;
             }
+            // Only validate references that look like DevTrail document IDs
+            // (start with a known document type prefix followed by a dash)
+            if !looks_like_devtrail_id(rel_id) {
+                continue;
+            }
             // Search for a file matching this id
             if !find_document_by_id(devtrail_dir, rel_id) {
                 result.add(ValidationIssue {
@@ -509,6 +525,15 @@ fn check_related_exist(result: &mut ValidationResult, doc: &DevTrailDocument, de
     }
 }
 
+/// Check if a reference looks like a DevTrail document ID.
+/// Matches patterns like "AILOG-2025-01-27-001" or "ADR-2025-01-27-001-title".
+/// Returns false for task IDs (T025), requirement IDs (FR-019, US2), paths, etc.
+fn looks_like_devtrail_id(id: &str) -> bool {
+    DocType::ALL_PREFIXES.iter().any(|prefix| {
+        id.starts_with(prefix) && id.get(prefix.len()..prefix.len() + 1) == Some("-")
+    })
+}
+
 /// META-004: Check that filename date matches created field
 fn check_date_consistency(result: &mut ValidationResult, doc: &DevTrailDocument) {
     let Some(created) = &doc.frontmatter.created else {
@@ -570,6 +595,18 @@ fn check_sensitive_info(result: &mut ValidationResult, doc: &DevTrailDocument) {
             });
         }
     }
+    // Soft patterns: common in auth documentation, warn instead of error
+    for pattern in SOFT_SENSITIVE_PATTERNS {
+        if full_content.contains(pattern) {
+            result.add(ValidationIssue {
+                file: doc.path.clone(),
+                rule: "SEC-001".to_string(),
+                message: format!("Review for sensitive information: '{}' (may be documentation context)", pattern.trim()),
+                severity: Severity::Warning,
+                fix_hint: Some("Verify this is documentation context, not an actual secret".to_string()),
+            });
+        }
+    }
 }
 
 /// OBS-001: If document has tag 'observabilidad' or 'observability', check for relevant sections