feat(references): add verification override mechanism reference (#1747) (#1819)

Combines implementation by @Tibsfox (test suite, 80% fuzzy threshold)
and @davesienkowski (must_have schema, mandatory audit fields, full
lifecycle with re-verification carryforward and overrides_applied counter,
embedded verifier step 3b, When-NOT-to-use guardrails).

- New reference: get-shit-done/references/verification-overrides.md
  with must_have/accepted_by/accepted_at schema, 80% fuzzy match
  threshold, When to Use / When NOT to Use guardrails, full override
  lifecycle (re-verification carryforward, milestone audit surfacing)
- gsd-verifier.md updated with required_reading block, embedded Step 3b
  override check before FAIL marking, and overrides_applied frontmatter
- 27-assertion test suite covering reference structure, field names,
  threshold value, lifecycle fields, and agent cross-reference

Closes #1747

Co-authored-by: Tibsfox <tibsfox@users.noreply.github.com>
Co-authored-by: Rezolv <davesienkowski@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

agents/gsd-verifier.md

@@ -22,6 +22,10 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 **Critical mindset:** Do NOT trust SUMMARY.md claims. SUMMARYs document what Claude SAID it did. You verify what ACTUALLY exists in the code. These often differ.
 </role>
 
+<required_reading>
+@~/.claude/get-shit-done/references/verification-overrides.md
+</required_reading>
+
 <project_context>
 Before verifying, discover project context:
 
@@ -154,7 +158,42 @@ For each truth:
 1. Identify supporting artifacts
 2. Check artifact status (Step 4)
 3. Check wiring status (Step 5)
-4. Determine truth status
+4. **Before marking FAIL:** Check for override (Step 3b)
+5. Determine truth status
+
+## Step 3b: Check Verification Overrides
+
+Before marking any must-have as FAILED, check the VERIFICATION.md frontmatter for an `overrides:` entry that matches this must-have.
+
+**Override check procedure:**
+
+1. Parse `overrides:` array from VERIFICATION.md frontmatter (if present)
+2. For each override entry, normalize both the override `must_have` and the current truth to lowercase, strip punctuation, collapse whitespace
+3. Split into tokens and compute intersection — match if 80% token overlap in either direction
+4. Key technical terms (file paths, component names, API endpoints) have higher weight
+
+**If override found:**
+- Mark as `PASSED (override)` instead of FAIL
+- Evidence: `Override: {reason} — accepted by {accepted_by} on {accepted_at}`
+- Count toward passing score, not failing score
+
+**If no override found:**
+- Mark as FAILED as normal
+- Consider suggesting an override if the failure looks intentional (alternative implementation exists)
+
+**Suggesting overrides:** When a must-have FAILs but evidence shows an alternative implementation that achieves the same intent, include an override suggestion in the report:
+
+```markdown
+**This looks intentional.** To accept this deviation, add to VERIFICATION.md frontmatter:
+
+```yaml
+overrides:
+  - must_have: "{must-have text}"
+    reason: "{why this deviation is acceptable}"
+    accepted_by: "{name}"
+    accepted_at: "{ISO timestamp}"
+```
+```
 
 ## Step 4: Verify Artifacts (Three Levels)
 
@@ -541,6 +580,12 @@ phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+overrides_applied: 0 # Count of PASSED (override) items included in score
+overrides: # Only if overrides exist — carried forward or newly added
+  - must_have: "Must-have text that was overridden"
+    reason: "Why deviation is acceptable"
+    accepted_by: "username"
+    accepted_at: "ISO timestamp"
 re_verification: # Only if previous VERIFICATION.md existed
   previous_status: gaps_found
   previous_score: 2/5