dotscope 0.1.0__tar.gz

dotscope-0.1.0/.claude/hooks/pre-commit-check.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# dotscope pre-commit enforcement for Claude Code
+#
+# Intercepts git commit commands and runs dotscope check on staged changes.
+# Exit 2 blocks the commit and feeds the error back to the agent.
+# Non-commit Bash commands pass through untouched.
+
+set -e
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+# Only intercept git commit commands
+case "$COMMAND" in
+    git\ commit*) ;;
+    *) exit 0 ;;
+esac
+
+# Run dotscope check on staged changes (30s timeout, fail open)
+if command -v timeout >/dev/null 2>&1; then
+    OUTPUT=$(timeout 30 python3 -m dotscope.cli check 2>&1) || true
+elif command -v gtimeout >/dev/null 2>&1; then
+    OUTPUT=$(gtimeout 30 python3 -m dotscope.cli check 2>&1) || true
+else
+    OUTPUT=$(python3 -m dotscope.cli check 2>&1) || true
+fi
+
+# Only GUARDs block. NUDGEs and NOTEs pass through.
+if echo "$OUTPUT" | grep -qE "GUARD|HOLD"; then
+    echo "$OUTPUT" >&2
+    echo "" >&2
+    echo "dotscope: commit blocked -- address guards before committing" >&2
+    exit 2
+fi
+
+# NUDGEs and NOTEs are guidance, not gates
+if echo "$OUTPUT" | grep -qE "NUDGE|NOTE"; then
+    echo "$OUTPUT" >&2
+fi
+
+exit 0

dotscope-0.1.0/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/pre-commit-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

dotscope-0.1.0/.claude/settings.local.json

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -c \"from dotscope.mcp_server import create_server; create_server\\(\\)\")",
+      "Bash(python3 -c \"from dotscope.mcp_server import main\")",
+      "Bash(chmod +x /Users/nigel/Documents/dotscope/.claude/hooks/pre-commit-check.sh)",
+      "Bash(python3 -m pytest tests/ -x -q)",
+      "WebSearch",
+      "WebFetch(domain:support.claude.com)",
+      "Bash(python3 -m pytest tests/test_line_filter.py -x -q)",
+      "Bash(git add:*)",
+      "Bash(python3 -m dotscope.cli check --acknowledge contract_dotscope_visibility__tests_test_visibilit_f05a15 --reason \"Large feature commit — visibility changes are internal\")",
+      "Bash(python3 -m dotscope.cli check --acknowledge contract_dotscope_mcp_server__dotscope_models_py_556414 --reason \"Large feature commit — models.py not affected by these changes\")",
+      "Bash(python3 -m dotscope.cli check --acknowledge contract_dotscope_mcp_server__dotscope_budget_py_8639b0 --reason \"Large feature commit — budget.py not affected\")",
+      "Bash(python3 -m dotscope.cli check --acknowledge contract_dotscope_mcp_server__tests_test_visibilit_57f45e --reason \"Large feature commit — visibility tests not affected\")",
+      "Bash(python3 -m dotscope.cli check --acknowledge contract_dotscope_cli_py_dotscope_models_py_42c554 --reason \"Large feature commit — models.py not affected\")",
+      "mcp__dotscope__dotscope_acknowledge",
+      "Bash(git commit:*)",
+      "Bash(git pull:*)",
+      "Bash(git push:*)",
+      "Bash(ls /Users/nigel/Downloads/dotscope*)",
+      "Bash(ls -t /Users/nigel/Downloads/*.png /Users/nigel/Downloads/*.jpg /Users/nigel/Downloads/*.svg)",
+      "Bash(python3 -c \"from dotscope.passes.sentinel import *\")",
+      "Bash(grep -n \"write_text\\\\|path.write\\\\|json.dump\" /Users/nigel/Documents/dotscope/dotscope/storage/*.py)",
+      "Bash(grep -n \"/ \" /Users/nigel/Documents/dotscope/dotscope/passes/*.py)",
+      "Bash(grep -n \"\\\\.get\\(\" /Users/nigel/Documents/dotscope/dotscope/passes/sentinel/*.py)",
+      "Bash(wc -l /Users/nigel/Documents/dotscope/dotscope/*.py)",
+      "Bash(grep -n \"\\\\[\"\"\" /Users/nigel/Documents/dotscope/dotscope/passes/sentinel/checks/*.py)",
+      "Bash(python3 -m py_compile dotscope/passes/convention_discovery.py dotscope/passes/convention_parser.py dotscope/passes/convention_compliance.py dotscope/passes/semantic_diff.py dotscope/passes/voice_discovery.py dotscope/passes/voice_defaults.py dotscope/passes/voice.py dotscope/passes/lazy.py dotscope/passes/incremental.py dotscope/passes/graph_builder.py dotscope/passes/history_miner.py dotscope/passes/budget_allocator.py dotscope/passes/backtest.py dotscope/passes/ast_analyzer.py dotscope/passes/virtual.py)",
+      "Bash(grep -n \"sys.exit\\(1\\)\" dotscope/*.py)",
+      "Bash(grep -n \"$\\\\|echo\\\\|grep\" /Users/nigel/Documents/dotscope/dotscope/storage/git_hooks.py)",
+      "Bash(grep -n \"\\\\.get.*\\\\[0\\\\]\" dotscope/passes/*.py)"
+    ]
+  }
+}

dotscope-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.dotscope/

dotscope-0.1.0/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "dotscope": {
+      "command": "python3",
+      "args": ["-m", "dotscope.mcp_server"],
+      "env": {}
+    }
+  }
+}

dotscope-0.1.0/.scopes

@@ -0,0 +1,28 @@
+version: 1
+total_repo_tokens: 42000
+
+scopes:
+  models:
+    path: dotscope/models/.scope
+    keywords: [models, dataclasses, types, core, history, intent, state]
+    description: Data models — the single source of truth for all types
+  passes:
+    path: dotscope/passes/.scope
+    keywords: [analysis, ast, graph, budget, enforcement, sentinel, checks]
+    description: Analysis engine — the active verbs of the compiler
+  storage:
+    path: dotscope/storage/.scope
+    keywords: [storage, sessions, hooks, cache, onboarding, timing]
+    description: Infrastructure — disk I/O, hooks, caching, state persistence
+  dotscope:
+    path: dotscope/.scope
+    keywords: [cli, mcp, resolve, ingest, compose, parse, format, visibility]
+    description: Root interfaces and orchestrators
+  tests:
+    path: tests/.scope
+    keywords: [tests, pytest, enforcement, experience, rigor, e2e]
+    description: Test suite — 266 tests across all features
+
+defaults:
+  max_tokens: 8000
+  include_related: false

dotscope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Supremum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dotscope-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: dotscope
+Version: 0.1.0
+Summary: Directory-scoped context boundaries for AI coding agents
+Author: Supremum
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,coding,context,mcp,scope
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: tree-sitter-go>=0.23.0
+Requires-Dist: tree-sitter-javascript>=0.23.0
+Requires-Dist: tree-sitter-typescript>=0.23.0
+Requires-Dist: tree-sitter>=0.23.0
+Provides-Extra: all
+Requires-Dist: mcp>=1.2.0; extra == 'all'
+Requires-Dist: tiktoken; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers; extra == 'embeddings'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == 'mcp'
+Provides-Extra: tokens
+Requires-Dist: tiktoken; extra == 'tokens'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="logo.png" alt="dotscope" width="400">
+</p>
+
+When agents write your code, no one remembers the architecture.
+Which files depend on each other. Which patterns the last agent followed.
+What breaks when you change something.
+
+dotscope remembers. It reads your codebase, learns the rules, and
+gives every agent the context it needs — before it writes a line.
+
+Works on existing codebases and new projects. Point it at anything.
+
+```
+pip install dotscope && dotscope init
+```
+
+[How It Works](docs/how-it-works.md) · [Docs](docs/scope-file.md) · [MIT](LICENSE)

dotscope-0.1.0/README.md

@@ -0,0 +1,18 @@
+<p align="center">
+  <img src="logo.png" alt="dotscope" width="400">
+</p>
+
+When agents write your code, no one remembers the architecture.
+Which files depend on each other. Which patterns the last agent followed.
+What breaks when you change something.
+
+dotscope remembers. It reads your codebase, learns the rules, and
+gives every agent the context it needs — before it writes a line.
+
+Works on existing codebases and new projects. Point it at anything.
+
+```
+pip install dotscope && dotscope init
+```
+
+[How It Works](docs/how-it-works.md) · [Docs](docs/scope-file.md) · [MIT](LICENSE)

dotscope-0.1.0/docs/architecture.md

@@ -0,0 +1,72 @@
+# Architecture
+
+dotscope is structured as an agentic compiler. Data definitions (Nouns), analysis operations (Verbs), and persistence (Memory).
+
+```
+dotscope/
+├── models/              # What the compiler knows
+│   ├── core.py          #   Static structure (AST, graph, scopes, conventions)
+│   ├── history.py       #   Empirical behavior (contracts, stability)
+│   ├── intent.py        #   Human rules (intents, conventions, assertions, checks)
+│   ├── state.py         #   Persistent memory (sessions, observations)
+│   └── passes.py        #   Transient outputs (ingest plans, semantic diffs)
+├── passes/              # What the compiler does
+│   ├── graph_builder.py #   Dependency analysis
+│   ├── history_miner.py #   Git history mining
+│   ├── budget_allocator.py    # Token budgeting with assertions
+│   ├── convention_discovery.py # Discover conventions from structural patterns
+│   ├── convention_parser.py   # Match files to conventions, check rules
+│   ├── convention_compliance.py # Compliance tracking + severity
+│   ├── semantic_diff.py       # Convention-level structural diff
+│   ├── voice_discovery.py     # Scan codebase for coding style patterns
+│   ├── voice_defaults.py      # Prescriptive defaults for new codebases
+│   ├── voice.py               # Voice injection into resolve responses
+│   ├── lazy.py                # On-demand single-module ingest
+│   ├── incremental.py         # Post-commit incremental scope updates
+│   └── sentinel/        #   Routing engine (8 checks, constraints, decay)
+├── storage/             # How the compiler remembers
+│   ├── session_manager.py     # Session + observation persistence
+│   ├── cache.py               # Cached analysis data
+│   ├── git_hooks.py           # Pre-commit routing + post-commit feedback
+│   ├── claude_hooks.py        # Claude Code PreToolUse hook
+│   ├── mcp_config.py          # Auto-detect IDE, write MCP config
+│   ├── onboarding.py          # Stage-aware milestone tracking
+│   ├── timing.py              # Operation instrumentation
+│   ├── near_miss.py           # Near-miss detection persistence
+│   └── incremental_state.py   # Continuous ingest drift tracking
+├── progress.py          # Streaming progress emitter
+├── help.py              # Hand-written help text
+├── cli.py               # Human interface
+└── mcp_server.py        # Agent interface
+```
+
+The Nouns live in `models/`. The Verbs live in `passes/`. The Memory lives in `storage/`. The Interfaces are at the root.
+
+## Design Principles
+
+**Routing, not enforcement.** Constraints at resolve time are the bowling bumpers. Checks at commit time verify the bumpers worked. Only frozen modules and deprecated imports hard-block.
+
+**Severity levels:** GUARD (blocks commit), NUDGE (prints guidance, passes through), NOTE (informational). Nudges that fire 3+ times auto-escalate to GUARD.
+
+**Zero dependencies.** Python 3.9+ stdlib only. Cross-platform.
+
+## What's in `.dotscope/`
+
+Runtime state. Gitignored. Fully rebuildable via `dotscope ingest .`.
+
+```
+.dotscope/
+  history.json           # Cached implicit contracts, stabilities, hotspots
+  graph_hubs.json        # Cached cross-cutting hub analysis
+  invariants.json        # Contracts, function co-changes, file stabilities
+  sessions/              # Per-session JSON files (predictions)
+  observations/          # Observation events from post-commit hooks
+  regressions/           # Frozen successful sessions (regression test cases)
+  near_misses.jsonl      # Detected near-misses
+  utility_scores.json    # Per-file utility scores
+  nudge_occurrences.jsonl # NUDGE escalation tracking
+  timings.jsonl          # Operation timing data
+  acknowledgments.jsonl  # Acknowledged guards with reasons
+  onboarding.json        # Milestone tracking
+  last_session.json      # Scopes resolved in most recent session
+```

dotscope-0.1.0/docs/cli-reference.md

@@ -0,0 +1,67 @@
+# CLI Reference
+
+## Setup
+
+```bash
+pip install dotscope
+dotscope init
+```
+
+`dotscope init` does everything: ingest, hook install, MCP config for detected IDEs. One command.
+
+For manual setup or re-runs:
+
+```bash
+dotscope ingest .               # Full re-ingest
+dotscope hook install           # Re-install hooks
+```
+
+## Commands
+
+```bash
+# Context
+dotscope resolve auth --budget 4000
+dotscope resolve auth+payments
+
+# Routing verification
+dotscope check
+dotscope check --backtest
+dotscope intent add freeze core/
+
+# Conventions
+dotscope conventions                  # List all conventions + compliance
+dotscope conventions --discover       # Discover patterns from codebase
+dotscope diff --staged                # Semantic diff against conventions
+
+# Voice
+dotscope voice                        # Show discovered voice config
+dotscope voice --upgrade typing       # Tighten enforcement as codebase improves
+
+# Rigor
+dotscope test-compiler
+dotscope bench
+dotscope debug --last
+
+# Hooks
+dotscope hook install             # Pre-commit routing + post-commit feedback
+dotscope hook claude              # Claude Code pre-commit hook (defense-in-depth)
+dotscope hook status              # Check what's installed
+
+# Maintenance
+dotscope health
+dotscope impact auth/tokens.py
+```
+
+## MCP Server
+
+For agents, add the MCP server:
+
+```json
+{
+  "mcpServers": {
+    "dotscope": { "command": "dotscope-mcp" }
+  }
+}
+```
+
+`dotscope init` configures this automatically for Claude Desktop, Claude Code, and Cursor.

dotscope-0.1.0/docs/how-it-works.md

@@ -0,0 +1,86 @@
+# How It Works
+
+You run `dotscope init`. It scans your codebase. From that point on, every agent that touches your code gets the full picture — what files matter, what patterns to follow, and what not to break.
+
+## What happens when you run `dotscope init`
+
+dotscope reads every file in your project and learns three things:
+
+**Which files are connected.** If `billing.py` and `webhook_handler.py` always change together in your git history, dotscope knows. When an agent changes one, it gets told to check the other.
+
+**What patterns your code follows.** If every file in `api/routes/` uses the same decorator and never touches the database directly, dotscope recognizes that as a convention. New files in that folder will follow the same pattern automatically.
+
+**How your code is written.** Type hints on most functions? Google-style docstrings? No bare `except:` blocks? dotscope measures the style of your existing code and teaches agents to match it.
+
+After the scan, dotscope:
+- Installs git hooks so it stays up to date on every commit
+- Connects to your AI tool (Claude Desktop, Claude Code, or Cursor) automatically
+- Shows you what it would have caught in your last 50 commits
+
+## What agents see
+
+When an agent starts working on your code, it asks dotscope: "What do I need to know about this part of the project?"
+
+dotscope responds with:
+- **The right files** — not the whole repo, just the ones that matter for this task
+- **The rules** — which files are connected, what patterns to follow, what imports are off-limits
+- **The style** — how the existing code is written, so new code matches
+
+The agent gets all of this before writing a single line. It writes code that fits in on the first try.
+
+## What happens when something goes wrong
+
+Before every commit, dotscope checks the agent's work:
+
+- **Blocks** (rare) — The agent tried to modify a frozen module or use deprecated code. The commit is stopped. The agent fixes it.
+- **Nudges** (common) — The agent changed a file without updating its counterpart, or drifted from a convention. The agent sees the guidance and self-corrects.
+- **Notes** (informational) — Something worth knowing but not worth blocking.
+
+Most of the time, nothing fires. The routing is good enough that agents follow the rules without needing to be corrected.
+
+## It gets smarter over time
+
+Every commit teaches dotscope something. Did the agent need a file that wasn't included? Next time, it will be. Did a convention hold up across 50 commits? Its enforcement gets stronger. Did a rule get overridden three times in a month? It gets quieter.
+
+You don't need to configure any of this. It happens automatically through the git hooks installed during `dotscope init`.
+
+## What you can customize
+
+dotscope works out of the box, but you can tune it:
+
+**Freeze a module.** If you have stable code that agents shouldn't touch:
+```
+dotscope intent add freeze core/
+```
+Any change to `core/` will be blocked until acknowledged.
+
+**Deprecate a file.** If you're migrating away from old code:
+```
+dotscope intent add deprecate utils/legacy.py --replacement utils/helpers.py
+```
+Agents that try to import from the old file get redirected.
+
+**Edit conventions.** dotscope discovers conventions automatically, but you can add your own or adjust the ones it found. They live in `intent.yaml` at the root of your project.
+
+## What gets created
+
+dotscope creates two kinds of files:
+
+**`.scope` files** (one per folder) — These describe what an agent needs to know about that part of your code. Commit them. They're your project's memory.
+
+**`.dotscope/` folder** — Machine state. Gitignored. Rebuilds automatically if deleted.
+
+Both are plain text. You can read them, edit them, or ignore them entirely.
+
+## Languages supported
+
+Python, JavaScript, TypeScript, and Go get full analysis — every function, every class, every import relationship mapped.
+
+Other languages get basic import detection (enough for the dependency graph and git history analysis, but no convention or style discovery).
+
+## Further reading
+
+- [The .scope File](scope-file.md) — what's inside a scope file and how to edit it
+- [MCP Server Setup](mcp-setup.md) — manual setup for AI tools (usually not needed after `dotscope init`)
+- [CLI Reference](cli-reference.md) — every command dotscope offers
+- [Architecture](architecture.md) — how dotscope itself is built (for contributors)