holt-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{holt_cli-0.1.0 → holt_cli-0.2.0}/.gitignore

@@ -14,6 +14,8 @@ node_modules/
 # Worktrees are checkouts, not content. `git add -A` swept one in once.
 .claude/worktrees/
 .claude/settings.local.json
+# Maintainer plugin choices (third-party marketplaces); copied into worktrees via .worktreeinclude
+.claude/settings.json
 
 # Live TUI runs record here, deliberately outside fixtures/trajectories/ so a
 # session can never rewrite the recordings the eval harness replays.

holt_cli-0.2.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.5
+Name: holt-cli
+Version: 0.2.0
+Summary: Evidence-backed assessment of whether a GitHub repository is a viable opportunity for an external contributor.
+Project-URL: Homepage, https://githolt.com
+Project-URL: Documentation, https://github.com/holt-oss/holt/tree/main/docs
+Project-URL: Repository, https://github.com/holt-oss/holt.git
+Project-URL: Issues, https://github.com/holt-oss/holt/issues
+Project-URL: Changelog, https://github.com/holt-oss/holt/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/holt-oss/holt/security/policy
+Author-email: Aahil Khan <aahilminookhan@gmail.com>
+Maintainer-email: Aahil Khan <aahilminookhan@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cli,contributors,github,open-source,repository-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.60
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=3.6.0
+Requires-Dist: textual>=0.80
+Description-Content-Type: text/markdown
+
+# Holt
+
+[![CI](https://github.com/holt-oss/holt/actions/workflows/ci.yml/badge.svg)](https://github.com/holt-oss/holt/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/holt-cli.svg?color=83a9ff)](https://pypi.org/project/holt-cli/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-69c7a6.svg)](https://github.com/holt-oss/holt/blob/main/pyproject.toml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-83a9ff.svg)](https://github.com/holt-oss/holt/blob/main/LICENSE)
+
+**Find an open-source project that will actually merge your first PR.**
+
+Paste a GitHub repository. Holt reads its recent pull requests and tells you,
+in plain English, whether newcomers get replies, get merged, and where their
+work lands. The answer is one of **Worth your time**, **Not worth your time**
+or **Not enough evidence**, with links to the pull requests behind it.
+
+![Holt answering for pallets/flask, then finding starter issues](https://raw.githubusercontent.com/holt-oss/holt/main/assets/demo.gif)
+
+<!-- HOLT_SITE_URL: the product lives at https://githolt.com -->
+**[Try it in your browser](https://githolt.com)** · no install, no
+account · [Install the CLI](#2-the-command-line) ·
+[Get the browser extension](#3-the-browser-extension)
+
+Holt is read-only. It never opens pull requests, posts comments or contacts
+maintainers, on any surface.
+
+## Three ways to use it
+
+### 1. The web app
+
+<!-- HOLT_SITE_URL -->
+Open **<https://githolt.com>** and paste a repository. Or take any GitHub
+link and **swap hub for holt**: `github.com` becomes `githolt.com`, and you
+land on the report.
+
+```text
+https://github.com/home-assistant/core
+https://githolt.com/home-assistant/core
+```
+
+No repository in mind? **Find a project** asks which languages you read and how
+much time you have, then lists welcoming repositories with open starter issues.
+
+<table>
+  <tr>
+    <td><img src="https://raw.githubusercontent.com/holt-oss/holt/main/assets/web-report-light-desktop.jpg" alt="The report for home-assistant/core: Worth your time, with the counts behind it and where to start" width="640"></td>
+    <td><img src="https://raw.githubusercontent.com/holt-oss/holt/main/assets/web-find-dark-phone.jpg" alt="Find a project on a phone: pick languages and time, get welcoming repositories" width="200"></td>
+  </tr>
+</table>
+
+### 2. The command line
+
+The same engine runs on your machine, from PyPI. It needs Python 3.11 or newer;
+use whichever installer you have (all three work in PowerShell too):
+
+```sh
+pipx install holt-cli
+uv tool install holt-cli
+pip install --user holt-cli
+```
+
+Give it a GitHub token once. Holt reads only public data, so
+[create a token](https://github.com/settings/tokens/new?description=holt) with
+every box unticked, then run `holt token` and paste it. If you use the GitHub
+CLI, Holt picks up `gh auth token` and you can skip this.
+
+```sh
+holt start --lang python          # starter issues in repositories that merge newcomers
+holt analyze home-assistant/core  # is this one worth your time?
+holt                              # the interactive terminal interface
+```
+
+No AI key is needed. Without one you get the rules-only report: the answer and
+the numbers behind it, free. For a written explanation that quotes the threads
+it relied on, `holt models` sets up a model; Gemini's free tier is the cheapest
+start.
+
+![holt analyze pallets/flask in a terminal: Worth your time, what the evidence shows, where outsider work landed](https://raw.githubusercontent.com/holt-oss/holt/main/assets/cli-analyze.png)
+
+| Command | Purpose |
+|---|---|
+| `holt analyze <owner/repo>` | Assess one repository. `--days N` for the time you have, `--json` for machine-readable output. |
+| `holt start` | Starter issues, across repositories (`--lang`, `--topic`, `--hacktoberfest`) or in one. |
+| `holt compare <repo>…` | Several repositories side by side. |
+| `holt next <repo> --as <login>` | After your first merge: open issues near the files you already changed. |
+| `holt profile`, `holt discover --live` | Say what you want to work on, then search for it. |
+| `holt token`, `holt models` | Save a GitHub token; optionally set up a model. |
+
+**The terminal interface.** Bare `holt` opens it: type a repository, watch the
+run, open any piece of evidence on GitHub with `o`, and come back to past
+assessments. Press `?` on any screen for help.
+
+![The Holt terminal interface showing the assessment for pallets/flask](https://raw.githubusercontent.com/holt-oss/holt/main/assets/tui.png)
+
+[docs/USAGE.md](https://github.com/holt-oss/holt/blob/main/docs/USAGE.md)
+walks through the whole workflow and
+[docs/COMMANDS.md](https://github.com/holt-oss/holt/blob/main/docs/COMMANDS.md)
+lists every flag.
+
+### 3. The browser extension
+
+**Holt for GitHub** adds a small chip next to the repository name on
+github.com (**Holt: Worth your time · 15 of 100 newcomer PRs merged**) and
+marks the issues Holt would pick first. Clicking the chip opens the full
+report. It sends only the `owner/repo` you are looking at, keeps nothing, and
+never writes to GitHub.
+
+![The Holt chip next to a repository name on GitHub, and Holt pick marks on the issue list](https://raw.githubusercontent.com/holt-oss/holt/main/extension/screenshots/desktop-light.png)
+
+It is not on the extension stores yet. To try it, build it and load it
+unpacked in Chrome, Edge, Brave or Firefox:
+[extension/README.md](https://github.com/holt-oss/holt/blob/main/extension/README.md).
+
+## Hacktoberfest
+
+Every October the site has a seasonal page, **[/hacktoberfest](https://githolt.com/hacktoberfest)**:
+repositories taking part that actually merge newcomers' work, with starter
+issues by language, and a few tips so your pull request doesn't get ignored.
+From the command line:
+
+```sh
+holt start --hacktoberfest --lang python
+```
+
+## For maintainers: a README badge
+
+Show newcomers they are welcome. Paste this into your README, with your own
+`owner/repo`:
+
+```markdown
+[![Holt](https://githolt.com/badge/owner/repo.svg)](https://githolt.com/owner/repo)
+```
+
+The badge shows Holt's current answer for your repository and links to the
+report. It updates when the report does; you never have to touch it again.
+
+## How the verdict works
+
+| Answer | Meaning |
+|---|---|
+| **Worth your time** | Outsiders get replies and land real work here, fast enough for the time you have. |
+| **Not worth your time** | The record says a newcomer's week is unlikely to go anywhere here. |
+| **Not enough evidence** | Too little outside activity to call it either way. That is an answer, not an error. |
+
+**Rules decide. AI only explains.** The answer comes from fixed rules applied
+to counted evidence: who tried, who got merged, how fast the first reply came,
+and whether anyone actually reviewed the work. An AI model can add a written
+explanation that quotes the threads it relied on, and every claim it makes is
+checked against the record before you see it. Unsupported claims are dropped.
+The model never chooses the answer.
+[docs/DESIGN.md](https://github.com/holt-oss/holt/blob/main/docs/DESIGN.md)
+has the argument.
+
+## Where it doesn't work
+
+Holt is a filter, not an oracle. Know the limits:
+
+- **It isn't always right.** Open the linked pull requests before you commit
+  a week; the evidence is there so you can check it yourself.
+- **It reads the past.** Repository cultures change, and a quiet month can
+  look worse than it is.
+- **It is about your time, not their quality.** A superb project with a deep
+  review queue can still be a poor place for a first pull request.
+- **Counts, not conversations.** Without a model, Holt can't tell you what a
+  thread said or who was welcoming, only what happened.
+
+Holt started as a benchmarked competition entry; that evaluation is now
+historical research rather than a live product claim.
+[docs/research/EVALUATION.md](https://github.com/holt-oss/holt/blob/main/docs/research/EVALUATION.md)
+has the design and the full numbers, and
+[docs/research/REPRODUCTION.md](https://github.com/holt-oss/holt/blob/main/docs/research/REPRODUCTION.md)
+reproduces them from a clone with no API key, no token and no money.
+
+## The repository
+
+| Path | What |
+|---|---|
+| `src/holt/` | The engine, the CLI and the terminal interface (`holt-cli` on PyPI) |
+| `web/` | The web app |
+| `server/` | The HTTP API the web app calls |
+| `extension/` | The browser extension |
+| `docs/` | Everything else, starting from [docs/README.md](https://github.com/holt-oss/holt/blob/main/docs/README.md) |
+
+## Contributing
+
+Holt is small, and one maintainer runs it. First pull requests are welcome.
+[CONTRIBUTING.md](https://github.com/holt-oss/holt/blob/main/CONTRIBUTING.md)
+starts with a 15-minute path to your first one, and issues labelled
+[good first issue](https://github.com/holt-oss/holt/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+are sized for it. Participation is governed by the
+[Code of Conduct](https://github.com/holt-oss/holt/blob/main/CODE_OF_CONDUCT.md);
+security reports follow
+[SECURITY.md](https://github.com/holt-oss/holt/blob/main/SECURITY.md).
+
+Working on Holt regularly? [docs/DEV-WORKFLOW.md](https://github.com/holt-oss/holt/blob/main/docs/DEV-WORKFLOW.md)
+is the one-page guide: run the web app locally, preview a branch on staging,
+and what CI and deploys expect.
+
+> Holt started as the winner of **Most useful real-world workflow** at the
+> micro1 Frontier Engineering Challenge.
+
+## Licensing
+
+Holt uses two licenses, split by directory:
+
+- **The engine, CLI, terminal interface and browser extension**
+  (`src/holt/`, `extension/`, everything else at the repo root) are
+  [Apache License 2.0](https://github.com/holt-oss/holt/blob/main/LICENSE).
+  Install the CLI from PyPI, embed the engine, or fork it under Apache terms.
+- **The web app and its server** (`web/`, `server/`) are
+  [GNU AGPL-3.0](https://github.com/holt-oss/holt/blob/main/web/LICENSE). If
+  you run a modified version of the web app or server as a network service,
+  the AGPL requires you to make your modified source available to the
+  people using it.
+
+Apache-licensed contributions from before the split remain Apache-2.0 and
+are compatible with the AGPL side, so nothing already in the project needed
+anyone's permission to move. If you're contributing new code, see
+[CONTRIBUTING.md](https://github.com/holt-oss/holt/blob/main/CONTRIBUTING.md#licensing).

holt_cli-0.2.0/README.md

@@ -0,0 +1,217 @@
+# Holt
+
+[![CI](https://github.com/holt-oss/holt/actions/workflows/ci.yml/badge.svg)](https://github.com/holt-oss/holt/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/holt-cli.svg?color=83a9ff)](https://pypi.org/project/holt-cli/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-69c7a6.svg)](https://github.com/holt-oss/holt/blob/main/pyproject.toml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-83a9ff.svg)](https://github.com/holt-oss/holt/blob/main/LICENSE)
+
+**Find an open-source project that will actually merge your first PR.**
+
+Paste a GitHub repository. Holt reads its recent pull requests and tells you,
+in plain English, whether newcomers get replies, get merged, and where their
+work lands. The answer is one of **Worth your time**, **Not worth your time**
+or **Not enough evidence**, with links to the pull requests behind it.
+
+![Holt answering for pallets/flask, then finding starter issues](https://raw.githubusercontent.com/holt-oss/holt/main/assets/demo.gif)
+
+<!-- HOLT_SITE_URL: the product lives at https://githolt.com -->
+**[Try it in your browser](https://githolt.com)** · no install, no
+account · [Install the CLI](#2-the-command-line) ·
+[Get the browser extension](#3-the-browser-extension)
+
+Holt is read-only. It never opens pull requests, posts comments or contacts
+maintainers, on any surface.
+
+## Three ways to use it
+
+### 1. The web app
+
+<!-- HOLT_SITE_URL -->
+Open **<https://githolt.com>** and paste a repository. Or take any GitHub
+link and **swap hub for holt**: `github.com` becomes `githolt.com`, and you
+land on the report.
+
+```text
+https://github.com/home-assistant/core
+https://githolt.com/home-assistant/core
+```
+
+No repository in mind? **Find a project** asks which languages you read and how
+much time you have, then lists welcoming repositories with open starter issues.
+
+<table>
+  <tr>
+    <td><img src="https://raw.githubusercontent.com/holt-oss/holt/main/assets/web-report-light-desktop.jpg" alt="The report for home-assistant/core: Worth your time, with the counts behind it and where to start" width="640"></td>
+    <td><img src="https://raw.githubusercontent.com/holt-oss/holt/main/assets/web-find-dark-phone.jpg" alt="Find a project on a phone: pick languages and time, get welcoming repositories" width="200"></td>
+  </tr>
+</table>
+
+### 2. The command line
+
+The same engine runs on your machine, from PyPI. It needs Python 3.11 or newer;
+use whichever installer you have (all three work in PowerShell too):
+
+```sh
+pipx install holt-cli
+uv tool install holt-cli
+pip install --user holt-cli
+```
+
+Give it a GitHub token once. Holt reads only public data, so
+[create a token](https://github.com/settings/tokens/new?description=holt) with
+every box unticked, then run `holt token` and paste it. If you use the GitHub
+CLI, Holt picks up `gh auth token` and you can skip this.
+
+```sh
+holt start --lang python          # starter issues in repositories that merge newcomers
+holt analyze home-assistant/core  # is this one worth your time?
+holt                              # the interactive terminal interface
+```
+
+No AI key is needed. Without one you get the rules-only report: the answer and
+the numbers behind it, free. For a written explanation that quotes the threads
+it relied on, `holt models` sets up a model; Gemini's free tier is the cheapest
+start.
+
+![holt analyze pallets/flask in a terminal: Worth your time, what the evidence shows, where outsider work landed](https://raw.githubusercontent.com/holt-oss/holt/main/assets/cli-analyze.png)
+
+| Command | Purpose |
+|---|---|
+| `holt analyze <owner/repo>` | Assess one repository. `--days N` for the time you have, `--json` for machine-readable output. |
+| `holt start` | Starter issues, across repositories (`--lang`, `--topic`, `--hacktoberfest`) or in one. |
+| `holt compare <repo>…` | Several repositories side by side. |
+| `holt next <repo> --as <login>` | After your first merge: open issues near the files you already changed. |
+| `holt profile`, `holt discover --live` | Say what you want to work on, then search for it. |
+| `holt token`, `holt models` | Save a GitHub token; optionally set up a model. |
+
+**The terminal interface.** Bare `holt` opens it: type a repository, watch the
+run, open any piece of evidence on GitHub with `o`, and come back to past
+assessments. Press `?` on any screen for help.
+
+![The Holt terminal interface showing the assessment for pallets/flask](https://raw.githubusercontent.com/holt-oss/holt/main/assets/tui.png)
+
+[docs/USAGE.md](https://github.com/holt-oss/holt/blob/main/docs/USAGE.md)
+walks through the whole workflow and
+[docs/COMMANDS.md](https://github.com/holt-oss/holt/blob/main/docs/COMMANDS.md)
+lists every flag.
+
+### 3. The browser extension
+
+**Holt for GitHub** adds a small chip next to the repository name on
+github.com (**Holt: Worth your time · 15 of 100 newcomer PRs merged**) and
+marks the issues Holt would pick first. Clicking the chip opens the full
+report. It sends only the `owner/repo` you are looking at, keeps nothing, and
+never writes to GitHub.
+
+![The Holt chip next to a repository name on GitHub, and Holt pick marks on the issue list](https://raw.githubusercontent.com/holt-oss/holt/main/extension/screenshots/desktop-light.png)
+
+It is not on the extension stores yet. To try it, build it and load it
+unpacked in Chrome, Edge, Brave or Firefox:
+[extension/README.md](https://github.com/holt-oss/holt/blob/main/extension/README.md).
+
+## Hacktoberfest
+
+Every October the site has a seasonal page, **[/hacktoberfest](https://githolt.com/hacktoberfest)**:
+repositories taking part that actually merge newcomers' work, with starter
+issues by language, and a few tips so your pull request doesn't get ignored.
+From the command line:
+
+```sh
+holt start --hacktoberfest --lang python
+```
+
+## For maintainers: a README badge
+
+Show newcomers they are welcome. Paste this into your README, with your own
+`owner/repo`:
+
+```markdown
+[![Holt](https://githolt.com/badge/owner/repo.svg)](https://githolt.com/owner/repo)
+```
+
+The badge shows Holt's current answer for your repository and links to the
+report. It updates when the report does; you never have to touch it again.
+
+## How the verdict works
+
+| Answer | Meaning |
+|---|---|
+| **Worth your time** | Outsiders get replies and land real work here, fast enough for the time you have. |
+| **Not worth your time** | The record says a newcomer's week is unlikely to go anywhere here. |
+| **Not enough evidence** | Too little outside activity to call it either way. That is an answer, not an error. |
+
+**Rules decide. AI only explains.** The answer comes from fixed rules applied
+to counted evidence: who tried, who got merged, how fast the first reply came,
+and whether anyone actually reviewed the work. An AI model can add a written
+explanation that quotes the threads it relied on, and every claim it makes is
+checked against the record before you see it. Unsupported claims are dropped.
+The model never chooses the answer.
+[docs/DESIGN.md](https://github.com/holt-oss/holt/blob/main/docs/DESIGN.md)
+has the argument.
+
+## Where it doesn't work
+
+Holt is a filter, not an oracle. Know the limits:
+
+- **It isn't always right.** Open the linked pull requests before you commit
+  a week; the evidence is there so you can check it yourself.
+- **It reads the past.** Repository cultures change, and a quiet month can
+  look worse than it is.
+- **It is about your time, not their quality.** A superb project with a deep
+  review queue can still be a poor place for a first pull request.
+- **Counts, not conversations.** Without a model, Holt can't tell you what a
+  thread said or who was welcoming, only what happened.
+
+Holt started as a benchmarked competition entry; that evaluation is now
+historical research rather than a live product claim.
+[docs/research/EVALUATION.md](https://github.com/holt-oss/holt/blob/main/docs/research/EVALUATION.md)
+has the design and the full numbers, and
+[docs/research/REPRODUCTION.md](https://github.com/holt-oss/holt/blob/main/docs/research/REPRODUCTION.md)
+reproduces them from a clone with no API key, no token and no money.
+
+## The repository
+
+| Path | What |
+|---|---|
+| `src/holt/` | The engine, the CLI and the terminal interface (`holt-cli` on PyPI) |
+| `web/` | The web app |
+| `server/` | The HTTP API the web app calls |
+| `extension/` | The browser extension |
+| `docs/` | Everything else, starting from [docs/README.md](https://github.com/holt-oss/holt/blob/main/docs/README.md) |
+
+## Contributing
+
+Holt is small, and one maintainer runs it. First pull requests are welcome.
+[CONTRIBUTING.md](https://github.com/holt-oss/holt/blob/main/CONTRIBUTING.md)
+starts with a 15-minute path to your first one, and issues labelled
+[good first issue](https://github.com/holt-oss/holt/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+are sized for it. Participation is governed by the
+[Code of Conduct](https://github.com/holt-oss/holt/blob/main/CODE_OF_CONDUCT.md);
+security reports follow
+[SECURITY.md](https://github.com/holt-oss/holt/blob/main/SECURITY.md).
+
+Working on Holt regularly? [docs/DEV-WORKFLOW.md](https://github.com/holt-oss/holt/blob/main/docs/DEV-WORKFLOW.md)
+is the one-page guide: run the web app locally, preview a branch on staging,
+and what CI and deploys expect.
+
+> Holt started as the winner of **Most useful real-world workflow** at the
+> micro1 Frontier Engineering Challenge.
+
+## Licensing
+
+Holt uses two licenses, split by directory:
+
+- **The engine, CLI, terminal interface and browser extension**
+  (`src/holt/`, `extension/`, everything else at the repo root) are
+  [Apache License 2.0](https://github.com/holt-oss/holt/blob/main/LICENSE).
+  Install the CLI from PyPI, embed the engine, or fork it under Apache terms.
+- **The web app and its server** (`web/`, `server/`) are
+  [GNU AGPL-3.0](https://github.com/holt-oss/holt/blob/main/web/LICENSE). If
+  you run a modified version of the web app or server as a network service,
+  the AGPL requires you to make your modified source available to the
+  people using it.
+
+Apache-licensed contributions from before the split remain Apache-2.0 and
+are compatible with the AGPL side, so nothing already in the project needed
+anyone's permission to move. If you're contributing new code, see
+[CONTRIBUTING.md](https://github.com/holt-oss/holt/blob/main/CONTRIBUTING.md#licensing).

{holt_cli-0.1.0 → holt_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "holt-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Evidence-backed assessment of whether a GitHub repository is a viable opportunity for an external contributor."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -39,7 +39,7 @@ dependencies = [
 holt = "holt.cli:main"
 
 [project.urls]
-Homepage = "https://github.com/holt-oss/holt"
+Homepage = "https://githolt.com"
 Documentation = "https://github.com/holt-oss/holt/tree/main/docs"
 Repository = "https://github.com/holt-oss/holt.git"
 Issues = "https://github.com/holt-oss/holt/issues"
@@ -47,7 +47,17 @@ Changelog = "https://github.com/holt-oss/holt/blob/main/CHANGELOG.md"
 Security = "https://github.com/holt-oss/holt/security/policy"
 
 [dependency-groups]
-dev = ["pytest>=8.0"]
+# holt-server is the web API in server/. It rides in the dev group so one
+# `uv sync` gives a working tree for both, and its tests run with the rest.
+# Dependency groups are never published, so the PyPI package is unaffected.
+# pytest-xdist runs the suite across cores: `uv run pytest -n auto` (CI does).
+dev = ["pytest>=8.0", "pytest-xdist>=3.8", "holt-server"]
+
+[tool.uv.workspace]
+members = ["server"]
+
+[tool.uv.sources]
+holt-server = { workspace = true }
 
 [build-system]
 requires = ["hatchling"]
@@ -63,6 +73,30 @@ packages = ["src/holt"]
 only-include = ["src/holt"]
 
 [tool.pytest.ini_options]
-testpaths = ["tests", "eval"]
+testpaths = ["tests", "eval", "server/tests"]
 # eval/ lives at the repo root, outside the installed src/holt package.
 pythonpath = ["."]
+
+[tool.ruff]
+target-version = "py311"
+extend-exclude = ["fixtures", "trajectories", "web", "extension", "e2e", "website"]
+
+[tool.ruff.lint]
+# Ruff's classic core set: syntax errors, undefined or unused names, and a few
+# statement-level mistakes. Widen it one rule family at a time, fixing as you go.
+select = ["E4", "E7", "E9", "F"]
+
+[tool.ruff.lint.per-file-ignores]
+# eval/ and scripts/ are frozen research material from the competition.
+"eval/**" = ["E7", "F541", "F401", "F841"]
+"scripts/**" = ["E741"]
+# Baseline: findings present when ruff was introduced. Each is a follow-up;
+# remove the entry once the file is clean.
+"src/holt/discover.py" = ["F841"]
+"src/holt/tui/screens/assessment.py" = ["F541"]
+"src/holt/tui/screens/models.py" = ["F401"]
+"tests/test_discover.py" = ["F401"]
+"tests/test_evidence_bounds.py" = ["F401", "F811"]
+"tests/test_models.py" = ["F401"]
+"tests/test_tui_discovery.py" = ["F401"]
+"tests/test_tui_observe.py" = ["F401", "E402"]

holt_cli-0.2.0/src/holt/agent/asks.py

@@ -0,0 +1,73 @@
+"""What a project asks of a contributor before it will take a pull request.
+
+Read from evidence Holt already has, and only where it is unambiguous:
+
+- a CLA (Contributor License Agreement): a CLA bot commented on outside pull
+  requests in the sample. Not from CONTRIBUTING: free-programming-books has a
+  "Contributor License Agreement" heading that only means "you agree to the
+  licence", with nothing to sign;
+- a DCO sign-off: CONTRIBUTING names the "Developer Certificate of Origin";
+- an issue first: CONTRIBUTING says, in so many words, to open an issue or
+  discuss the change before sending a pull request.
+
+These never touch the verdict. They are advice for the next step, and each
+one links to where it was read so the reader can check it. Where nothing is
+found, nothing is said: the absence of a match is not a claim that the project
+asks for nothing.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from holt.types import EvidenceRecord
+
+# CLA bots seen on the golden set: linux-foundation-easycla, google-cla,
+# meta-cla, python-cla-bot, CLAassistant. Whole-word "cla", so `cclauss` and
+# `clarfonthey` are people.
+_CLA_BOT = re.compile(r"easycla|claassistant|cla-assistant|(?:^|[-_])cla(?:[-_](?:bot|checker|assistant))?(?:\[bot\])?$",
+                      re.I)
+_DCO_DOC = re.compile(r"developer\s+certificate\s+of\s+origin", re.I)
+_ISSUE_FIRST_DOC = re.compile(
+    r"\b(?:open|file|create|raise)\s+an\s+issue\s+first\b"
+    r"|\bdiscuss\s+(?:it|your\s+(?:idea|change|proposal)|the\s+change|this)\s+first\b"
+    r"|\bbefore\s+(?:opening|submitting|sending|starting)\s+(?:a|your|any)\s+(?:pull\s+request|PR)"
+    r"[^.\n]{0,40}?\b(?:open|file|create)\s+an\s+issue\b",
+    re.I,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Ask:
+    code: str  # "cla", "dco" or "issue_first"
+    url: str  # where it was read: a bot's comment, or CONTRIBUTING
+
+
+def is_cla_bot(login: str | None) -> bool:
+    return bool(login) and bool(_CLA_BOT.search(login or ""))
+
+
+def read(records: Iterable[EvidenceRecord], outsider_keys: set[str] | None = None) -> list[Ask]:
+    """Every ask found, CLA first. `outsider_keys` limits the CLA-bot check to
+    those pull requests (a bot greeting staff says nothing about outsiders)."""
+    records = list(records)
+    found: dict[str, Ask] = {}
+    for r in records:
+        if ":comment:" not in r.evidence_id and ":review:" not in r.evidence_id:
+            continue
+        key = ":".join(r.evidence_id.split(":")[:2])
+        if outsider_keys is not None and key not in outsider_keys:
+            continue
+        if is_cla_bot(r.payload.get("author")) and r.url:
+            found.setdefault("cla", Ask("cla", r.url))
+            break
+    doc = next((r for r in records if r.evidence_id.endswith(":contributing")), None)
+    text = (doc.payload.get("text") or "") if doc is not None else ""
+    if doc is not None and doc.url and text:
+        if _DCO_DOC.search(text):
+            found.setdefault("dco", Ask("dco", doc.url))
+        if _ISSUE_FIRST_DOC.search(text):
+            found.setdefault("issue_first", Ask("issue_first", doc.url))
+    return [found[c] for c in ("cla", "dco", "issue_first") if c in found]