feat: corrected text suggestions alongside flags

[Jamie-BitFlight]

Summary

When a hallucination pattern is flagged, generate a suggested rewrite that replaces the speculative/ungrounded language with evidence-based alternatives.

Current Behavior

The stop hook outputs a warning message with the flagged evidence but does not suggest what to say instead. The user/agent must figure out the rewrite themselves.

Proposed Behavior

Each trigger match includes a suggestedFix field with a rewritten version:

{
  kind: 'speculation_language',
  evidence: 'I think',
  offset: 12,
  original: 'I think the issue is in the config.',
  suggestedFix: 'I have not verified the root cause. To investigate, I can check the config file.'
}

Fix Templates (per category)

Speculation Language

• "I think X" → "I have not verified X. To check: [verification step]."
• "X is probably Y" → "X may be Y — I can verify by [method]."
• "It should be working" → "I have not confirmed whether it is working. Next step: [test]."

Causality Language

• "X because Y" → "X was observed. Y is a hypothesis — to verify: [method]."
• "caused by Z" → "Potential cause: Z. Evidence needed: [what to check]."

Completeness Claims

• "all files checked" → "I checked [list files]. Other files were not examined."
• "fully resolved" → "The specific issue in [file:line] is fixed. Other instances not checked."

Pseudo-Quantification

• "8.5/10" → Remove or replace with specific measurable criteria.
• "70% improvement" → "Measured: [before] → [after] by [method]."

Implementation

• Templates stored as data, not hardcoded strings
• Configurable via .hallucination-detectorrc.cjs (see feat: config file handling — cascading settings from multiple sources #10)
• Templates support ${evidence}, ${kind}, ${offset} interpolation
• Optional: LLM-powered rewrite mode for more natural suggestions (requires API key)

Acceptance Criteria

• Every trigger match includes suggestedFix text
• Templates exist for all four current categories
• Templates are overrideable via config (feat: config file handling — cascading settings from multiple sources #10)
• Tests validate fix generation for each category
• Stop hook output includes the suggestion in its response

Related Issues

• feat: config file handling — cascading settings from multiple sources #10 (config — custom response templates)

[Jamie-BitFlight]

Grouping: Group E — Output Pipeline

Implement together with: #17

Rationale: Both modify the output format of trigger matches:

• feat: corrected text suggestions alongside flags #13 adds a suggestedFix field to each match
• feat: structured JSON output mode for programmatic consumption #17 adds JSON/JSONL output modes alongside the existing text format

Implementing together ensures the JSON schema (#17) includes the suggestedFix field (#13) from the start, rather than extending the schema later.

Shared work:

• Both touch emitJson() and the output formatting in the stop hook
• Both reference feat: config file handling — cascading settings from multiple sources #10 (config) for settings like outputFormat and custom response templates
• The JSON schema for feat: structured JSON output mode for programmatic consumption #17 should include the suggestedFix field from feat: corrected text suggestions alongside flags #13

Dependencies: Benefits from #10 (config) for outputFormat setting and custom templates.

[Jamie-BitFlight]

Deep Analysis: Implementation Impact

Classification

• Impact type: CONTRACT (additive — adds fields to match objects)
• Risk: Low (template mode) / Medium (LLM rewrite mode)
• Phase: 5 — Output pipeline

What changes

Each trigger match gains suggestedFix and original fields. The reason string in { decision: "block", reason } includes suggested rewrites. The JSON shape { decision, reason } is preserved — the reason string just gets longer.

Template mode is safe

Template interpolation (${evidence}, ${kind}, ${offset}) is synchronous string operations. No new dependencies. No async. No risk to the hook contract.

LLM rewrite mode shares #11's risk

The optional LLM-powered rewrite requires an API call, introducing the same async/timeout/fail-open risks as #11 (RAG). Recommendation: implement template-only first. LLM rewrite is a separate, later feature.

Sequencing

• Benefits from: feat: config file handling — cascading settings from multiple sources #10 (configurable templates), but can use hardcoded templates first
• Should come before: feat: structured JSON output mode for programmatic consumption #17 (so JSON schema includes suggestedFix from the start)
• Independent of: feat: optional RAG verification tier via Exa.ai or similar #11, feat: proactive CLAUDE.md framing prompt — prevention over detection #14, feat: sentence-level granularity and weighted multi-signal scoring #21 (operates on whatever matches exist)
• If feat: sentence-level granularity and weighted multi-signal scoring #21 lands first, suggestions become per-sentence rather than per-match

Failure mode

• Template with ${evidence} containing regex special chars → string interpolation is safe (not regex replacement)
• Suggested rewrites that themselves contain trigger patterns → the rewritten text would be flagged on the next Stop hook invocation (self-correcting, not a loop because the suggestion is in the reason field, not the assistant's response)