feat: proactive CLAUDE.md framing prompt — prevention over detection

[Jamie-BitFlight]

Summary

The initial CLAUDE.md behavioral framing prompt has been added (commit b560871). This issue tracks improvements and iterations on the proactive prevention approach — shaping assistant behavior before hallucinations occur rather than only catching them after.

Current State

CLAUDE.md in the plugin root is auto-loaded by Claude Code when the plugin is installed. It currently:

• Bans speculation language ("likely", "probably", "I think", etc.)
• Requires tool-verified claims
• Enforces evidence-based communication
• Prevents completeness overclaims

Planned Improvements

Framing Refinements

• Add examples of good vs bad responses for each category
• Include a decision tree: "Can I verify this? → Yes: verify → No: say 'I don't know'"
• Tune the wording to minimize false interventions on legitimate language
• Add escape hatch instructions for when speculation is explicitly requested by the user

Integration with Stop Hook

• Stop hook should reference CLAUDE.md rules in its output ("This violates the framing rule about...")
• Track repeat violations within a session — escalating responses
• First violation: gentle reminder. Second: stronger warning. Third: block and require verification.

Multi-Platform Framing

• Cursor: equivalent framing via .cursor-plugin/ configuration
• Codex: framing guidance in .codex/INSTALL.md
• OpenCode: system prompt injection in .opencode/plugins/hallucination-detector.cjs

Metrics

• Count how many stop-hook triggers occur per session
• Compare trigger rates before/after CLAUDE.md is installed
• Identify which categories are most frequently violated (focus improvement there)

Related Issues

• feat: config file handling — cascading settings from multiple sources #10 (config — framing text should be customizable)

[Jamie-BitFlight]

Grouping: Standalone

No hard dependencies on other issues. The CLAUDE.md improvements and multi-platform framing can be done independently at any time.

Note: The "stop hook should reference CLAUDE.md rules" sub-task connects to the output pipeline (Group E, #13/#17). The "metrics" sub-task connects to #17 (structured output for aggregation). These can be done incrementally.

[Jamie-BitFlight]

Deep Analysis: Implementation Impact

Classification

• Impact type: INFRASTRUCTURE (state management) + CONTRACT (decision logic change)
• Risk: HIGH — changes the loop prevention safety valve
• Phase: 6 — Stateful escalation (implement last among core changes)

The critical concern: loop prevention

The current system blocks on the 1st and 2nd trigger, then allows through on the 3rd+ to prevent infinite loops (Claude Code retries → hook blocks → retry → block → ...). This is at lines 513–521 of hallucination-audit-stop.cjs.

The escalation model proposes: 1st = gentle reminder, 2nd = stronger warning, 3rd = hard block. This inverts the safety valve. If the 3rd+ trigger always blocks and Claude Code always retries, the session deadlocks.

Implementation constraint: The escalation model MUST preserve an escape valve (e.g., after N escalated blocks, allow through).

State requirements — unique among all issues

This is the only issue that requires extending the persistent state layer:

Current state	Proposed state
{ blocks: N } in /tmp/	{ blocks: N, violations: [...], categories: { speculation_language: 3 }, tier: "gentle"|"strong"|"block" }

Additionally, the "compare trigger rates before/after" sub-feature requires cross-session metrics that survive beyond /tmp/ (e.g., ~/.hallucination-detector/metrics.jsonl).

Race condition (inherited)

The existing loadLoopState/saveLoopState has a TOCTOU race: two concurrent Stop hook invocations could both read { blocks: 1 }, both increment to 2, and one write overwrites the other. This risk is amplified by #14's richer state. Mitigation: atomic writes (write to temp + rename) or accepting the race as low-probability (Claude sessions are typically serial).

Hook coordination — new coupling

The SessionStart hook and Stop hook currently share NO state. #14 introduces coupling:

• Stop hook writes violation counts
• SessionStart hook may read prior counts to adjust framing ("You have been flagged N times...")
• Both hooks must agree on file location and schema

Dependencies

• Depends on: feat: config file handling — cascading settings from multiple sources #10 (config for maxBlocksPerSession), should come after feat: sentence-level granularity and weighted multi-signal scoring #21 (so escalation logic knows what "a trigger" means in the scoring model)
• Blocked by: feat: config file handling — cascading settings from multiple sources #10, feat: sentence-level granularity and weighted multi-signal scoring #21
• Conflicts with: feat: sentence-level granularity and weighted multi-signal scoring #21 (both change the block/allow decision — must be sequenced, not parallel)

Failure modes

• Escape valve removed → session deadlock
• State file format change → old format files from before the upgrade cause parse errors → fall back to { blocks: 0 } (safe, but loses escalation history)
• Cross-session metrics file grows unboundedly → needs rotation or size cap

[Jamie-BitFlight]

Cross-reference: also depends on #10

This issue is a sub-issue of #21 (scoring). It also depends on #10 (config) for `maxBlocksPerSession` and framing text customization.

Full dependency chain: #10 → #21 → #14