Improve open source project readiness

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Report a reproducible qalmsw problem
+title: ""
+labels: bug
+assignees: ""
+---
+
+## What happened?
+
+Describe the unexpected behavior.
+
+## Reproduction
+
+1. qalmsw version or commit:
+2. Python version:
+3. Command:
+4. Minimal `.tex` / `.bib` input:
+
+```tex
+
+```
+
+## Expected behavior
+
+Describe what should have happened.
+
+## Output
+
+Paste the relevant terminal output or JSON report.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Propose a checker, output format, backend, or workflow improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Use case
+
+Who needs this, and what paper-writing or review workflow would it improve?
+
+## Proposed behavior
+
+Describe the command, checker, report field, or integration you want.
+
+## Alternatives
+
+Describe any current workaround or related tool.
+
+## Implementation notes
+
+Share links, examples, or constraints that would help a maintainer scope the work.

.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Summary
+
+- 
+
+## Testing
+
+- [ ] `ruff check .`
+- [ ] `pytest -q`
+
+## Notes
+
+Mention any behavior changes, network calls, or LLM assumptions reviewers should verify.

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package
+        run: python -m pip install -U pip && python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest -q

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable project changes should be recorded here before a release is tagged.
+
+## Unreleased
+
+- Added CI configuration for linting and tests on supported Python versions.
+- Added open-source project files: license, contributing guide, security policy,
+  code of conduct, issue templates, and pull request template.
+- Improved JSON output so CI consumers receive one parseable document for single
+  or multi-file checks.
+- Fixed claims-checker retrieval backend selection so runtime backend switches
+  affect new `ClaimsChecker` instances.

CLAUDE.md

@@ -75,5 +75,5 @@ When adding a checker: drop a file into `src/qalmsw/checkers/`, register it in `
 ### What's intentionally *not* here
 
 - No LLM-assisted citation verification (does this citation actually support this claim?). That's the `claims` checker's territory.
-- Retrieval uses **Google Scholar** by default (`src/qalmsw/retrieval/scholar.py` via `scholarly`). **Scraping-based**; rate-limits and CAPTCHAs are expected under sustained use. Keep it for personal/interactive runs; fall back to Semantic Scholar or arXiv when CI-scale reliability matters. Backend switching is done at runtime via `qalmsw.retrieval.set_backend()`.
-- No SARIF/JSON report formats yet — only `report/text.py`. The `Finding` pydantic model is the serialization seam for future support.
+- Retrieval uses **Semantic Scholar** by default (`src/qalmsw/retrieval/semantic_scholar.py`). Google Scholar remains available as an opt-in scraping backend and may hit rate limits or CAPTCHAs. Backend switching is done at runtime via `qalmsw.retrieval.set_backend()`.
+- JSON report output exists in `report/json.py`; SARIF is still future work. The `Finding` pydantic model is the serialization seam for future output formats.

CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+qalmsw should be a practical, respectful place to improve tooling for scientific
+writing quality.
+
+## Expected behavior
+
+- Be direct and constructive when discussing bugs, limitations, and research claims.
+- Focus criticism on code, data, documentation, and reproducible behavior.
+- Respect differences in experience level, institution, geography, language, and
+  research area.
+- Assume public issues and pull requests are archived and searchable.
+
+## Unacceptable behavior
+
+- Harassment, threats, or personal attacks.
+- Dismissive comments about a contributor's identity, background, or affiliation.
+- Publishing private information without permission.
+- Repeated off-topic or bad-faith disruption.
+
+## Enforcement
+
+Maintainers may edit, hide, or remove comments; close issues; reject pull requests;
+or block participants when necessary to keep the project usable. Report conduct
+concerns through the maintainer contact listed on the GitHub repository profile.

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to qalmsw
+
+qalmsw is a Python CLI for checking scientific LaTeX manuscripts before submission.
+Contributions are welcome when they keep the tool reliable for local, privacy-preserving
+review workflows.
+
+## Development setup
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest -q
+```
+
+Tests use fake LLM clients and should not require a running llama.cpp server or live
+network access. If a test needs paper metadata, stub the retrieval function.
+
+## Project constraints
+
+- The default LLM backend is a local llama.cpp server using an OpenAI-compatible API.
+- Do not require hosted LLM providers for core checks.
+- Deterministic checks should run before LLM-backed checks and should work in CI.
+- Checkers should return `Finding` objects instead of printing directly.
+- Do not ask the LLM for line numbers. Ask for excerpts and locate them in source.
+- Keep output stable enough for CI and editor integrations.
+
+## Adding a checker
+
+1. Add the checker in `src/qalmsw/checkers/`.
+2. Register it in `src/qalmsw/checkers/__init__.py`.
+3. Wire it into `src/qalmsw/cli.py`.
+4. Add focused tests under `tests/` with a fake LLM or stubbed retrieval backend.
+5. Document the checker in `README.md`.
+
+## Pull requests
+
+Before opening a PR, run:
+
+```bash
+ruff check .
+pytest -q
+```
+
+For user-visible behavior changes, include a short example command and explain the
+expected report output.

LICENSE

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

README.md

@@ -1,7 +1,22 @@
 # qalmsw
 
-Automated QA for scientific LaTeX writing, powered by a local LLM (llama.cpp server).
-Catches the artefacts that get you a 1-year arXiv ban - before you submit.
+[![CI](https://github.com/pebaryan/qalmsw/actions/workflows/ci.yml/badge.svg)](https://github.com/pebaryan/qalmsw/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Local-first automated QA for scientific LaTeX writing, powered by a local LLM
+through a llama.cpp OpenAI-compatible server.
+
+qalmsw catches high-risk artifacts before submission: LLM meta-comments,
+placeholder data, hallucinated references, missing figures, citation mistakes,
+and claim/reference mismatches. Deterministic checks run without an LLM, while
+grammar, math, reviewer, and claims checks are opt-in parts of a local review
+workflow.
+
+## Status
+
+Pre-1.0 and actively maintained. The package has a Python CLI, focused tests,
+JSON output for CI integrations, and a local-first architecture. See
+[ROADMAP.md](ROADMAP.md) for the maintainer plan and Codex/API credit use case.
 
 ## What it catches
 
@@ -24,12 +39,13 @@ Code of Conduct penalises:
 | **Substantive reviewer concerns** | `reviewer` checker - per-section LLM critique |
 | **Unsupported claims** *(opt-in)* | `claims` checker - checks each \cite-backed claim against the cited paper's abstract |
 
-The first three rows are the ones that get you banned. qalmsw catches all of them.
+The first three rows are the highest-risk categories. qalmsw catches all of them
+with deterministic checks, so they can run in CI without LLM cost.
 
 ## Quick start
 
 ```bash
-pip install -e '.[dev]'
+pip install -e ".[dev]"
 
 # Start llama.cpp server separately, e.g.
 #   ./llama-server -m model.gguf -c 8192 --port 8080
@@ -40,7 +56,7 @@ qalmsw check --skip-math --skip-grammar --skip-reviewer paper.tex
 qalmsw check --skip-grammar path/to/paper.tex              # reviewer + citations + artifacts + references
 qalmsw check -j 4 path/to/paper.tex                        # fan out 4 parallel LLM calls
 qalmsw check --bib refs.bib path/to/paper.tex              # override .bib auto-discovery
-qalmsw check --json paper.tex                              # JSON output for CI
+qalmsw check --json paper.tex                              # parseable JSON output for CI
 qalmsw check ch1.tex ch2.tex ch3.tex                       # batch mode: check multiple files
 qalmsw check "src/**/*.tex"                                # glob expansion
 
@@ -121,3 +137,12 @@ report.render_findings   # rich-formatted terminal output (or --json for CI)
 Deterministic checkers (artifacts, figures, images, citations) run first and always.
 LLM checkers (grammar, math, reviewer, claims) run only when a server is available.
 Network checkers (references, claims) make live API calls.
+
+## Open Source
+
+- License: [MIT](LICENSE)
+- Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Security policy: [SECURITY.md](SECURITY.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- Roadmap and funding plan: [ROADMAP.md](ROADMAP.md)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)

ROADMAP.md

@@ -0,0 +1,51 @@
+# Roadmap
+
+qalmsw is focused on pre-submission QA for scientific LaTeX manuscripts. The
+near-term goal is to make the deterministic checks strong enough for CI, and the
+LLM-backed checks useful enough for private local review before authors submit.
+
+## Current priorities
+
+- Keep deterministic artifact, citation, image, and figure/table checks fast and
+  suitable for CI.
+- Improve JSON output and add SARIF output so editors, GitHub Actions, and review
+  tools can annotate exact manuscript lines.
+- Expand reference verification beyond arXiv and DOI checks with better fallbacks
+  for Semantic Scholar, Crossref, and OpenAlex.
+- Build a small public regression corpus of synthetic LaTeX manuscripts that cover
+  hallucinated references, placeholder content, missing figures, and unsupported
+  claims.
+- Publish reproducible releases with changelogs and pinned test results.
+
+## Codex/API Credit Plan
+
+OpenAI's Codex open source programs ask how API credits would support project work.
+For qalmsw, credits would be used for bounded maintainer automation and evaluation,
+not for sending users' manuscripts to hosted services by default.
+
+Planned uses:
+
+- Generate and review checker test cases from synthetic LaTeX fixtures.
+- Compare checker output across models and prompts before releases.
+- Prototype SARIF/GitHub Actions annotations for manuscript review workflows.
+- Triage issues and draft pull-request reviews for community contributions.
+- Build release notes and migration notes from merged changes.
+
+User-facing checks should continue to support local llama.cpp by default. Hosted API
+usage belongs in maintainer workflows, opt-in experiments, or clearly documented
+integrations.
+
+## Funding Application Draft
+
+Short project description:
+
+> qalmsw is an open-source Python CLI that checks scientific LaTeX manuscripts for
+> LLM artifacts, placeholder text, hallucinated references, missing figures, citation
+> problems, and unsupported claims before submission.
+
+How credits would be used:
+
+> API credits would fund maintainer automation: synthetic LaTeX regression fixtures,
+> checker evaluation, issue/PR triage, release-note drafting, and CI annotation
+> prototypes. The user CLI remains local-first with llama.cpp; hosted API use is for
+> project maintenance and opt-in integrations.

SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Supported versions
+
+qalmsw is pre-1.0. Security fixes are applied to the `main` branch until formal
+releases are published.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a vulnerability.
+
+Report security-sensitive problems by emailing the maintainer listed on the GitHub
+repository profile, or by opening a private GitHub security advisory if that is
+enabled for the repository.
+
+Useful details include:
+
+- A minimal input file or command that triggers the issue.
+- Whether the issue requires network retrieval or an LLM server.
+- Any file paths, URLs, or environment variables involved.
+
+## Security model
+
+qalmsw reads LaTeX and BibTeX files supplied by the user and may call local LLM and
+metadata retrieval services. It should not execute LaTeX, shell commands from input,
+or arbitrary code embedded in a manuscript.
+
+The default LLM endpoint is a local llama.cpp server. Users who configure another
+OpenAI-compatible endpoint are responsible for that provider's data handling terms.

pyproject.toml

@@ -7,7 +7,20 @@ name = "qalmsw"
 version = "0.0.1"
 description = "Automated QA for scientific LaTeX writing using local LLMs"
 readme = "README.md"
+license = { file = "LICENSE" }
 requires-python = ">=3.11"
+keywords = ["latex", "llm", "scientific-writing", "citations", "quality-assurance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Text Processing :: Markup :: LaTeX",
+]
 dependencies = [
     "pylatexenc>=2.10",
     "openai>=1.40",
@@ -28,6 +41,11 @@ dev = [
 [project.scripts]
 qalmsw = "qalmsw.cli:app"
 
+[project.urls]
+Homepage = "https://github.com/pebaryan/qalmsw"
+Repository = "https://github.com/pebaryan/qalmsw"
+Issues = "https://github.com/pebaryan/qalmsw/issues"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/qalmsw"]
 
@@ -38,6 +56,9 @@ target-version = "py311"
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM"]
 
+[tool.ruff.lint.per-file-ignores]
+"src/qalmsw/cli.py" = ["B008"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests", "research/tests"]
 pythonpath = ["."]

src/qalmsw/checkers/claims.py

@@ -14,7 +14,7 @@ Pipeline for each paragraph that contains a ``\\cite{}``:
 
 Design notes:
 - Scholar is injected as a ``Callable[[str], ScholarResult | None]`` so tests can stub
-  it without hitting the network. Default: :func:`qalmsw.retrieval.search_by_title`.
+  it without hitting the network. Default: the active ``qalmsw.retrieval`` backend.
 - Scholar lookups are per-run-cached by bib key. Duplicate ``\\cite`` of the same paper
   costs one network call, not N.
 - We never raise on Scholar failures — they become ``info`` findings so the rest of
@@ -25,14 +25,16 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any
 
+import qalmsw.retrieval as retrieval
 from qalmsw.bib import BibEntry
 from qalmsw.checkers.base import Finding, Severity
 from qalmsw.document import Document
 from qalmsw.llm import LLMClient
 from qalmsw.parse import Paragraph, scan_citations
-from qalmsw.retrieval import ScholarResult, search_by_title
+from qalmsw.retrieval import ScholarResult
 
-_EXTRACT_SYSTEM_PROMPT = """You are extracting citation-backed claims from a paragraph of a scientific paper.
+_EXTRACT_SYSTEM_PROMPT = """You are extracting citation-backed claims from a paragraph
+of a scientific paper.
 
 A "claim" is a factual or empirical assertion that is explicitly attributed to one or \
 more citations. Do NOT include statements that don't carry a citation.
@@ -84,11 +86,11 @@ class ClaimsChecker:
         self,
         llm: LLMClient,
         bib_entries: list[BibEntry],
-        search: SearchFn = search_by_title,
+        search: SearchFn | None = None,
     ) -> None:
         self._llm = llm
         self._bib_by_key = {e.key: e for e in bib_entries}
-        self._search = search
+        self._search = search or retrieval.search_by_title
         self._abstract_cache: dict[str, ScholarResult | None] = {}
 
     def check(self, doc: Document) -> list[Finding]:
@@ -103,7 +105,10 @@ class ClaimsChecker:
         return findings
 
     def _extract_claims(self, para: Paragraph, cite_keys: list[str]) -> list[dict[str, Any]]:
-        prompt = f"Cite keys present: {', '.join(sorted(set(cite_keys)))}\n\nParagraph:\n{para.text}"
+        prompt = (
+            f"Cite keys present: {', '.join(sorted(set(cite_keys)))}\n\n"
+            f"Paragraph:\n{para.text}"
+        )
         result = self._llm.complete_json(_EXTRACT_SYSTEM_PROMPT, prompt)
         raw_claims = result.get("claims", [])
         return [c for c in raw_claims if isinstance(c, dict) and c.get("claim")]
@@ -119,7 +124,13 @@ class ClaimsChecker:
     def _verify_single(self, para: Paragraph, claim_text: str, cite_key: str) -> list[Finding]:
         entry = self._bib_by_key.get(cite_key)
         if entry is None:
-            return [_finding(para, Severity.info, f"Unknown cite key '{cite_key}' in claim: {claim_text}")]
+            return [
+                _finding(
+                    para,
+                    Severity.info,
+                    f"Unknown cite key '{cite_key}' in claim: {claim_text}",
+                )
+            ]
         if not entry.title:
             return [
                 _finding(
@@ -134,7 +145,8 @@ class ClaimsChecker:
                 _finding(
                     para,
                     Severity.info,
-                    f"Could not retrieve abstract for '{cite_key}' ({entry.title!r}) — claim unverified.",
+                    f"Could not retrieve abstract for '{cite_key}' "
+                    f"({entry.title!r}) — claim unverified.",
                 )
             ]
         if not abstract_result.abstract:
@@ -147,7 +159,11 @@ class ClaimsChecker:
             ]
         verdict_raw = self._llm.complete_json(
             _JUDGE_SYSTEM_PROMPT,
-            f"Claim: {claim_text}\n\nCited paper title: {abstract_result.title}\n\nAbstract: {abstract_result.abstract}",
+            (
+                f"Claim: {claim_text}\n\n"
+                f"Cited paper title: {abstract_result.title}\n\n"
+                f"Abstract: {abstract_result.abstract}"
+            ),
         )
         verdict = str(verdict_raw.get("verdict", "unclear")).strip().lower()
         rationale = str(verdict_raw.get("rationale", "")).strip()

src/qalmsw/cli.py

@@ -25,7 +25,7 @@ from qalmsw.checkers import (
 from qalmsw.document import Document
 from qalmsw.llm import LlamaCppClient
 from qalmsw.parse import scan_bib_resources
-from qalmsw.report import render_findings, render_findings_json
+from qalmsw.report import render_batch_findings_json, render_findings
 from qalmsw.retrieval import search_by_title, set_backend
 
 app = typer.Typer(no_args_is_help=True, add_completion=False)
@@ -88,10 +88,11 @@ def check(
     # Select retrieval backend for claims checker
     set_backend(retrieval)
 
-    if len(resolved) > 1:
+    if len(resolved) > 1 and not json_output:
         console.print(f"[dim]{len(resolved)} file(s) to check[/]")
 
     any_errors = False
+    json_results: list[tuple[Path, list[Finding]]] = []
     for file in resolved:
         if not json_output:
             if len(resolved) > 1:
@@ -99,7 +100,7 @@ def check(
             else:
                 console.print(f"[bold]{file}[/]")
 
-        has_errors = _check_single(
+        has_errors, findings = _check_single(
             file,
             bib,
             skip_grammar,
@@ -113,7 +114,11 @@ def check(
         )
         if has_errors:
             any_errors = True
+        if json_output:
+            json_results.append((file, findings))
 
+    if json_output:
+        console.file.write(render_batch_findings_json(json_results) + "\n")
     raise typer.Exit(code=1 if any_errors else 0)
 
 
@@ -128,14 +133,15 @@ def _check_single(
     base_url: str | None,
     model: str | None,
     json_output: bool,
-) -> bool:
-    """Run checks on a single file. Returns True if any errors found."""
+) -> tuple[bool, list[Finding]]:
+    """Run checks on a single file. Returns error state plus all findings."""
     doc = Document.load(file)
-    console.print(f"[dim]{len(doc.paragraphs)} paragraph(s) parsed[/]")
+    if not json_output:
+        console.print(f"[dim]{len(doc.paragraphs)} paragraph(s) parsed[/]")
 
-    bib_paths = list(bib) if bib else _discover_bib_files(doc)
+    bib_paths = list(bib) if bib else _discover_bib_files(doc, quiet=json_output)
     bib_entries = _load_bib_entries(bib_paths)
-    if bib_paths:
+    if bib_paths and not json_output:
         console.print(f"[dim]{len(bib_entries)} bib entries from {len(bib_paths)} file(s)[/]")
     if not bib_entries:
         inline = extract_inline_bibitems(
@@ -143,11 +149,12 @@ def _check_single(
         )
         if inline:
             bib_entries = inline
-            console.print(
-                f"[dim]{len(inline)} bib entries from inline "
-                f"\\begin{{thebibliography}}[/]"
-            )
-        else:
+            if not json_output:
+                console.print(
+                    f"[dim]{len(inline)} bib entries from inline "
+                    f"\\begin{{thebibliography}}[/]"
+                )
+        elif not json_output:
             console.print(
                 "[yellow]warning[/]: no bib entries found (no --bib, no \\bibliography{}, "
                 "no inline \\begin{thebibliography}); citation checks will be limited."
@@ -176,12 +183,10 @@ def _check_single(
     for c in checkers:
         findings.extend(c.check(doc))
 
-    if json_output:
-        console.print(render_findings_json(file, findings))
-    else:
+    if not json_output:
         render_findings(console, file, findings)
 
-    return any(f.severity.value == "error" for f in findings)
+    return any(f.severity.value == "error" for f in findings), findings
 
 
 @app.command()
@@ -220,7 +225,7 @@ def _resolve_files(paths: list[Path]) -> list[Path]:
     return resolved
 
 
-def _discover_bib_files(doc: Document) -> list[Path]:
+def _discover_bib_files(doc: Document, quiet: bool = False) -> list[Path]:
     names = scan_bib_resources(doc.source)
     base_dir = doc.path.parent
     resolved: list[Path] = []
@@ -228,7 +233,7 @@ def _discover_bib_files(doc: Document) -> list[Path]:
         candidate = base_dir / (name if name.endswith(".bib") else f"{name}.bib")
         if candidate.exists():
             resolved.append(candidate)
-        else:
+        elif not quiet:
             console.print(f"[yellow]warning[/]: referenced bib file not found: {candidate}")
     return resolved
 

src/qalmsw/llm/__init__.py

@@ -1,3 +1,3 @@
-from qalmsw.llm.client import LLMClient, LlamaCppClient
+from qalmsw.llm.client import LlamaCppClient, LLMClient
 
 __all__ = ["LLMClient", "LlamaCppClient"]

src/qalmsw/report/__init__.py

@@ -1,4 +1,4 @@
-from qalmsw.report.json import render_findings_json
+from qalmsw.report.json import render_batch_findings_json, render_findings_json
 from qalmsw.report.text import render_findings
 
-__all__ = ["render_findings", "render_findings_json"]
+__all__ = ["render_batch_findings_json", "render_findings", "render_findings_json"]

src/qalmsw/report/json.py

@@ -8,6 +8,20 @@ from typing import Any
 from qalmsw.checkers import Finding
 
 
+def findings_payload(file: Path, findings: list[Finding]) -> dict[str, Any]:
+    """Return the serializable JSON payload for one checked file."""
+    by_severity: dict[str, int] = {}
+    for f in findings:
+        by_severity[f.severity.value] = by_severity.get(f.severity.value, 0) + 1
+
+    return {
+        "file": str(file),
+        "total": len(findings),
+        "by_severity": by_severity,
+        "findings": [_finding_dict(f) for f in findings],
+    }
+
+
 def render_findings_json(file: Path, findings: list[Finding]) -> str:
     """Return findings as a JSON string, one object with file info and results list.
 
@@ -19,15 +33,30 @@ def render_findings_json(file: Path, findings: list[Finding]) -> str:
       "findings": [ ... Finding.dict() ... ]
     }
     """
+    return json.dumps(findings_payload(file, findings), indent=2, default=str)
+
+
+def render_batch_findings_json(results: list[tuple[Path, list[Finding]]]) -> str:
+    """Return parseable JSON for one or more checked files.
+
+    Single-file output preserves the original object shape. Multi-file output wraps
+    per-file payloads in a top-level summary object.
+    """
+    if len(results) == 1:
+        file, findings = results[0]
+        return render_findings_json(file, findings)
+
+    files = [findings_payload(file, findings) for file, findings in results]
     by_severity: dict[str, int] = {}
-    for f in findings:
-        by_severity[f.severity.value] = by_severity.get(f.severity.value, 0) + 1
+    for file_payload in files:
+        for severity, count in file_payload["by_severity"].items():
+            by_severity[severity] = by_severity.get(severity, 0) + count
 
-    payload: dict[str, Any] = {
-        "file": str(file),
-        "total": len(findings),
+    payload = {
+        "total_files": len(results),
+        "total": sum(file_payload["total"] for file_payload in files),
         "by_severity": by_severity,
-        "findings": [_finding_dict(f) for f in findings],
+        "files": files,
     }
     return json.dumps(payload, indent=2, default=str)
 

src/qalmsw/retrieval/__init__.py

@@ -14,8 +14,9 @@ __all__ = ["ScholarResult", "search_by_title", "set_backend"]
 def set_backend(name: str) -> None:
     """Switch the active retrieval backend at runtime.
 
-    This patches the module-level ``search_by_title`` so existing imports
-    like ``from qalmsw.retrieval import search_by_title`` pick up the change.
+    This patches the module-level ``search_by_title``. Code that needs runtime
+    switching should resolve ``qalmsw.retrieval.search_by_title`` after calling
+    this function instead of keeping an earlier direct function import.
 
     Parameters
     ----------

tests/test_claims.py

@@ -44,9 +44,12 @@ def test_supports_verdict_produces_no_finding():
         extract=[{"claims": [{"claim": "LLMs are powerful", "cite_keys": ["foo"]}]}],
         judge=[{"verdict": "supports", "rationale": "abstract confirms"}],
     )
-    findings = ClaimsChecker(llm, [_entry("foo", "Big LLMs")], search=_stub_search("Big LLMs")).check(
-        _doc([para])
+    checker = ClaimsChecker(
+        llm,
+        [_entry("foo", "Big LLMs")],
+        search=_stub_search("Big LLMs"),
     )
+    findings = checker.check(_doc([para]))
     assert findings == []
 
 
@@ -56,7 +59,8 @@ def test_contradicts_verdict_produces_error_finding():
         extract=[{"claims": [{"claim": "X always works", "cite_keys": ["foo"]}]}],
         judge=[{"verdict": "contradicts", "rationale": "abstract says otherwise"}],
     )
-    findings = ClaimsChecker(llm, [_entry("foo")], search=_stub_search("A Paper")).check(_doc([para]))
+    checker = ClaimsChecker(llm, [_entry("foo")], search=_stub_search("A Paper"))
+    findings = checker.check(_doc([para]))
     assert len(findings) == 1
     f = findings[0]
     assert f.checker == "claims"
@@ -152,3 +156,24 @@ def test_abstract_is_cached_per_bib_key():
 
     ClaimsChecker(llm, [_entry("foo")], search=counting_search).check(_doc([para1, para2]))
     assert call_count["n"] == 1
+
+
+def test_default_search_uses_active_retrieval_backend(monkeypatch):
+    """ClaimsChecker should pick up runtime backend switches by default."""
+    import qalmsw.retrieval as retrieval
+
+    para = Paragraph(text="LLMs are useful \\cite{foo}.", start_line=1, end_line=1)
+    llm = ScriptedLLM(
+        extract=[{"claims": [{"claim": "LLMs are useful", "cite_keys": ["foo"]}]}],
+        judge=[{"verdict": "supports", "rationale": "abstract confirms"}],
+    )
+    calls: list[str] = []
+
+    def active_search(title: str) -> ScholarResult | None:
+        calls.append(title)
+        return ScholarResult(title=title, authors=[], year=None, abstract="Useful.", url=None)
+
+    monkeypatch.setattr(retrieval, "search_by_title", active_search)
+    ClaimsChecker(llm, [_entry("foo", "Active Backend")]).check(_doc([para]))
+
+    assert calls == ["Active Backend"]

tests/test_cli.py

@@ -1,10 +1,16 @@
 """Tests for CLI batch mode and retrieval backend switching."""
+import json
 from pathlib import Path
 
+from typer.testing import CliRunner
+
+from qalmsw.cli import app
 from qalmsw.retrieval import search_by_title, set_backend
 from qalmsw.retrieval.scholar import search_by_title as gs_search
 from qalmsw.retrieval.semantic_scholar import search_by_title as ss_search
 
+runner = CliRunner()
+
 
 def test_default_backend_is_semantic_scholar():
     """Module-level search_by_title should point to Semantic Scholar by default."""
@@ -66,3 +72,55 @@ def test_resolve_files_no_match(tmp_path: Path):
     from qalmsw.cli import _resolve_files
     resolved = _resolve_files([tmp_path / "nonexistent*.tex"])
     assert resolved == []
+
+
+def test_json_output_is_parseable_without_status_lines(tmp_path: Path):
+    """--json should emit only JSON so CI tools can parse stdout."""
+    tex = tmp_path / "paper.tex"
+    tex.write_text(r"\documentclass{article}\begin{document}Plain text.\end{document}")
+
+    result = runner.invoke(
+        app,
+        [
+            "check",
+            "--skip-grammar",
+            "--skip-math",
+            "--skip-reviewer",
+            "--json",
+            str(tex),
+        ],
+    )
+
+    assert result.exit_code == 0
+    payload = json.loads(result.stdout)
+    assert payload["file"] == str(tex)
+    assert payload["findings"] == []
+
+
+def test_json_output_batches_multiple_files(tmp_path: Path):
+    """Multi-file --json should still be one parseable JSON document."""
+    tex1 = tmp_path / "a.tex"
+    tex2 = tmp_path / "b.tex"
+    tex1.write_text(r"\documentclass{article}\begin{document}A.\end{document}")
+    tex2.write_text(r"\documentclass{article}\begin{document}B.\end{document}")
+
+    result = runner.invoke(
+        app,
+        [
+            "check",
+            "--skip-grammar",
+            "--skip-math",
+            "--skip-reviewer",
+            "--json",
+            str(tex1),
+            str(tex2),
+        ],
+    )
+
+    assert result.exit_code == 0
+    payload = json.loads(result.stdout)
+    assert payload["total_files"] == 2
+    assert [file_payload["file"] for file_payload in payload["files"]] == [
+        str(tex1),
+        str(tex2),
+    ]