dotscope 0.1.0__tar.gz → 1.2.0__tar.gz

dotscope-1.2.0/.claude/worktrees/hopeful-chatelet/.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-1.2.0/.claude/worktrees/hopeful-chatelet/.claude/settings.json

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

dotscope-1.2.0/.claude/worktrees/hopeful-chatelet/.claude/settings.local.json

@@ -0,0 +1,52 @@
+{
+  "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)",
+      "Bash(python -m pytest tests/test_eval_harness.py -v)",
+      "Bash(python3 -m pytest tests/test_eval_harness.py -v)",
+      "Bash(python3 -m pytest tests/ -x --timeout=30)",
+      "Bash(python3 -c \":*)",
+      "Bash(python3 -c \"import inspect; from dotscope.resolver import resolve; print\\(inspect.signature\\(resolve\\)\\)\")",
+      "Bash(python3 -m pytest tests/test_eval_harness.py tests/ -x -q)",
+      "Bash(grep -E \"\\\\.\\(py|json\\)$\")",
+      "Bash(python3:*)",
+      "Bash(ls /Users/nigel/Documents/dotscope/.claude/worktrees/hopeful-chatelet/dotscope/*.py)",
+      "Bash(xargs -I{} basename {})",
+      "Bash(for K in 10 12 15 18 20)",
+      "Bash(do python3 -c \":*)",
+      "Bash(sort -t= -k2 -n)",
+      "Bash(for K in 8 10 12 14 16)",
+      "Bash(git fetch:*)",
+      "Bash(gh pr:*)",
+      "Bash(gh api:*)"
+    ]
+  }
+}

dotscope-1.2.0/.claude/worktrees/hopeful-chatelet/.git

@@ -0,0 +1 @@
+gitdir: /Users/nigel/Documents/dotscope/.git/worktrees/hopeful-chatelet

dotscope-1.2.0/.claude/worktrees/hopeful-chatelet/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,129 @@
+# dotscope Agent Instructions
+
+## How This Codebase Works
+
+This repository is managed by dotscope, a codebase compiler that provides you with architectural context, dependency analysis, and mutation safety. You have access to dotscope's MCP tools. Use them instead of manually reading files and guessing at architecture.
+
+## The One Rule
+
+**Start every task with `codebase_search`.** Do not read files manually. Do not guess which files are relevant. `codebase_search` returns the code, its dependency neighborhood, the bodies of functions it calls, the contracts you must honor, the conventions you must follow, and which files another agent is currently mutating. One call replaces five.
+
+```
+# Wrong: manual discovery
+1. Read src/billing/webhooks.py
+2. Read src/billing/processor.py
+3. Read tests/billing/test_webhooks.py
+4. Guess at conventions
+5. Hope nothing is locked
+
+# Right: compiled retrieval
+1. codebase_search("Stripe webhook retry logic")
+   → code + dependencies + abstractions + contracts + locks — done
+```
+
+---
+
+## Tool Reference
+
+### Discovery Tools
+
+**`codebase_search(query, budget?, limit?)`**
+Your primary entry point. Natural-language query returns a compiled `ResolvedScope`:
+- `files` — ranked by architectural relevance, budget-fitted
+- `flattened_abstractions` — bodies of cross-file functions your code calls, with lock status
+- `constraints` — implicit contracts, anti-patterns, intents you must respect
+- `routing` — convention blueprints, voice rules for how to write new code
+- `retrieval_metadata` — index freshness, scores, result count
+
+Use for: any task where you don't already know the scope name.
+
+**`resolve_scope(scope_name, task?)`**
+When you already know which scope to work in (e.g., "billing", "auth"). Returns the same `ResolvedScope` structure without the retrieval layer. Useful for follow-up work after an initial `codebase_search`.
+
+Use for: continuing work in a known scope, or when a constraint references a scope by name.
+
+### Mutation Tools
+
+**`dotscope_claim_scope(scope_name, task_description)`**
+Claim exclusive write access before modifying files. The claim includes a blast radius: direct dependents get exclusive locks, two-hop dependents get shared locks. Other agents can still read but will be warned before claiming overlapping files.
+
+Call this AFTER `codebase_search` / `resolve_scope` but BEFORE writing any code.
+
+**`dotscope_renew_lock(scope_name)`**
+If your task is taking longer than expected and you receive a lock expiry warning in a `resolve_scope` response, renew immediately. An expired lock means another agent can claim your files mid-work.
+
+**`dotscope_check(diff)`**
+Pre-commit verification. Runs your changes against the contract enforcement pipeline: implicit contracts, network contracts, convention compliance, co-change requirements. This is your safety net. Always run it before committing.
+
+If `dotscope_check` returns violations, fix them before committing. The violations are structured descriptions — they tell you exactly what broke and why.
+
+**`dotscope_escalate()`**
+When you're stuck in a conflict you can't resolve: interlocking locks, merge conflicts, contract violations that require cross-scope changes beyond your claim. Escalation surfaces the full state to a human operator or supervisory agent.
+
+### Documentation Tool
+
+**`generate_artifacts(artifact?)`**
+Generates human-readable architecture documents from dotscope's analysis. Useful when asked to "document the architecture" or "explain the system contracts." Produces: `ARCHITECTURE_CONTRACTS.md`, `NETWORK_MAP.md`, `CO_CHANGE_ATLAS.md`.
+
+---
+
+## Reading a `codebase_search` Response
+
+The response is JSON. Here's what to do with each section:
+
+**`files`** — These are the files you'll be working in. They're already ranked by relevance and trimmed to your token budget. Trust the ranking.
+
+**`flattened_abstractions`** — These are the bodies of functions your code calls in other files. Read them to understand the interface contracts. Check `lock_status`:
+- `"unlocked"` — safe to modify if needed
+- `"shared_locked"` — another agent has nearby work; modify with caution
+- `"exclusive_locked"` — another agent owns this; do not modify, work with the current interface
+
+**`constraints`** — These are the rules. If a constraint says "when `pricing_engine.py` changes, `tax_calculator.py` must also change," then you must change both or change neither. Constraints with `severity: "GUARD"` will block your commit if violated. Constraints with `severity: "NOTE"` are advisory.
+
+**`routing`** — These are the conventions. If routing says "all ViewSet classes must include `permission_classes`," your new ViewSet must include it. If it specifies a voice (e.g., "docstrings use imperative mood, max 2 lines"), match it.
+
+**`retrieval_metadata`** — Check `index_freshness`. If it says `"stale"`, the vector index is outdated and results are BM25-only (keyword matching). Execute `dotscope ingest` to rebuild the index before proceeding. Without a fresh index, you are flying blind on conceptual queries.
+
+---
+
+## Standard Workflow
+
+### For any code modification task:
+
+```
+1. DISCOVER    codebase_search("your task description")
+2. UNDERSTAND  Read the response: files, abstractions, constraints, routing
+3. CLAIM       dotscope_claim_scope("scope_name", "task description")
+4. WRITE       Make your changes, respecting constraints and conventions
+5. CHECK       dotscope_check(your_diff)
+6. FIX         If violations, fix and re-check
+7. COMMIT      Only after check passes
+```
+
+**If step 3 is rejected** (overlapping exclusive locks), do not force the changes. You have three options: wait for the lock to release and retry, switch to a different task that doesn't overlap, or use `dotscope_escalate()` if the blocking lock appears stale or the task is urgent.
+
+### For multi-file changes:
+
+If `codebase_search` returns a co-change contract (e.g., `pricing_engine.py` ↔ `tax_calculator.py`), you must modify both files in the same commit. The contract exists because these files have historically always changed together. Changing one without the other will likely break something.
+
+### For cross-scope work:
+
+If your task requires changes in multiple scopes, claim each scope separately. If a scope is already claimed by another agent, either wait or escalate. Do not modify files outside your claimed scopes.
+
+### When a merge conflict occurs:
+
+If your `git merge` or `git rebase` fails, do NOT look for `<<<<<<< HEAD` markers. dotscope's AST Merge Driver intercepts the failure and injects a `ConflictDescriptor` JSON into your context. This descriptor contains: the conflicting function name, the other agent's version, the dependency footprint of each change, and the relevant architectural contracts. Read the conflict reason, refactor your code to align with the other agent's merged signature, and run `dotscope_check` again. If you cannot resolve the conflict programmatically, use `dotscope_escalate()`.
+
+---
+
+## Anti-Patterns
+
+**Do not manually crawl the repo.** Every `read_file` call you make instead of using `codebase_search` wastes context window and misses architectural signals. `codebase_search` already read the files, resolved the dependencies, flattened the abstractions, and checked the locks.
+
+**Do not ignore constraints.** If a constraint says GUARD severity, `dotscope_check` will reject your commit. Fix the violation rather than working around it.
+
+**Do not skip `dotscope_check`.** It catches contract violations, convention drift, and co-change requirements that are invisible from reading the code alone. A clean diff is not a safe diff.
+
+**Do not modify exclusively-locked files.** If `lock_status` is `"exclusive_locked"`, another agent is actively working on that code. Your changes will conflict. Work with the current interface or escalate.
+
+**Do not guess at conventions.** The `routing` section of the response tells you exactly how to write new code in this scope: naming patterns, import style, docstring format, required attributes. Match them.

dotscope-1.2.0/.claude/worktrees/hopeful-chatelet/README.md

@@ -0,0 +1,90 @@
+<p align="center">
+  <img src="logo.png" alt="dotscope" width="400">
+</p>
+
+You give an agent a task. It searches your codebase, finds the files,
+writes the code, runs the tests, and ships. Sounds fine until you
+realize it changed a backend endpoint without touching the frontend
+that calls it. It put a utility function in `src/helpers/` instead of
+next to the module that uses it. It ignored the naming convention every
+other file follows. And when two agents worked at the same time, they
+silently overwrote each other's changes.
+
+The code compiled. The tests passed. Production broke.
+
+This happens because agents don't have what you have — the full
+picture. They see files. You see architecture.
+
+**dotscope is the operating system for agent-driven codebases.**
+
+One command scans your project and learns the architecture: which files
+depend on which, what patterns your code follows, how your backend
+talks to your frontend, and what breaks when something changes. From
+that point on, every agent gets the full picture before it writes a
+line.
+
+It does five things:
+
+1. **One search, everything you need.** An agent describes what it
+   wants to do. dotscope returns the relevant files, the functions
+   they call, the contracts they must honor, the conventions they must
+   follow, and which files are locked by other agents. One call. Not
+   five.
+
+2. **Enforces contracts across languages.** Your Python backend and
+   TypeScript frontend share an invisible API contract. dotscope
+   extracts routes from FastAPI, Flask, and DRF. It extracts fetch
+   calls from React and Angular. It links them automatically. Change
+   a Django ViewSet without updating the Angular component? Blocked.
+
+3. **Routes files to the right place.** Before an agent creates a
+   file, it asks dotscope where it should go. dotscope reads the
+   dependency graph and routes the file there. No more `src/utils/`
+   graveyards.
+
+4. **Coordinates multiple agents.** When Agent A starts working on
+   billing, dotscope locks the blast radius. Agent B works on auth
+   without collision. If they touch the same function, the AST merge
+   driver resolves it semantically — not with conflict markers.
+
+5. **Gets smarter with every commit.** Which search results did agents
+   actually use? Which did they ignore? dotscope tracks this and
+   adjusts. Conventions that hold up get enforced harder. Rules that
+   get overridden get quieter.
+
+Here's what it looks like on a real codebase:
+
+```
+$ dotscope ingest
+
+  Analyzing dependency graph...
+  Mining git history...
+  Discovering conventions...
+
+  Discoveries:
+  - version.py and environment.prod.ts always change together
+  - workflow-edit-dialog.component.ts and models.py are tightly coupled
+
+  Validation (49 commits backtested):
+  - Overall recall: 78%
+  - Token reduction: 67% (1.3M → 437K avg)
+
+  Output: 3 .scope files written.
+
+$ dotscope check --backtest
+
+  13 issues flagged across 7 commits:
+  - models.py changes need the Angular component updated
+  - consumer.py changes need matching parser test updates
+  - views.py changes typically need test_api_search.py updated
+
+  3 commits were clean.
+```
+
+One command. Point it at anything.
+
+```
+pip install dotscope && dotscope init
+```
+
+[How It Works](docs/how-it-works.md) · [Scope Files](docs/scope-file.md) · [Agent Instructions](AGENT_INSTRUCTIONS.md) · [MIT](LICENSE)

dotscope-1.2.0/.claude/worktrees/hopeful-chatelet/docs/how-it-works.md

@@ -0,0 +1,146 @@
+# 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, what not to break, and who else is working.
+
+## 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
+- Registers an AST-aware merge driver for scoped files
+- 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 locks** — which files other agents are working on right now
+
+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:
+
+- **Holds** (blocking) — The agent modified a backend endpoint without updating the frontend consumer. Or it wrote to a file locked by another agent. Or it violated a frozen module. The commit is stopped. The agent fixes it or acknowledges the override with an audit trail.
+- **Notes** (informational) — A low-confidence link was flagged, or a file could live in a better directory. Worth knowing, 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 sees across languages
+
+Your Python backend and your TypeScript frontend share an invisible contract: the HTTP API. dotscope sees both sides.
+
+When an agent modifies a Django ViewSet that serves `/api/documents/`, dotscope knows that `document-list.component.ts` calls that endpoint. If the agent changes the backend without updating the frontend, the commit is blocked.
+
+This works for FastAPI, Flask, Django REST Framework (including class-based ViewSets), Angular `HttpClient`, React, and any fetch/axios call. dotscope extracts routes and HTTP calls from the AST and links them with confidence scoring:
+
+- **1.0** — exact regex match (decorator path matches fetch URL)
+- **0.8** — suffix-aligned match (handles base URL differences)
+- **0.5** — semantic root match (`DocumentViewSet` linked to `/api/document-types/`)
+
+High-confidence matches (>= 0.8) block the commit. Low-confidence matches (0.5) surface as informational notes.
+
+## It knows where files go
+
+Agents dump utility functions in `src/utils/` and helpers in `src/helpers/`. Six months later, nobody can find anything.
+
+dotscope prevents this with two rules derived from the dependency graph:
+
+- **Orphan Rule** — If a file is only imported by one other file, it should live in the same directory as its parent.
+- **Shared Rule** — If a file is imported from multiple directories, it should live at their lowest common ancestor.
+
+Before an agent creates a file, it can ask:
+
+```
+dotscope_route_file("Stripe webhook retry task", imports=["domains.billing.models"])
+→ domains/billing/tasks/
+```
+
+If an agent ignores the suggestion, the commit gets a note with a ready-to-apply `git mv` + AST-safe import rewrites across all dependent files.
+
+On new projects, dotscope scaffolds a clean domain-driven structure from the first commit.
+
+## It coordinates multiple agents
+
+When two agents work on the same codebase at the same time, they will eventually touch the same file. dotscope prevents this with the Swarm Lock — a semantic mutex built on the dependency graph.
+
+When Agent A claims a scope, dotscope computes the **blast radius** — not just the files Agent A asked for, but everything connected to them:
+
+- **Depth 1** (direct dependents, network consumers, high-confidence co-change partners) — exclusively locked. Other agents cannot modify these.
+- **Depth 2** (two-hop dependents) — shared lock with warnings. Other agents can read but get a warning before writing.
+- **Depth 3+** — no lock. If two agents happen to modify the same function, the AST merge driver handles it.
+
+Locks expire after 30 minutes. Agents can renew them. If a lock-related conflict fails to resolve after 2 attempts, dotscope escalates to a human operator with the full conflict state.
+
+## It merges code semantically
+
+When two agents legitimately modify the same file — say Agent A edits `get_user()` and Agent B adds `delete_user()` — Git's line-level merger often breaks. dotscope replaces it with an AST-aware merge driver.
+
+The merge driver:
+1. Extracts named mutations from each agent's diff (function edits, class changes, import additions)
+2. Checks for conflicts (same function modified by both → halt)
+3. Merges imports using set logic: `(Ancestor - Removed_A - Removed_B) ∪ Added_A ∪ Added_B`
+4. Reconstructs the source in two passes: reverse-order replacements (no offset drift), then fresh insertion targets for additions
+5. Runs contract verification on the merged result before accepting
+
+The driver is registered via `.gitattributes` — only files in active scopes use it. Everything else falls through to Git's default merger.
+
+## 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: utility scores, swarm locks, cached graphs, network edges. 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. Python and JS/TS also get cross-language network contract detection (backend routes linked to frontend API calls) and AST-aware merging.
+
+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)

{dotscope-0.1.0 → dotscope-1.2.0/.claude/worktrees/hopeful-chatelet}/docs/scope-file.md

@@ -218,6 +218,22 @@ conventions:
 - `prohibited_imports` — imports that violate the convention
 - `required_methods` — methods all matching classes must implement
 - `must_have_matching` — pattern for a companion file (e.g., a test file)
+- `allowed_paths` — regex patterns for where matching files should live (spatial routing)
+
+```yaml
+conventions:
+  - name: "REST Controller"
+    source: discovered
+    match:
+      any_of:
+        - has_decorator: "router"
+    rules:
+      prohibited_imports: [sqlalchemy]
+      allowed_paths: ["domains/[^/]+/api/.*\\.py"]
+    compliance: 0.92
+```
+
+The `allowed_paths` rule is discovered automatically during ingest — if 80%+ of files matching a convention share a directory structure, that structure becomes the allowed path. Agents that create files in the wrong directory get a note with a `git mv` fix.
 
 **Compliance** tracks what percentage of matching files follow the rules. Conventions with >=80% compliance are enforced as HOLDs, 50-79% as NOTEs, and below 50% are retired.
 
@@ -249,9 +265,21 @@ voice:
 
 See [How It Works](how-it-works.md) for voice discovery and enforcement.
 
+## Multi-Agent State
+
+When multiple agents work concurrently, dotscope maintains additional state in `.dotscope/cache/`:
+
+- **`swarm_state.json`** — active locks, blast radii, and conflict descriptors
+- **`network_edges.json`** — cross-language API contract links (provider → consumer)
+- **`network_confidence.json`** — match confidence scores per link (1.0/0.8/0.5)
+- **`graph_hubs.json`** — dependency graph hub data for fast lookups
+
+This state is ephemeral (gitignored) and rebuilds from `dotscope ingest`. The `.gitattributes` file (which registers the AST merge driver for scoped files) should be committed.
+
 ## What to Commit
 
 - **`.scope` files** — commit them. They're institutional memory.
 - **`.scopes` index** — commit it. Project metadata.
 - **`intent.yaml`** — commit it. Team's architectural direction.
+- **`.gitattributes`** — commit it. Merge driver registration for scoped files.
 - **`.dotscope/`** — gitignored. Machine state. Rebuilds automatically.

{dotscope-0.1.0 → dotscope-1.2.0/.claude/worktrees/hopeful-chatelet}/dotscope/.scope

@@ -10,6 +10,21 @@ includes:
   - dotscope/discovery.py
   - dotscope/parser.py
   - dotscope/visibility.py
+  - dotscope/hooks.py
+  - dotscope/budget.py
+  - dotscope/models.py
+  - dotscope/assertions.py
+  - dotscope/health.py
+  - dotscope/utility.py
+  - dotscope/sessions.py
+  - dotscope/virtual.py
+  - dotscope/lessons.py
+  - dotscope/graph.py
+  - dotscope/textio.py
+  - dotscope/tokens.py
+  - dotscope/matcher.py
+  - dotscope/ast_analyzer.py
+  - .scopes
 excludes:
   - dotscope/__pycache__/
   - dotscope/models/
@@ -56,6 +71,10 @@ related:
   - dotscope/models/.scope
   - dotscope/passes/.scope
   - dotscope/storage/.scope
+  - dotscope/search/.scope
+  - dotscope/generate/.scope
+  - dotscope/merge/.scope
+  - dotscope/eval/.scope
 tags:
   - cli
   - mcp

{dotscope-0.1.0 → dotscope-1.2.0/.claude/worktrees/hopeful-chatelet}/dotscope/assertions.py

@@ -10,6 +10,7 @@ Defined in intent.yaml (project-wide) or .scope files (per-scope).
 from typing import Dict, List, Optional
 
 from .models.intent import Assertion, ContextExhaustionError  # noqa: F401
+from .textio import read_repo_text
 
 
 def load_assertions(repo_root: str, scope_name: str = "") -> List[Assertion]:
@@ -26,8 +27,7 @@ def load_assertions(repo_root: str, scope_name: str = "") -> List[Assertion]:
     intent_path = os.path.join(repo_root, "intent.yaml")
     if os.path.exists(intent_path):
         from .parser import _parse_yaml
-        with open(intent_path, "r", encoding="utf-8") as f:
-            data = _parse_yaml(f.read())
+        data = _parse_yaml(read_repo_text(intent_path).text)
         for item in _to_list_of_dicts(data.get("assertions", [])):
             assertions.append(_parse_assertion(item))
 
@@ -38,8 +38,7 @@ def load_assertions(repo_root: str, scope_name: str = "") -> List[Assertion]:
         if scope_path:
             try:
                 from .parser import _parse_yaml
-                with open(scope_path, "r", encoding="utf-8") as f:
-                    data = _parse_yaml(f.read())
+                data = _parse_yaml(read_repo_text(scope_path).text)
                 raw = data.get("assertions", {})
                 if isinstance(raw, dict):
                     a = Assertion(scope=scope_name)