description: Infrastructure — disk I/O, hooks, caching, state persistence
includes:
  - session_manager.py
  - cache.py
  - git_hooks.py
  - claude_hooks.py
  - onboarding.py
  - timing.py
  - near_miss.py
  - incremental_state.py
excludes:
  - __pycache__/
context: |
  Storage reads and writes models.state to disk. Pure infrastructure.

  ## session_manager.py
  SessionManager class. Creates sessions (.dotscope/sessions/),
  records observations (.dotscope/observations/). Matches commits
  to sessions by timestamp overlap.

  ## cache.py
  Caches history analysis and graph hubs after ingest so the MCP
  server can load them at startup without re-computing.

  ## git_hooks.py
  Two git hooks installed by `dotscope hook install`:
    pre-commit: runs `dotscope check`, blocks on HOLDs (enforcement)
    post-commit: runs `dotscope observe` + `dotscope incremental` (feedback)
  Cross-platform: POSIX shell script or Python fallback for Windows.
  Marks hook_installed in onboarding state.

  ## claude_hooks.py
  Claude Code PreToolUse hook installed by `dotscope hook claude`.
  Writes .claude/hooks/pre-commit-check.sh and wires it into
  .claude/settings.json. Defense-in-depth layer for Claude Code.

  ## onboarding.py
  Milestone tracking in .dotscope/onboarding.json. Gating rules:
  counterfactuals after 3+ observations, health nudges after 7+ days.
  Next-step prompts: ingest -> backtest -> conventions -> voice -> MCP -> hook -> stop.

  ## timing.py
  Appends operation timing (resolve, check, ingest) to timings.jsonl.
  Used by dotscope bench.

  ## near_miss.py
  Persistent storage for near-miss detections and session scopes.

  ## incremental_state.py
  Tracks commits_since_last_full_ingest in .dotscope/incremental.json.
  Reset after full ingest. Used to prompt for re-scan after 200 commits.

  ## Gotchas
  All file I/O uses encoding="utf-8" for Windows compatibility.
  Session files are JSON, observation files are JSONL (append-only).
  .dotscope/ is gitignored and fully rebuildable via `dotscope rebuild`.
related:
  - dotscope/models/.scope
tags:
  - storage
  - sessions
  - hooks
  - caching
tokens_estimate: 3800
