{"id":51189938,"url":"https://github.com/kestiny18/scopediff","last_synced_at":"2026-06-27T14:02:45.649Z","repository":{"id":363109164,"uuid":"1225597412","full_name":"kestiny18/scopediff","owner":"kestiny18","description":"Local-first scope checker for AI-generated code changes.","archived":false,"fork":false,"pushed_at":"2026-06-07T12:43:39.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T14:20:15.124Z","etag":null,"topics":["ai","claude-code","cli","code-review","codex","coding-agent","cursor","diff","git"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@scopediff-dev/cli","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kestiny18.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-30T12:50:23.000Z","updated_at":"2026-06-07T12:43:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kestiny18/scopediff","commit_stats":null,"previous_names":["kestiny18/scopediff"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/kestiny18/scopediff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestiny18%2Fscopediff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestiny18%2Fscopediff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestiny18%2Fscopediff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestiny18%2Fscopediff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kestiny18","download_url":"https://codeload.github.com/kestiny18/scopediff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestiny18%2Fscopediff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34855826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","cli","code-review","codex","coding-agent","cursor","diff","git"],"created_at":"2026-06-27T14:02:44.884Z","updated_at":"2026-06-27T14:02:45.638Z","avatar_url":"https://github.com/kestiny18.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ScopeDiff\n\n[![npm](https://img.shields.io/npm/v/@scopediff-dev/cli.svg)](https://www.npmjs.com/package/@scopediff-dev/cli)\n[![CI](https://github.com/kestiny18/scopediff/actions/workflows/ci.yml/badge.svg)](https://github.com/kestiny18/scopediff/actions/workflows/ci.yml)\n[![license](https://img.shields.io/npm/l/@scopediff-dev/cli.svg)](LICENSE)\n\n\u003e Status: early (v0.2). Useful today; the CLI surface and rules may still change.\n\nLet AI write code without letting it rewrite your project.\n\nScopeDiff reports when AI-generated code changes drift outside the scope a task\ndeclared. It runs locally, requires no API key, and works with Cursor, Codex,\nClaude Code, and other AI coding workflows.\n\nMost AI code review tools ask:\n\n\u003e Is this code good?\n\nScopeDiff asks:\n\n\u003e Was this code supposed to change?\n\n## How it answers that\n\nScopeDiff does **not** try to guess your intent from a prompt. Instead, the task\ndeclares its scope up front — the paths it expects to touch — and ScopeDiff\ncompares the actual diff against that declaration. It is an **attention router**:\nit points you (or your agent) at the few changes that fall outside the declared\nscope, and gets out of the way for everything that's in scope.\n\nIts guiding principle is **trust over coverage**: only high-confidence facts\n(an undeclared dependency/lockfile/migration/CI/secret change) ever *block*.\nFuzzy, inferred findings are surfaced for review but never block.\n\n## Why ScopeDiff\n\nAI coding agents are useful, but they drift: touching unrelated modules,\nchanging dependencies, deleting tests, or rewriting build files while solving a\nnarrow task. ScopeDiff catches that drift before you finish a task or open a PR.\n\n## Installation\n\nRequires **Node.js ≥ 20** and **git**.\n\n```bash\nnpm install -g @scopediff-dev/cli\n```\n\nOr run without installing:\n\n```bash\nnpx @scopediff-dev/cli check\n```\n\n## Declared scope (recommended)\n\nAt the start of a task, declare what it should touch:\n\n```bash\nscopediff intent --task \"fix login empty password returns 400\" --allow \"src/auth/**\"\n```\n\nThis writes `.scopediff/intent.json`. Then, after changes, check the diff:\n\n```bash\nscopediff check\n```\n\nExample output (declared `src/auth/**`, but the diff also touched `package.json`\nand `src/payment/`):\n\n```text\nScopeDiff Report\n\nMode:\n  scope\n\nDeclared scope:\n  task: fix login empty password returns 400\n  allow: src/auth/**\n\nSummary:\n  1 high, 1 medium, 0 info\n  3 files, 6 changed lines\n\nHigh Risk:\n  [SD019] High-risk file changed outside declared scope\n  file: package.json\n  reason: This file was changed but is not covered by the declared scope (src/auth/**). High-risk files require an explicit declaration.\n  blocking: true\n\nPotential Scope Drift:\n  [SD019] Potential scope drift: file changed outside declared scope\n  file: src/payment/PaymentService.ts\n  reason: This file was changed but is not covered by the declared scope (src/auth/**). Please review whether it belongs in this task.\n\nResult:\n  failed because 1 blocking finding(s) were found.\n```\n\nFiles inside the declared scope (and test files) stay silent. An undeclared\nhigh-risk file blocks; an undeclared ordinary source file is a non-blocking\nreview note; an undeclared docs file is informational.\n\n## Without a declaration\n\nIf there is no `.scopediff/intent.json`, ScopeDiff degrades gracefully:\n\n- **Deterministic danger tripwires still fire on fact** — env/secret changes,\n  test deletion, and large deletions are flagged regardless of scope.\n- **Keyword heuristics become a best-effort fallback** — it guesses task domains\n  from a prompt or branch name. These findings are review hints and **never\n  block**.\n\nYou can still pass context explicitly:\n\n```bash\nscopediff check --prompt \"fix login empty password returns 400\"\nscopediff check --prompt-file task.md\n```\n\n## Diff source\n\n```bash\nscopediff check            # git diff HEAD (all tracked changes)\nscopediff check --staged   # git diff --staged\nscopediff check --base main # git diff main...HEAD\n```\n\n## Agent workflows\n\n```bash\nscopediff init cursor\nscopediff init codex\nscopediff init claude\n```\n\nExecution differs by tool, and ScopeDiff is honest about it:\n\n| Tool | Enforcement | How |\n| --- | --- | --- |\n| **Claude Code** | **Hard** | `init claude` installs a `Stop` hook (`scopediff check --hook`) that runs automatically before the agent finishes and sends it back on blocking findings. Merged into `.claude/settings.json`. |\n| **Cursor** | Soft (best-effort) | `.cursor/rules/scopediff.mdc` asks the agent to declare scope and check. The agent may skip it. |\n| **Codex** | Soft (best-effort) | `AGENTS.md` asks the agent to declare scope and check. The agent may skip it. |\n\n\u003e Deterministic post-turn hooks for Cursor and Codex are not yet supported here;\n\u003e on those tools enforcement is best-effort until that is verified.\n\n## Configuration\n\n```bash\nscopediff init   # writes scopediff.yml\n```\n\nScopeDiff reads `scopediff.yml` from the current project.\n\n## Exit codes\n\n- `0`: passed\n- `1`: blocked by findings at or above the configured `fail_on` (default: HIGH)\n- `2`: runtime or config error\n\n## Rules\n\nFindings carry an ID (`SD001`–`SD019`). The full rule list, severities, and the\ndeclared-intent model are documented in [SPEC.md](SPEC.md).\n\n## Privacy\n\nScopeDiff runs locally. Your code, diffs, and task context are not uploaded. No\nAPI key is required. No LLM is used — semantic judgment, when needed, is left to\nthe coding agent already in your editor.\n\n## Roadmap\n\n- v0.1: CLI, local rules, config, Risk Mode, Agent Pack\n- v0.2: declared-intent scope engine, Claude Code Stop hook, honest agent docs\n- v0.2.x: verify Cursor/Codex hooks, file-level scope precision, more rules\n- v1.0: PR bot, team policies, dashboard\n\n## Contributing\n\nIssues and PRs are welcome. Local setup:\n\n```bash\ngit clone https://github.com/kestiny18/scopediff.git\ncd scopediff\nnpm install\nnpm run check   # build + tests\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for project layout and how rules are\nstructured.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkestiny18%2Fscopediff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkestiny18%2Fscopediff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkestiny18%2Fscopediff/lists"}