parla 0.0.1__tar.gz

parla-0.0.1/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 ptonso
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

parla-0.0.1/MANIFEST.in

@@ -0,0 +1,2 @@
+graft tests
+global-exclude __pycache__ *.py[cod]

parla-0.0.1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: parla
+Version: 0.0.1
+Summary: Agent-first tool for writing papers, slides, posts and diagrams in their final format, guided by the author's guides and corrections.
+Author: ptonso
+License-Expression: Apache-2.0
+Keywords: latex,agent,writing,docker,pdf
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: pdf
+Requires-Dist: pymupdf>=1.24.0; extra == "pdf"
+Requires-Dist: pymupdf4llm>=0.3.0; extra == "pdf"
+Provides-Extra: svg
+Requires-Dist: fonttools>=4.40; extra == "svg"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.7; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Dynamic: license-file
+
+# parla
+
+`parla` lets a coding agent write papers, CVs, talks, posts and diagrams in your own voice.
+
+It keeps your long-term memory of how you write, loads the part of it that the section being written needs, checks the text against the rules of yours that a tool can test, and asks you before anything becomes permanent. The goal is to automate communication while keeping your idiosyncrasies.
+
+`parla` works as a plugin for agentic tools. It ships a skill that Claude Code and opencode load, and the skill carries the working method: how a job is routed, when the agent asks you, and how it learns from your corrections. The `parla` CLI supplies what the agent cannot do alone, and you talk to the agent as usual:
+
+```
+/parla icra-paper introduction
+```
+
+- **Final format.** The agent edits LaTeX, SVG or plain text directly, and `parla` builds it in a pinned Docker image. See the [architecture](https://github.com/ptonso/parla/blob/master/specs/architecture.md).
+- **Good defaults.** A brief per modality, a note per topic and a few starter checks give a reasonable first draft before you teach anything. See [guides](https://github.com/ptonso/parla/blob/master/specs/guides.md).
+- **Checks what can be tested.** A pattern, such as an em dash or a reference form, fails the build with its line, and a question, such as whether a citation supports its claim, is located for the agent to answer with a quoted line. See [constraints](https://github.com/ptonso/parla/blob/master/specs/constraints.md).
+- **Learns from corrections.** Your fixes become cases, rules or constraints, always with your approval. See the [casebook](https://github.com/ptonso/parla/blob/master/specs/casebook.md).
+- **Safe to steer.** Every job is snapshotted and diffed, and can be reverted. See [jobs](https://github.com/ptonso/parla/blob/master/specs/jobs.md).
+- **Local.** Your guides and casebook are plain files on your machine, and `parla` makes no model calls.
+
+## Vision
+
+`parla` keeps a human in the loop. You make the decisions about what to say and which writing preferences to keep. The agent applies the decisions you already made and proposes text that follows them. It asks before anything becomes permanent: a case, a rule, a constraint or a claim in the card.
+
+A job has two roles. The agent you talk to chooses the topics the section needs (`parla guide list topic` shows each with its size and when it applies), relays the worker's questions to you and keeps your memories. One worker subagent writes. Its prompt is short, about 1000 words: your rules for those topics, one-line hooks of earlier corrections and the card ([skill spec](https://github.com/ptonso/parla/blob/master/specs/skill.md)). The worker is done when `parla check` ends with `suite: 0 fail, 0 probes open`.
+
+## How it learns
+
+When a job ends, the agent proposes where each correction belongs and you accept, rephrase or decline: a case for an illustration, a rule for a matter of degree, a constraint for what a pattern or a yes-or-no question can decide. When several cases share a lesson, it proposes a rule with the cases as evidence, and it keeps the guides inside their size budget by merging and rewriting rules.
+
+| Memory | Holds | Changes |
+|---|---|---|
+| Guides | your stable rules, on top of the shipped defaults | slowly |
+| Constraints | patterns and questions with an exact answer, run by every check and build | when a correction has an exact answer |
+| Casebook | your corrections, each with a before, an after and a lesson | every job |
+| Card | the decisions of one artifact: claim strength, scope, which result leads | per artifact |
+
+More in [how it learns](https://github.com/ptonso/parla/blob/master/docs/guide/learning.md).
+
+## Modalities
+
+| Modality | Output |
+|---|---|
+| `paper`, `short-paper`, `thesis` | PDF, plus a change PDF against the job snapshot |
+| `cv` | PDF |
+| `talk` | Beamer PDF |
+| `diagram` | SVG and PNG |
+| `social-post` | plain text |
+
+## Quick start
+
+`parla` needs Python 3.12 and Docker.
+
+```bash
+pip install "parla[svg,pdf]"
+parla image build
+parla init
+parla init artifact my-paper --modality paper
+```
+
+`parla init` links the skill into `.claude/skills` and `.agents/skills`. Open your agent and type `/parla my-paper`. The full walk-through is in the [quick start](https://github.com/ptonso/parla/blob/master/docs/guide/quickstart.md).
+
+## Documentation
+
+- [Quick start](https://github.com/ptonso/parla/blob/master/docs/guide/quickstart.md): install, first artifact, first job.
+- [How it learns](https://github.com/ptonso/parla/blob/master/docs/guide/learning.md): cases, rules, constraints and the four memories.
+- [Development](https://github.com/ptonso/parla/blob/master/docs/guide/development.md): tests and linting.
+- [specs/](https://github.com/ptonso/parla/blob/master/specs/README.md): the contract of every command and format. The agent's method is the [skill spec](https://github.com/ptonso/parla/blob/master/specs/skill.md).
+
+## License
+
+Apache 2.0. See [LICENSE](https://github.com/ptonso/parla/blob/master/LICENSE) and [THIRD-PARTY.md](https://github.com/ptonso/parla/blob/master/THIRD-PARTY.md).

parla-0.0.1/README.md

@@ -0,0 +1,71 @@
+# parla
+
+`parla` lets a coding agent write papers, CVs, talks, posts and diagrams in your own voice.
+
+It keeps your long-term memory of how you write, loads the part of it that the section being written needs, checks the text against the rules of yours that a tool can test, and asks you before anything becomes permanent. The goal is to automate communication while keeping your idiosyncrasies.
+
+`parla` works as a plugin for agentic tools. It ships a skill that Claude Code and opencode load, and the skill carries the working method: how a job is routed, when the agent asks you, and how it learns from your corrections. The `parla` CLI supplies what the agent cannot do alone, and you talk to the agent as usual:
+
+```
+/parla icra-paper introduction
+```
+
+- **Final format.** The agent edits LaTeX, SVG or plain text directly, and `parla` builds it in a pinned Docker image. See the [architecture](https://github.com/ptonso/parla/blob/master/specs/architecture.md).
+- **Good defaults.** A brief per modality, a note per topic and a few starter checks give a reasonable first draft before you teach anything. See [guides](https://github.com/ptonso/parla/blob/master/specs/guides.md).
+- **Checks what can be tested.** A pattern, such as an em dash or a reference form, fails the build with its line, and a question, such as whether a citation supports its claim, is located for the agent to answer with a quoted line. See [constraints](https://github.com/ptonso/parla/blob/master/specs/constraints.md).
+- **Learns from corrections.** Your fixes become cases, rules or constraints, always with your approval. See the [casebook](https://github.com/ptonso/parla/blob/master/specs/casebook.md).
+- **Safe to steer.** Every job is snapshotted and diffed, and can be reverted. See [jobs](https://github.com/ptonso/parla/blob/master/specs/jobs.md).
+- **Local.** Your guides and casebook are plain files on your machine, and `parla` makes no model calls.
+
+## Vision
+
+`parla` keeps a human in the loop. You make the decisions about what to say and which writing preferences to keep. The agent applies the decisions you already made and proposes text that follows them. It asks before anything becomes permanent: a case, a rule, a constraint or a claim in the card.
+
+A job has two roles. The agent you talk to chooses the topics the section needs (`parla guide list topic` shows each with its size and when it applies), relays the worker's questions to you and keeps your memories. One worker subagent writes. Its prompt is short, about 1000 words: your rules for those topics, one-line hooks of earlier corrections and the card ([skill spec](https://github.com/ptonso/parla/blob/master/specs/skill.md)). The worker is done when `parla check` ends with `suite: 0 fail, 0 probes open`.
+
+## How it learns
+
+When a job ends, the agent proposes where each correction belongs and you accept, rephrase or decline: a case for an illustration, a rule for a matter of degree, a constraint for what a pattern or a yes-or-no question can decide. When several cases share a lesson, it proposes a rule with the cases as evidence, and it keeps the guides inside their size budget by merging and rewriting rules.
+
+| Memory | Holds | Changes |
+|---|---|---|
+| Guides | your stable rules, on top of the shipped defaults | slowly |
+| Constraints | patterns and questions with an exact answer, run by every check and build | when a correction has an exact answer |
+| Casebook | your corrections, each with a before, an after and a lesson | every job |
+| Card | the decisions of one artifact: claim strength, scope, which result leads | per artifact |
+
+More in [how it learns](https://github.com/ptonso/parla/blob/master/docs/guide/learning.md).
+
+## Modalities
+
+| Modality | Output |
+|---|---|
+| `paper`, `short-paper`, `thesis` | PDF, plus a change PDF against the job snapshot |
+| `cv` | PDF |
+| `talk` | Beamer PDF |
+| `diagram` | SVG and PNG |
+| `social-post` | plain text |
+
+## Quick start
+
+`parla` needs Python 3.12 and Docker.
+
+```bash
+pip install "parla[svg,pdf]"
+parla image build
+parla init
+parla init artifact my-paper --modality paper
+```
+
+`parla init` links the skill into `.claude/skills` and `.agents/skills`. Open your agent and type `/parla my-paper`. The full walk-through is in the [quick start](https://github.com/ptonso/parla/blob/master/docs/guide/quickstart.md).
+
+## Documentation
+
+- [Quick start](https://github.com/ptonso/parla/blob/master/docs/guide/quickstart.md): install, first artifact, first job.
+- [How it learns](https://github.com/ptonso/parla/blob/master/docs/guide/learning.md): cases, rules, constraints and the four memories.
+- [Development](https://github.com/ptonso/parla/blob/master/docs/guide/development.md): tests and linting.
+- [specs/](https://github.com/ptonso/parla/blob/master/specs/README.md): the contract of every command and format. The agent's method is the [skill spec](https://github.com/ptonso/parla/blob/master/specs/skill.md).
+
+## License
+
+Apache 2.0. See [LICENSE](https://github.com/ptonso/parla/blob/master/LICENSE) and [THIRD-PARTY.md](https://github.com/ptonso/parla/blob/master/THIRD-PARTY.md).

parla-0.0.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "parla"
+version = "0.0.1"
+description = "Agent-first tool for writing papers, slides, posts and diagrams in their final format, guided by the author's guides and corrections."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "ptonso" }]
+keywords = ["latex", "agent", "writing", "docker", "pdf"]
+dependencies = ["PyYAML>=6.0"]
+
+[project.scripts]
+parla = "parla.cli:main"
+
+[project.optional-dependencies]
+pdf = ["pymupdf>=1.24.0", "pymupdf4llm>=0.3.0"]
+svg = ["fonttools>=4.40"]
+dev = ["pytest>=7.4", "ruff>=0.6", "mypy>=1.7", "types-PyYAML"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+parla = ["docker/*", "data/*", "texmf/**/*", "assets/fonts/*", "guides/**/*.md", "guides/*.jsonl", "skills/parla/*.md", "py.typed"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-q"
+markers = ["docker: needs a running Docker daemon"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.12"
+
+# Copied from texfy-ai with its typing; the copies are compared against the originals, not retyped.
+[[tool.mypy.overrides]]
+module = ["parla.tools.pdf.*", "parla.tools.sections", "parla.tools.table_parse", "parla.tools.table_fit", "parla.tools.table_render"]
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = ["fontTools.*"]
+ignore_missing_imports = true

parla-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

parla-0.0.1/src/parla/__init__.py

@@ -0,0 +1,3 @@
+"""parla."""
+
+__version__ = "0.0.1"

parla-0.0.1/src/parla/assets/fonts/LICENSE-Latin-Modern.txt

@@ -0,0 +1,171 @@
+This package was debianized by Florent Rougon <f.rougon@free.fr> on
+Tue, 27 Jan 2004 20:12:21 +0100.
+
+The following TeX Live packages were downloaded from 
+    http://www.ctan.org/tex-archive/systems/texlive/tlnet/archive/
+and merged into one orig.tar.gz file:
+    lm.tar.xz
+    lm.doc.tar.xz
+    lm-math.tar.xz
+    lm-math.doc.tar.xz
+
+
+Upstream work
+-------------
+
+The upstream README-Latin-Modern.txt file says:
+
+  Font: The Latin Modern Family of Fonts
+  Designer (Computer Modern Family of Fonts): Donald E. Knuth
+  Author: Bogus\l{}aw Jackowski and Janusz M. Nowacki
+  Version: 2.005
+  Date: 21 III 2021
+  Downloads: http://www.gust.org.pl/projects/e-foundry/latin-modern/
+  License: 
+    % Copyright 2003--2021 by B. Jackowski and J.M. Nowacki
+    % (on behalf of TeX Users Groups).
+    % This work is released under the GUST Font License
+    %   -- see GUST-FONT-LICENSE.txt.
+    % This work has the LPPL maintenance status "maintained".
+    % The Current Maintainer of this work is Bogus\l{}aw Jackowski
+    % This work consists of the files listed in the MANIFEST.txt file.
+
+  [...]
+
+  The current LM package contains the most recent version
+  of the Latin Modern family of fonts in the PostScript Type 1 and
+  OpenType format. The fonts are based on Donald E. Knuth's Computer Modern
+  fonts in the PostScript Type 1 format, released into public domain by the
+  American Mathematical Society (for the history of the outline version of
+  the CM fonts see, e.g., http://www.math.utah.edu/~beebe/fonts/bluesky.html ).
+  The project is supported by TeX users groups: CSTUG, DANTE eV, GUST,
+  GUTenberg, NTG, and TUG.
+
+
+The current README-Latin-Modern-Math.txt says
+License:
+  % Copyright 2012--2014 for the Latin Modern math extensions by B. Jackowski,
+  % P. Strzelczyk and P. Pianowski (on behalf of TeX Users Groups).
+  %
+  % This work can be freely used and distributed under
+  % the GUST Font License (GFL -- see GUST-FONT-LICENSE.txt)
+  % which is actually an instance of the LaTeX Project Public License
+  % (LPPL -- see http://www.latex-project.org/lppl.txt).
+  %
+  % This work has the maintenance status "maintained". The Current Maintainer
+  % of this work is Bogus\l{}aw Jackowski, Piotr Strzelczyk and Piotr Pianowski.
+  %
+  % This work consists of the files listed
+  % in the MANIFEST-Latin-Modern-Math.txt file.
+
+
+See the appendix B for the GUST Font License.
+
+Please read the appendix A below if you want to examine the licensing terms 
+for the Computer Modern fonts in Type 1 format on which the Latin Modern fonts
+are based.
+
+
+Debian packaging
+----------------
+
+Copyright (c) 2004-2007 Florent Rougon
+Copyright (c) 2005-2019 Norbert Preining
+Copyright (c) 2021-2022 Hilmar Preusse
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; version 2 dated June, 1991.
+
+   This program is distributed in the hope that it will be useful, but
+   WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+   General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; see the file COPYING. If not, write to the
+   Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+   Boston, MA  02110-1301 USA.
+
+On Debian systems, the complete text of the GNU General Public License version
+2 can be found in `/usr/share/common-licenses/GPL-2'.
+
+
+Appendix A -- Licensing terms for the Computer Modern fonts in Type 1 format
+              on which the Latin Modern fonts are based.
+-----------------------------------------------------------------------------
+
+Running t1disasm (from the t1utils package) on
+/usr/share/texmf/fonts/type1/bluesky/cm/*.pfb and
+/usr/share/texmf/fonts/type1/bluesky/cmextra/*.pfb yields:
+
+  Copyright (C) 1997 American Mathematical Society.  All Rights Reserved
+
+  [ Florent Rougon's note: well, for
+    /usr/share/texmf/fonts/type1/bluesky/cm/cmb{,sy}10.pfb, you will only get
+    one space between "Society." and "All" (with tetex-extra 2.0.2-5.1). ;-) ]
+
+The precise distribution conditions for these fonts can be found in
+/usr/share/doc/texmf/fonts/bluesky/README from the tetex-doc package. I will
+duplicate here the relevant excerpt for your convenience:
+
+  The PostScript Type 1 implementation of the Computer Modern fonts produced
+  by and previously distributed by Blue Sky Research and Y&Y, Inc. are now
+  freely available for general use. This has been accomplished through the
+  cooperation of a consortium of scientific publishers with Blue Sky Research
+  and Y&Y. Members of this consortium include:
+
+        Elsevier Science
+        IBM Corporation
+        Society for Industrial and Applied Mathematics (SIAM)
+        Springer-Verlag
+        American Mathematical Society (AMS)
+
+  In order to assure the authenticity of these fonts, copyright will be held
+  by the American Mathematical Society. This is not meant to restrict in any
+  way the legitimate use of the fonts, such as (but not limited to) electronic
+  distribution of documents containing these fonts, inclusion of these fonts
+  into other public domain or commercial font collections or computer
+  applications, use of the outline data to create derivative fonts and/or
+  faces, etc. However, the AMS does require that the AMS copyright notice be
+  removed from any derivative versions of the fonts which have been altered in
+  any way. In addition, to ensure the fidelity of TeX documents using Computer
+  Modern fonts, Professor Donald Knuth, creator of the Computer Modern faces,
+  has requested that any alterations which yield different font metrics be
+  given a different name.
+
+
+Appendix B -- GUST Font License
+-------------------------------
+
+What follows is the exact contents of GUST-FONT-LICENSE.txt from the
+upstream distribution of the Latin Modern fonts.
+
+% This is version 1.0, dated 22 June 2009, of the GUST Font License.
+% (GUST is the Polish TeX Users Group, http://www.gust.org.pl)
+%
+% For the most recent version of this license see
+% http://www.gust.org.pl/fonts/licenses/GUST-FONT-LICENSE.txt
+% or
+% http://tug.org/fonts/licenses/GUST-FONT-LICENSE.txt
+%
+% This work may be distributed and/or modified under the conditions
+% of the LaTeX Project Public License, either version 1.3c of this
+% license or (at your option) any later version.
+%
+% Please also observe the following clause:
+% 1) it is requested, but not legally required, that derived works be
+%    distributed only after changing the names of the fonts comprising this
+%    work and given in an accompanying "manifest", and that the
+%    files comprising the Work, as listed in the manifest, also be given
+%    new names. Any exceptions to this request are also given in the
+%    manifest.
+%
+%    We recommend the manifest be given in a separate file named
+%    MANIFEST-<fontid>.txt, where <fontid> is some unique identification
+%    of the font family. If a separate "readme" file accompanies the Work,
+%    we recommend a name of the form README-<fontid>.txt.
+%
+% The latest version of the LaTeX Project Public License is in
+% http://www.latex-project.org/lppl.txt and version 1.3c or later
+% is part of all distributions of LaTeX version 2006/05/20 or later.

parla-0.0.1/src/parla/casebook.py

@@ -0,0 +1,180 @@
+"""The casebook: approved corrections as an append-only JSON-lines store. See `specs/casebook.md`."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, date, datetime, timedelta
+from pathlib import Path
+
+from . import config as config_mod
+from .checks import Finding
+from .checks.ids import finding
+
+STATUSES = ("active", "distilled", "contradicted", "pruned")
+REQUIRED = ("artifact", "part", "topics", "hook", "problem", "before", "after", "lesson")
+CASES_FILE = "cases.jsonl"
+USE_FILE = "cases.use.jsonl"
+
+
+class CaseError(Exception):
+    """A case command cannot proceed."""
+
+
+def _path(name: str) -> Path:
+    return config_mod.guides_private() / name
+
+
+def _lines(name: str) -> list[dict]:
+    path = _path(name)
+    if not path.is_file():
+        return []
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+def _append(name: str, entry: dict) -> None:
+    path = _path(name)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+
+def load() -> dict[str, dict]:
+    """The current state of every case: its lines folded in order. Insertion order is first-seen."""
+    cases: dict[str, dict] = {}
+    for entry in _lines(CASES_FILE):
+        cases.setdefault(entry["id"], {}).update(entry)
+    return cases
+
+
+def add(root: Path, payload: dict, known_topics: set[str], *, today: date | None = None) -> str:
+    missing = [k for k in REQUIRED if not payload.get(k)]
+    if missing:
+        raise CaseError(f"missing field(s): {', '.join(missing)}")
+    if not isinstance(payload["topics"], list):
+        raise CaseError("topics must be a list")
+    unknown = [t for t in payload["topics"] if t not in known_topics]
+    if unknown:
+        raise CaseError(f"unknown topic(s): {', '.join(unknown)} (have: {', '.join(sorted(known_topics))})")
+    for key in ("hook", "lesson"):
+        if "\n" in payload[key].strip():
+            raise CaseError(f"the {key} must be one line")
+    card = config_mod.load_card(root, payload["artifact"])
+    cases = load()
+    number = max((int(i.removeprefix("c-")) for i in cases), default=0) + 1
+    entry = {
+        "id": f"c-{number:04d}",
+        "date": (today or datetime.now(UTC).date()).isoformat(),
+        **{k: payload[k] for k in REQUIRED},
+        "modality": card.modality,
+        "audience": card.audience,
+        "contradicts": payload.get("contradicts", []),
+        "status": "active",
+    }
+    _append(CASES_FILE, entry)
+    return entry["id"]
+
+
+EDITABLE = ("hook", "lesson", "problem", "topics")
+
+
+def edit(case_id: str, fields: dict, known_topics: set[str]) -> None:
+    """Appends an update to a case. Only the hook, lesson, problem and topics can change; the before
+    and after stay as the author left them."""
+    if case_id not in load():
+        raise CaseError(f"unknown case '{case_id}'")
+    bad = set(fields) - set(EDITABLE)
+    if bad or not fields:
+        raise CaseError(f"edit takes {', '.join(EDITABLE)}; got {', '.join(sorted(bad)) or 'nothing'}")
+    for key in ("hook", "lesson"):
+        if key in fields and ("\n" in str(fields[key]).strip() or not str(fields[key]).strip()):
+            raise CaseError(f"the {key} must be one non-empty line")
+    unknown = [t for t in fields.get("topics", []) if t not in known_topics]
+    if unknown:
+        raise CaseError(f"unknown topic(s): {', '.join(unknown)} (have: {', '.join(sorted(known_topics))})")
+    _append(CASES_FILE, {"id": case_id, **fields})
+
+
+def mark(case_id: str, status: str) -> None:
+    if status not in STATUSES:
+        raise CaseError(f"unknown status '{status}' (have: {', '.join(STATUSES)})")
+    if case_id not in load():
+        raise CaseError(f"unknown case '{case_id}'")
+    _append(CASES_FILE, {"id": case_id, "status": status})
+
+
+def list_lines(topic: str | None = None, status: str | None = None) -> list[str]:
+    return [
+        f"{c['id']} {c['status']} {','.join(c['topics'])} {c['audience']} {c.get('hook', '-')} | {c['lesson']}"
+        for c in load().values()
+        if (topic is None or topic in c["topics"]) and (status is None or c["status"] == status)
+    ]
+
+
+def retrieve(
+    *, topics: set[str], modality: str, audience: str | None, artifact: str, max_cases: int
+) -> list[dict]:
+    """Active or distilled cases on the loaded topics whose audience and modality match or are
+    absent, best first: same artifact, same audience, same modality, most recent."""
+    hits = [
+        c for c in load().values()
+        if c["status"] in ("active", "distilled")
+        and topics & set(c["topics"])
+        and (not c.get("audience") or c["audience"] == audience)
+        and (not c.get("modality") or c["modality"] == modality)
+    ]
+    hits.sort(
+        key=lambda c: (c["artifact"] == artifact, c.get("audience") == audience, c.get("modality") == modality, c["date"], c["id"]),
+        reverse=True,
+    )
+    return hits[:max_cases]
+
+
+def show(case_ids: list[str], artifact: str) -> str:
+    """The cases in full as XML, in the order asked; logs one use per case."""
+    cases = load()
+    unknown = [i for i in case_ids if i not in cases]
+    if unknown:
+        raise CaseError(f"unknown case(s): {', '.join(unknown)}")
+    log_use(case_ids, artifact)
+    return "\n\n".join(
+        f'<case id="{i}">\n'
+        + "\n".join(f"<{k}>{cases[i][k]}</{k}>" for k in ("problem", "after", "lesson"))
+        + "\n</case>"
+        for i in case_ids
+    )
+
+
+def log_use(case_ids: list[str], artifact: str, *, today: date | None = None) -> None:
+    stamp = (today or datetime.now(UTC).date()).isoformat()
+    for case_id in case_ids:
+        _append(USE_FILE, {"case": case_id, "date": stamp, "artifact": artifact})
+
+
+def lint(*, distill_min: int, stale_days: int | None, today: date | None = None) -> list[Finding]:
+    today = today or datetime.now(UTC).date()
+    cases = load()
+    first_line: dict[str, int] = {}
+    for number, entry in enumerate(_lines(CASES_FILE), 1):
+        first_line.setdefault(entry["id"], number)
+    active = [c for c in cases.values() if c["status"] == "active"]
+    findings: list[Finding] = []
+    groups: dict[tuple[str, str], list[str]] = {}
+    for c in active:
+        for topic in c["topics"]:
+            groups.setdefault((topic, c.get("audience", "")), []).append(c["id"])
+    for (topic, audience), ids in sorted(groups.items()):
+        if len(ids) >= distill_min:
+            findings.append(finding(
+                "case-distill", CASES_FILE, first_line[ids[0]],
+                f"{len(ids)} active cases on '{topic}' for '{audience}' ({', '.join(ids)}): propose a principle",
+            ))
+    if stale_days is not None:
+        last_use: dict[str, str] = {}
+        for use in _lines(USE_FILE):
+            last_use[use["case"]] = max(last_use.get(use["case"], ""), use["date"])
+        cutoff = today - timedelta(days=stale_days)
+        for c in active:
+            seen = date.fromisoformat(last_use.get(c["id"], c["date"]))
+            if seen < cutoff:
+                findings.append(finding("case-stale", CASES_FILE, first_line[c["id"]], f"{c['id']} was not retrieved since {seen}"))
+    return findings

parla-0.0.1/src/parla/checks/__init__.py

@@ -0,0 +1,3 @@
+from .finding import CheckFailed, Finding, Severity
+
+__all__ = ["CheckFailed", "Finding", "Severity"]

parla-0.0.1/src/parla/checks/finding.py

@@ -0,0 +1,28 @@
+"""One reported problem. See `specs/checks.md#finding`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Severity = Literal["error", "warning", "probe", "resolved"]
+
+
+@dataclass(frozen=True)
+class Finding:
+    file: str  # relative to parla/
+    line: int
+    severity: Severity
+    id: str
+    message: str
+
+    def format(self) -> str:
+        return f"{self.file}:{self.line}: {self.severity} {self.id}: {self.message}"
+
+
+class CheckFailed(Exception):
+    """A check reported an error finding; nothing was built."""
+
+    def __init__(self, findings: list[Finding]):
+        self.findings = findings
+        super().__init__("\n".join(f.format() for f in findings if f.severity == "error"))