Metadata-Version: 2.5
Name: luria
Version: 0.8.1
Summary: A project's memory: decisions, principles, changelog and devlog, kept honest by lint
Project-URL: Homepage, https://github.com/dmarx/luria
Project-URL: Documentation, https://dmarx.github.io/luria/
Project-URL: Repository, https://github.com/dmarx/luria
Project-URL: Issues, https://github.com/dmarx/luria/issues
Project-URL: Changelog, https://github.com/dmarx/luria/blob/main/CHANGELOG.md
Author: dmarx
License: MIT
License-File: LICENSE
Keywords: adr,architecture-decision-records,changelog,devlog,documentation,lint,project-memory
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: fire>=0.7
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: build>=1; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/branding/luria-brainslug/luria_project_memory_lockup_horizontal.svg"
       alt="Luria — project memory" width="480">
</p>

# Luria

**A record of what your project knows — and of what it no longer believes.**

Projects forget, and they forget *silently*. The wiki still renders. The
decisions folder still has files in it. Nothing announces that a rationale
expired, or that the reasoning behind a constraint now points at a decision
somebody reversed.

Here is the whole idea. A page cites a decision by name:

```markdown
We retry writes because ADR-012 requires at-least-once delivery.
```

Months later that decision is superseded — one field, in one file:

```yaml
status: 'Superseded — by ADR-013'
```

Nobody edited `docs/api.md`. It is now wrong, and it says so:

```console
$ luria lint
luria: 1 warning(s) — retired documents cited unacknowledged from current docs/code
  ADR-012 is Superseded, cited 1× in 1 file(s) — Writes are at-least-once

$ luria reports
docs/api.md:3
```

The old decision is not deleted; it keeps its body and its reasons. What
changed is that everything resting on it became visible. Now fix the sentence,
or say at the citing site why the citation is deliberate:

```markdown
<!-- inactive-ok: ADR-012 — the history this section is about -->
```

Either way the finding closes, and the reason it closed is written down.

That operation is the product. The rest is machinery around it: identities
worth citing, statuses that mean something, and views generated so they cannot
drift from their sources.

<!-- luria:badges -->
[![needs decision: 0](https://img.shields.io/badge/needs%20decision-0-brightgreen)](docs/reports/pending-decisions.md)
[![cited, not in force: 0](https://img.shields.io/badge/cited,%20not%20in%20force-0-brightgreen)](docs/reports/reference-status.md)
<!-- /luria:badges -->

📖 **[dmarx.github.io/luria](https://dmarx.github.io/luria/)** — this
repository's own record, published by `luria site`. Searchable, with backlinks
and a graph. Not a mirror of these docs: it is the output of one of the
features, applied to the project that ships it.

## Install

```
pip install luria
```

Python 3.11+. Two runtime dependencies (PyYAML, fire).

## Sixty seconds

```console
$ luria init --dry-run                      # what would it add?
$ luria init                                # issue_url comes from your remote
$ luria index                               # build the generated views
$ luria new --title "Switched the queue to at-least-once delivery"
record/devlog.d/2026/08/22/143005.md
$ luria new adr --title "Consumers must be idempotent"
record/decisions.d/ADR-tmp3kf9x.md
$ luria index && luria lint
luria: docs lint clean
```

Edit the two files it printed, commit, and the record has begun. The
[quickstart](docs/quickstart.md) walks the same path with explanations, and
ends by superseding a decision so you see the finding land.

## What a record holds

A record is made of several kinds of material, and they are not the same kind
of thing.

**Referable documents** — decisions, principles, RFCs, whatever a project
declares. These are the ones the operation above runs on:

- **A name something can cite.** `ADR-012`, `RFC-7` — in prose, in a commit,
  in a source comment. `luria link --fix` turns the bare code into a working
  link; the lint reports codes that resolve to nothing, so a reference is a
  claim that gets checked rather than a string that goes stale.
- **A standing**, from a closed vocabulary: `Active`, `Proposed`, `Deferred`,
  `Superseded`, `Rejected`. Retiring something is an edit to its status, never
  a deletion.
- **Rules you declare instead of hope for.** Required fields, exactly one
  primary category, what each status means *in this scheme*. The conventions
  you would otherwise write in CONTRIBUTING become things that fail. Luria will
  even tell you when a status field has stopped carrying information, which is
  what one looks like a year after anyone maintained it.

**Journals** hold dated observations — true about the day they were written,
never revised, so they carry no standing to change. **Fragment directories**
hold pieces staged for a shared document, which is how a changelog stops being
a file every branch has to touch. **Remotes** bring another project's codes,
or arXiv ids, or ticket keys, into the same citation graph.

Every view of any of them is generated by `luria index` and never hand-edited,
so a generated page cannot drift from the sources it is built from.

Luria is also its own first user: this repository's record is scaffolded,
generated and linted by the CLI it ships.

## A note on files

A record is kept as plain text in your repository, one entry per file, and
that is a deliberate implementation choice rather than the product. It is
chosen for *participation*: a contributor — or a coding agent — edits a file,
opens a pull request, and greps the result, with no application to run, no
database to migrate, and no export to negotiate when they want their history
back.

Markdown is what that looks like today and will likely stay the primary shape.
Nothing in the model above depends on it. Identity, standing, declared rules
and generated views are claims about a record, not about a file format.

## The shape of it

```
luria.toml            what this record is made of (all keys have defaults)
record/               sources — one small file per entry, written by people
  decisions.d/        ADR-001.md, ADR-002.md, …   (a "scheme")
  principles.d/       DP-001.md, …                (another scheme)
  devlog.d/           2026/08/22/143005.md        (a "journal")
  changelog.d/        one fragment per change     (a "fragment directory")
docs/                 the read surface — prose plus generated views
  decisions/          index + tag pages    (GENERATED)
  design-principles.md  one page, anchored (GENERATED)
  devlog/             monthly books        (GENERATED)
  reports/            status reports       (GENERATED)
CHANGELOG.md          assembled from fragments by `luria collect`
```

None of the names above are hard-coded. Schemes, journals, fragment
directories and remote projects are *families* declared in `luria.toml` —
a record made of RFCs, specs, and an incident log is the same engine with
different tables. See [project memory](docs/project-memory.md) and the generated
[configuration reference](docs/configuration.md).

## Kinds of record

`ADR` is not in the code. It is a table in a config file, and so is
everything else: schemes (documents with codes), journals (dated entries
that persist), fragment directories (written now, assembled later), and
remotes (someone else's namespace, cited by prefix). Name the tables and you
have a different record on the same engine.

- **Project memory** — decisions, principles, a changelog, a devlog. The
  default, and what `luria init` writes.
- **A research anthology** — one scheme of papers, another of the practices
  drawn from them, each with its own status so a foundational paper and a
  stale recommendation can disagree; arXiv identifiers linted and linked as
  a `uid` remote.
- **A standards registry** — proposals browsed as an index, the interfaces
  they define concatenated into one page.
- **An operations record** — an incident journal that is never revised
  beside runbooks that are cited by name and go stale.

[Designing a record](docs/modeling.md) is how to work out which of these
your material is.

## Documentation

- [Quickstart](docs/quickstart.md) — from empty repository to linted record.
- [Concepts](docs/concepts.md) — entries, citations, and the one operation
  everything else is machinery around.
- [Designing a record](docs/modeling.md) — what belongs in one, which family
  fits, when two kinds of entry are two schemes, and what the schema can be
  made to refuse.
- [Project memory](docs/project-memory.md) — sources and views, schemes, journals,
  fragments, remotes, statuses, constraints, and how references work.
- [CLI reference](docs/cli.md) — every command and flag.
- [Comment directives](docs/directives.md) — acknowledging a finding where
  it happens instead of silencing the check.
- [Adopting Luria](docs/adopting.md) — scaffolding an existing project,
  wiring up CI, publishing the site.
- [Importing an existing corpus](docs/importing.md) — when the material
  already exists as data, and what the transform will surface.
- [Configuration reference](docs/configuration.md) — generated from the
  schema, every key with its default.

And the record itself, dogfooded: [decisions](docs/decisions/README.md) ·
[design principles](docs/design-principles.md) ·
[development log](docs/devlog/README.md) ·
[status reports](docs/reports/pending-decisions.md).

## Citing Luria

<!-- luria:citation -->
```bibtex
@software{marx_luria,
  author  = {Marx, David},
  title   = {Luria: project memory, kept honest by lint},
  url     = {https://github.com/dmarx/luria},
  license = {MIT},
}
```
<!-- /luria:citation -->

Derived from [`CITATION.cff`](CITATION.cff) by `luria index`, which is also
what GitHub reads for its *Cite this repository* button — so the two cannot
disagree. Add `version = {...}` for the release you used; `pip show luria`
prints it. Nothing pins one here, because a version written into a file by
hand is a copy of the release tag, which is the drift [DP-3](docs/design-principles.md#dp-3) names and [ADR-053](record/decisions.d/ADR-053.md)
removed.

## License

[MIT](LICENSE).
