scori 0.1.0__tar.gz

scori-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install deps
+        run: uv sync --group dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type-check
+        run: uv run mypy src/
+      - name: Test
+        run: uv run pytest

scori-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+# Publica no PyPI ao fazer push de uma tag v* (ex.: v0.1.0).
+#
+# IMPORTANTE — antes do primeiro push é preciso configurar o Trusted
+# Publisher em https://pypi.org/manage/account/publishing/ com:
+#   PyPI Project Name : scori
+#   Owner             : <teu-user-github>
+#   Repository name   : scori
+#   Workflow filename : publish.yml
+#   Environment name  : pypi
+# Sem isso o passo "uv publish --trusted-publishing always" falha por
+# falta de credenciais — não há tokens nem secrets para configurar.
+
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/scori
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish --trusted-publishing always

scori-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# uv / venv
+.venv/
+.python-version
+uv.lock
+
+# OS / IDE
+.DS_Store
+.idea/
+*.swp
+
+# Claude Code local config
+.claude/
+
+# scori
+.scori/
+scori-report.html

scori-0.1.0/.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "MD013": false,
+  "MD024": { "siblings_only": true }
+}

scori-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-requests]

scori-0.1.0/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "ms-python.mypy-type-checker",
+    "charliermarsh.ruff",
+    "eamodio.gitlens",
+    "tamasfe.even-better-toml"
+  ]
+}

scori-0.1.0/.vscode/launch.json

@@ -0,0 +1,29 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "scori scan",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "scori",
+      "args": ["scan", "--path", "."],
+      "justMyCode": false
+    },
+    {
+      "name": "scori friction (json)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "scori",
+      "args": ["friction", "--path", ".", "--format", "json"],
+      "justMyCode": false
+    },
+    {
+      "name": "scori friction (table)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "scori",
+      "args": ["friction", "--path", ".", "--format", "table"],
+      "justMyCode": false
+    }
+  ]
+}

scori-0.1.0/.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.testing.pytestEnabled": true,
+  "python.testing.pytestArgs": ["tests"],
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": { "source.fixAll.ruff": "explicit" }
+  },
+  "mypy-type-checker.enabled": true,
+  "editor.rulers": [88],
+  "files.exclude": {
+    "**/__pycache__": true,
+    "**/.mypy_cache": true
+  },
+  "snyk.advanced.autoSelectOrganization": true
+}

scori-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+semantic versioning [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+- `scori update` command with three modes:
+  - `--dry-run`: shows a table of pending version bumps without touching files
+  - `--apply`: writes updated versions to manifest files and creates a backup
+    in `.scori-backup/`
+  - `--rollback`: restores manifest files from the last backup
+  - `--max-friction <label>`: limits updates to deps at or below the given
+    friction label (`low`, `medium`, `high`, `critical`)
+- `scori monitor` command: shows only dependencies with available updates,
+  sorted by friction score (highest first); marks with ★ packages where
+  updating fixes known CVEs
+- `--watch` flag on `scori monitor` for continuous polling (default interval:
+  300 s, configurable via `--interval`)
+- CVEs fixed by the latest release now contribute up to +15 pts to the
+  friction score (`+3` per fixed CVE, capped at 15); CVEs that persist in
+  the latest version do not affect the score
+- `--ci` flag on `scori friction`: exits with code 1 if any dependency score
+  exceeds a configurable threshold (default: 75, override with `--threshold`)
+- `CVEs` column in `scori friction` table showing known vulnerabilities per
+  version via the OSV API
+- Installed version resolution for unpinned dependencies by inspecting the
+  project's local venv (`.venv/`, `venv/`, `env/`)
+
+## [0.1.0] - 2026-05-12
+
+### Added
+
+- `scori scan`: reads requirements.txt, pyproject.toml, setup.cfg
+- `scori friction`: computes friction score 0–100 per dependency
+- Local cache in ~/.cache/scori/ with 1-hour TTL
+- Output as table (CLI), JSON, and basic HTML

scori-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: scori
+Version: 0.1.0
+Summary: Software Composition Risk Intelligence — score the real cost of updating a dependency
+Project-URL: Homepage, https://github.com/pauloestevao795/scori
+Project-URL: Repository, https://github.com/pauloestevao795/scori
+Project-URL: Issues, https://github.com/pauloestevao795/scori/issues
+Project-URL: Changelog, https://github.com/pauloestevao795/scori/blob/main/CHANGELOG.md
+Author-email: Paulo Estevao <pestevao@scori.dev>
+License-Expression: MIT
+Keywords: dependencies,friction,risk,sca,score,security,update
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: packaging>=24.0
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# scori
+
+**Software Composition Risk Intelligence** — *Know the cost before you update.*
+
+[![PyPI](https://img.shields.io/pypi/v/scori.svg)](https://pypi.org/project/scori/)
+[![Python](https://img.shields.io/pypi/pyversions/scori.svg)](https://pypi.org/project/scori/)
+[![License](https://img.shields.io/pypi/l/scori.svg)](LICENSE)
+[![CI](https://github.com/pauloestevao795/scori/actions/workflows/ci.yml/badge.svg)](https://github.com/pauloestevao795/scori/actions/workflows/ci.yml)
+
+Free tools like `pip-audit`, OSV-Scanner, and Dependabot detect vulnerabilities and open update PRs — but none of them answer the question that matters: *is it worth updating this lib right now, or does the migration cost outweigh the risk of not doing it?* `scori` quantifies that friction as a single 0–100 score per dependency, using public data from PyPI, GitHub, and the OSV vulnerability database.
+
+## Install
+
+```bash
+pip install scori
+# or
+uv add scori
+```
+
+## Usage
+
+```bash
+# Show friction scores for every dependency
+scori friction --path .
+scori friction --path . --format json > report.json
+scori friction --path . --format html        # writes scori-report.html
+scori friction --path . --ci                 # exit 1 if any score > 75
+scori friction --path . --ci --threshold 50  # stricter gate
+
+# Show only dependencies with updates available, sorted by friction
+scori monitor --path .
+scori monitor --path . --watch               # re-check every 5 minutes
+scori monitor --path . --watch --interval 60 # re-check every 60 s
+
+# Preview and apply dependency version updates
+scori update --path . --dry-run              # show what would change
+scori update --path . --apply                # write changes + create backup
+scori update --path . --apply --max-friction medium  # only Low/Medium deps
+scori update --path . --rollback             # restore from last backup
+
+# List all detected dependencies
+scori scan --path .
+```
+
+Example output (`scori friction --format table`, with color indicators):
+
+```text
+                          scori — friction scores
+┌───────────┬─────────┬─────────┬───────┬───────┬──────────┬─────────┐
+│ Package   │ Current │ Latest  │ Jump  │ Score │ Label    │  CVEs   │
+├───────────┼─────────┼─────────┼───────┼───────┼──────────┼─────────┤
+│ django    │ 3.2.0   │ 5.1.0   │ major │  78   │ Critical │ 3 → 0 ✓ │
+│ nltk      │ 3.8.1   │ 3.9.4   │ minor │  35   │ Medium   │ 9 → 0 ✓ │
+│ requests  │ 2.31.0  │ 2.32.3  │ patch │   8   │ Low      │    —    │
+└───────────┴─────────┴─────────┴───────┴───────┴──────────┴─────────┘
+```
+
+The **CVEs** column shows known vulnerabilities in your current version and
+whether they are fixed in the latest release:
+
+- `9 → 0 ✓` — 9 CVEs in current, all fixed in latest (prioritize this update)
+- `3` — 3 CVEs, still present in latest (update won't help with security)
+- `—` — no known vulnerabilities in either version
+
+`scori monitor` shows only the packages that have a newer release available,
+sorted by friction score (highest first), and marks with ★ any package where
+updating also fixes known CVEs.
+
+## How it works
+
+The friction score is a weighted sum of five components (max 100):
+
+| Component                           | Max weight | Logic                               |
+|-------------------------------------|------------|-------------------------------------|
+| Semantic version jump               | 50         | patch=5, minor=25, major=50         |
+| Breaking signals in changelog       | 20         | +4 per keyword found (max 20)       |
+| Affected transitive dependencies    | 15         | +3 per transitive dep (max 15)      |
+| CVEs fixed by updating              | 15         | +3 per fixed CVE (max 15)           |
+| Months without updating in project  | 10         | +1 per month (max 10)               |
+| Current version yanked              | 5          | +5 if `yanked: true` in PyPI API    |
+
+Labels:
+
+- 0–25 → **Low** → *Safe to update*
+- 26–50 → **Medium** → *Update with tests*
+- 51–75 → **High** → *Update in isolated branch*
+- 76–100 → **Critical** → *Manual migration required*
+
+CVE data is fetched from the [OSV database](https://osv.dev) (free, no auth required).
+CVEs that are **fixed by updating** contribute up to +15 points to the
+friction score — a dependency where updating resolves known vulnerabilities
+will score higher, pushing it toward the top of your update queue. CVEs that
+remain present in the latest version do not affect the score (updating won't
+help with those).
+
+### Data sources
+
+| Source | Data |
+| --- | --- |
+| `https://pypi.org/pypi/{pkg}/json` | Latest version, release dates, yanked status |
+| `https://api.github.com/repos/{owner}/{repo}/releases` | Release notes for breaking signal detection |
+| `https://api.osv.dev/v1/query` | Known CVEs per version |
+
+Set `GITHUB_TOKEN` in your environment to raise the GitHub API rate limit from 60/h to 5000/h. PyPI and GitHub release data is cached in `~/.cache/scori/` for 1 hour. OSV results are cached in memory for the duration of a single run.
+
+### Version resolution
+
+For pinned dependencies (`fastapi==0.115.8`), the pinned version is used directly. For unpinned dependencies (`uvicorn` with no version), scori looks up the installed version in the project's local venv (`.venv/`, `venv/`, or `env/`) before falling back to `0.0.0`.
+
+## Roadmap
+
+- **v0.2** — `scori report`: rich HTML with charts and history
+- **v0.3** — support for `poetry.lock` and `uv.lock` for real transitive tree
+
+## Contributing
+
+PRs and issues are welcome. Local setup:
+
+```bash
+git clone https://github.com/pauloestevao795/scori
+cd scori
+uv sync --group dev
+uv run pre-commit install
+uv run pytest
+```
+
+## License
+
+MIT

scori-0.1.0/README.md

@@ -0,0 +1,129 @@
+# scori
+
+**Software Composition Risk Intelligence** — *Know the cost before you update.*
+
+[![PyPI](https://img.shields.io/pypi/v/scori.svg)](https://pypi.org/project/scori/)
+[![Python](https://img.shields.io/pypi/pyversions/scori.svg)](https://pypi.org/project/scori/)
+[![License](https://img.shields.io/pypi/l/scori.svg)](LICENSE)
+[![CI](https://github.com/pauloestevao795/scori/actions/workflows/ci.yml/badge.svg)](https://github.com/pauloestevao795/scori/actions/workflows/ci.yml)
+
+Free tools like `pip-audit`, OSV-Scanner, and Dependabot detect vulnerabilities and open update PRs — but none of them answer the question that matters: *is it worth updating this lib right now, or does the migration cost outweigh the risk of not doing it?* `scori` quantifies that friction as a single 0–100 score per dependency, using public data from PyPI, GitHub, and the OSV vulnerability database.
+
+## Install
+
+```bash
+pip install scori
+# or
+uv add scori
+```
+
+## Usage
+
+```bash
+# Show friction scores for every dependency
+scori friction --path .
+scori friction --path . --format json > report.json
+scori friction --path . --format html        # writes scori-report.html
+scori friction --path . --ci                 # exit 1 if any score > 75
+scori friction --path . --ci --threshold 50  # stricter gate
+
+# Show only dependencies with updates available, sorted by friction
+scori monitor --path .
+scori monitor --path . --watch               # re-check every 5 minutes
+scori monitor --path . --watch --interval 60 # re-check every 60 s
+
+# Preview and apply dependency version updates
+scori update --path . --dry-run              # show what would change
+scori update --path . --apply                # write changes + create backup
+scori update --path . --apply --max-friction medium  # only Low/Medium deps
+scori update --path . --rollback             # restore from last backup
+
+# List all detected dependencies
+scori scan --path .
+```
+
+Example output (`scori friction --format table`, with color indicators):
+
+```text
+                          scori — friction scores
+┌───────────┬─────────┬─────────┬───────┬───────┬──────────┬─────────┐
+│ Package   │ Current │ Latest  │ Jump  │ Score │ Label    │  CVEs   │
+├───────────┼─────────┼─────────┼───────┼───────┼──────────┼─────────┤
+│ django    │ 3.2.0   │ 5.1.0   │ major │  78   │ Critical │ 3 → 0 ✓ │
+│ nltk      │ 3.8.1   │ 3.9.4   │ minor │  35   │ Medium   │ 9 → 0 ✓ │
+│ requests  │ 2.31.0  │ 2.32.3  │ patch │   8   │ Low      │    —    │
+└───────────┴─────────┴─────────┴───────┴───────┴──────────┴─────────┘
+```
+
+The **CVEs** column shows known vulnerabilities in your current version and
+whether they are fixed in the latest release:
+
+- `9 → 0 ✓` — 9 CVEs in current, all fixed in latest (prioritize this update)
+- `3` — 3 CVEs, still present in latest (update won't help with security)
+- `—` — no known vulnerabilities in either version
+
+`scori monitor` shows only the packages that have a newer release available,
+sorted by friction score (highest first), and marks with ★ any package where
+updating also fixes known CVEs.
+
+## How it works
+
+The friction score is a weighted sum of five components (max 100):
+
+| Component                           | Max weight | Logic                               |
+|-------------------------------------|------------|-------------------------------------|
+| Semantic version jump               | 50         | patch=5, minor=25, major=50         |
+| Breaking signals in changelog       | 20         | +4 per keyword found (max 20)       |
+| Affected transitive dependencies    | 15         | +3 per transitive dep (max 15)      |
+| CVEs fixed by updating              | 15         | +3 per fixed CVE (max 15)           |
+| Months without updating in project  | 10         | +1 per month (max 10)               |
+| Current version yanked              | 5          | +5 if `yanked: true` in PyPI API    |
+
+Labels:
+
+- 0–25 → **Low** → *Safe to update*
+- 26–50 → **Medium** → *Update with tests*
+- 51–75 → **High** → *Update in isolated branch*
+- 76–100 → **Critical** → *Manual migration required*
+
+CVE data is fetched from the [OSV database](https://osv.dev) (free, no auth required).
+CVEs that are **fixed by updating** contribute up to +15 points to the
+friction score — a dependency where updating resolves known vulnerabilities
+will score higher, pushing it toward the top of your update queue. CVEs that
+remain present in the latest version do not affect the score (updating won't
+help with those).
+
+### Data sources
+
+| Source | Data |
+| --- | --- |
+| `https://pypi.org/pypi/{pkg}/json` | Latest version, release dates, yanked status |
+| `https://api.github.com/repos/{owner}/{repo}/releases` | Release notes for breaking signal detection |
+| `https://api.osv.dev/v1/query` | Known CVEs per version |
+
+Set `GITHUB_TOKEN` in your environment to raise the GitHub API rate limit from 60/h to 5000/h. PyPI and GitHub release data is cached in `~/.cache/scori/` for 1 hour. OSV results are cached in memory for the duration of a single run.
+
+### Version resolution
+
+For pinned dependencies (`fastapi==0.115.8`), the pinned version is used directly. For unpinned dependencies (`uvicorn` with no version), scori looks up the installed version in the project's local venv (`.venv/`, `venv/`, or `env/`) before falling back to `0.0.0`.
+
+## Roadmap
+
+- **v0.2** — `scori report`: rich HTML with charts and history
+- **v0.3** — support for `poetry.lock` and `uv.lock` for real transitive tree
+
+## Contributing
+
+PRs and issues are welcome. Local setup:
+
+```bash
+git clone https://github.com/pauloestevao795/scori
+cd scori
+uv sync --group dev
+uv run pre-commit install
+uv run pytest
+```
+
+## License
+
+MIT

scori-0.1.0/ROADMAP.md

@@ -0,0 +1,166 @@
+# scori Roadmap
+
+> *Know the cost before you update.*
+
+scori is a free, auth-free CLI for Python that quantifies the real cost of updating a dependency as a single friction score (0–100). It complements tools like `pip-audit`, OSV-Scanner, and Dependabot — which tell you *what* to update — by answering the harder question: *should you update it now, and how much will it hurt?* The friction score is a concept not yet present in open-source dependency tooling, and scori aims to make it a first-class signal in every Python project's maintenance workflow.
+
+---
+
+## Current status — v0.1.0 ✅
+
+- [x] `scori scan`: reads `requirements.txt`, `pyproject.toml` (PEP 517/518), `setup.cfg`
+- [x] `scori friction`: computes friction score 0–100 per dependency
+- [x] Weighted scoring algorithm: version jump, breaking signals, transitive deps, months outdated, yanked status
+- [x] Labels: Low / Medium / High / Critical with color-coded table output
+- [x] CVEs column via [OSV API](https://osv.dev) — shown as `3 → 0 ✓`, separate from the score
+- [x] Output formats: table (rich), JSON, HTML
+- [x] Local cache in `~/.cache/scori/` with 1-hour TTL (PyPI + GitHub data)
+- [x] `GITHUB_TOKEN` support to raise API rate limit from 60/h to 5000/h
+- [x] Installed version resolution for unpinned deps via local venv inspection
+
+**Known limitations in v0.1.0:**
+
+- Unpinned dependencies without a local venv fall back to `0.0.0` (no conda/pyenv/Docker support yet)
+- Transitive dependency count is always 0 — requires a lockfile parser (planned for v0.3)
+- CVE count is informational only — not yet factored into the friction score
+- `scori monitor`, `scori update`, and `scori report` are stubbed in the CLI but not implemented
+
+---
+
+## v0.2 — Full CLI surface
+
+Complete the commands already declared in the CLI but not yet implemented.
+
+### `scori monitor` ✅
+
+- [x] Poll PyPI for new releases on all project dependencies
+- [x] Output a "updates available" table sorted by friction score (highest friction first)
+- [x] `--watch` flag for continuous monitoring with a configurable interval
+- [x] Highlight dependencies where a new release also fixes known CVEs (★ marker)
+
+### `scori update` ✅
+
+- [x] `--dry-run`: show a diff of what would change in the manifest without applying
+- [x] `--apply`: apply updates and create an automatic backup of the original manifest
+- [x] `--rollback`: restore the most recent backup
+- [x] `--max-friction <label>`: only update deps at or below a given friction label (e.g. `medium`)
+
+### `scori report`
+
+- [ ] Standalone HTML report with a visual traffic-light indicator per dependency
+- [ ] Structured JSON export suitable for CI/CD pipeline consumption
+- [ ] `--ci` flag: exit with code 1 if any dependency exceeds a configurable score threshold
+
+---
+
+## v0.3 — Smarter scoring
+
+Improve the accuracy and depth of the friction score algorithm.
+
+### Real transitive dependency counts
+
+- [ ] Parse `poetry.lock` to count packages that depend on the package being updated
+- [ ] Parse `uv.lock` for the same
+- [ ] Use the resolved count in the score weight (currently always 0)
+
+### CVEs in the score
+
+- [x] Incorporate OSV CVE count directly into the weighted algorithm (up to +15 pts)
+- [ ] Weight CVSS ≥ 9.0 CVEs more heavily than lower-severity ones
+
+### Improved breaking signal detection
+
+- [ ] Scan `CHANGELOG.md` from the GitHub repo in addition to release notes
+- [ ] Detect `BREAKING CHANGE:` in Conventional Commits commit history
+- [ ] Heuristic diff of `.pyi` type stub files between versions as an API-change signal
+
+### Broader version resolution
+
+- [ ] Resolve unpinned versions via `conda list --json` when inside a conda environment
+- [ ] Support pyenv shims as a version source
+- [ ] Optional: detect version from Docker image labels (requires Docker CLI, off by default)
+
+---
+
+## v0.4 — Integrations
+
+Bring scori into the workflows and tools developers already use.
+
+### GitHub Actions
+
+- [ ] Official `scori-action` published to the GitHub Marketplace
+- [ ] Automatic PR comment with a friction table for any changed dependencies
+- [ ] Dynamic badge for `README.md` showing the project's average friction score
+
+### Pre-commit hook
+
+- [ ] Official hook for `.pre-commit-config.yaml`
+- [ ] Configurable threshold — block commit if any dep exceeds it
+
+### VSCode Extension *(stretch goal)*
+
+- [ ] Inline decoration showing the friction score per line in `requirements.txt` / `pyproject.toml`
+- [ ] CodeLens action: "Run scori friction on this package"
+
+---
+
+## v0.5 — Intelligence layer
+
+Higher-level features that turn scori from a scoring tool into a maintenance advisor.
+
+### Score history
+
+- [ ] Track friction scores over time per project in local storage
+- [ ] Trend chart: surface dependencies that are becoming riskier over successive runs
+
+### Risk profiles
+
+- [ ] Per-project `.scori.toml` configuration for custom thresholds and weights
+- [ ] Built-in profiles: `conservative`, `balanced`, `aggressive`
+
+### Suggested update order
+
+- [ ] Rank dependencies by update order to minimise total migration risk
+- [ ] Detect conflicts between simultaneous updates (e.g. shared transitive dep with incompatible constraints)
+
+### LLM-assisted changelog summary *(opt-in)*
+
+- [ ] Plain-language summary of what changes in a given update
+- [ ] Supports local inference via Ollama or `OPENAI_API_KEY` — never required to use scori
+- [ ] Off by default; enabled explicitly with `--summarise`
+
+---
+
+## Non-goals
+
+scori has a deliberate scope. The following are explicitly out of scope:
+
+- **Not a CVE scanner.** scori shows CVE counts as context, but `pip-audit` and OSV-Scanner do this properly. Use them alongside scori, not instead.
+- **Not a package manager.** scori reads and optionally edits manifests, but it does not resolve or install packages.
+- **Python only.** Supporting npm, cargo, or other ecosystems is out of scope. scori's scoring model is designed around the PyPI and GitHub release data available for Python packages.
+- **No account required.** scori will never require a login, subscription, or mandatory API key. Optional tokens (e.g. `GITHUB_TOKEN`) may improve rate limits, but the tool is always fully functional without them.
+
+---
+
+## How to contribute
+
+Contributions are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) (coming soon) for the full guide.
+
+**Priority areas for external contributions:**
+
+- Manifest parsers for additional formats (`conda.yml`, `Pipfile`, `Pipfile.lock`)
+- Integration tests against well-known real-world projects
+- CLI message internationalisation (i18n)
+
+Issues labelled **`good first issue`** on GitHub are the recommended starting point for new contributors.
+
+---
+
+## Versioning policy
+
+scori follows [Semantic Versioning](https://semver.org).
+
+- Patch releases (`0.x.y`) fix bugs without changing behaviour.
+- Minor releases (`0.x`) add features in a backwards-compatible way.
+- Breaking changes to the CLI interface will only occur in major releases.
+- The public API (`FrictionResult`, `Dependency`, `compute()`) is considered stable from v1.0 onwards. Until then, minor releases may include breaking changes to the Python API — the CLI surface is the stable interface.