feat: offline fallback for Langfuse + repo quality guardrails

[michaelpetrik]

Summary

• Offline fallback (src/offlineFallback.js): when Langfuse is unreachable and all retries are exhausted, a lightweight session reference is appended to ~/.claude/telemetry-fallback.jsonl. The reference contains sessionId, userId, org metadata, and cost/token stats — enough to locate the full transcript in local Claude session data (~/.claude/projects/). No retry queue, no replay — just a bookmark.
• Quality guardrails: first-time baseline bringing the repo up to the node-ts reference standard from zero local enforcement.

Changes

Offline fallback

File	Change
src/offlineFallback.js	New — writeReference(), getFallbackPath(), JSONL append-only
src/sessionHandler.js	finalize() catch block now calls writeReference(this) on flush failure
src/serverHelpers.js	createConfig() exposes fallbackFile field
.env.example	Documents FALLBACK_FILE env var
docs/ENVIRONMENT_VARIABLES.md	FALLBACK_FILE section added
test/unit/offlineFallback.test.js	New — dir creation, append, missing metadata, write

Quality guardrails

File	What it adds
AGENTS.md	Canonical agent doc (was missing; CLAUDE.md is now @AGENTS.md)
.nvmrc	Pins Node 22 for local dev
.githooks/pre-commit	lint + format:check + staged-file secret scan
scripts/install-hooks.sh	One-time hook wiring (npm run hooks:install)
scripts/ci/run_quality_gates.sh	Offline-runnable gate: format + lint + unit tests
scripts/ci/run_security_review.sh	npm audit + secret scan + docker build smoke
package.json	quality, security, hooks:install scripts; AGENTS.md in files[]
.quality/guardrails-report.md	Full policy vs enforcement matrix with N/A rows

Prettier was also run across the entire codebase — format:check was never in CI so 41 files had accumulated drift.

Test plan

• npm run quality passes (format:check + lint + unit tests)
• npm test — 12 suites, 160 tests all pass
• CI should pass on this PR (lint, unit tests, docker build, security scan)
• Manual: verify ~/.claude/telemetry-fallback.jsonl is written when Langfuse is stopped and bridge receives telemetry

Guardrail status summary

Control	Status
AGENTS.md / claudecode-conventions	enforced
Local hook wiring	enforced
Local quality gate	enforced
Secret scanning (local)	enforced
Pinned toolchain manifest	partial (.nvmrc + engines range)
Dep vulnerability audit	partial (network-dependent npm audit)
Docker / runtime checks	partial (Trivy CI-only)
GitNexus / code intelligence	policy-only (bootstrap: npx gitnexus analyze)

🤖 Generated with Claude Code