luria 0.1.0__tar.gz

luria-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+build/
+dist/

luria-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Marx
+
+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.

luria-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: luria
+Version: 0.1.0
+Summary: A project's memory: decisions, principles, changelog and devlog, kept honest by lint
+Project-URL: Homepage, https://github.com/dmarx/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: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Luria
+
+[![CI](https://github.com/dmarx/luria/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dmarx/luria/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/github/license/dmarx/luria)](LICENSE)
+<!-- luria:badges -->
+[![needs decision: 0](https://img.shields.io/badge/needs%20decision-0-brightgreen)](docs/decisions/README.md)
+[![cited but retired: 0](https://img.shields.io/badge/cited%20but%20retired-0-brightgreen)](docs/decisions/README.md)
+<!-- /luria:badges -->
+
+A project's memory: the decisions, the principles, the changelog and the
+narrative log — kept where the next collaborator will find them, and kept honest
+by a lint.
+
+Half the collaborators on a modern codebase are stateless. They arrive with no
+memory, read some pages, work, and vanish. Unwritten knowledge is re-derived at
+cost, per session, forever. Luria is the machinery for a record that survives
+that: [project memory](docs/project-memory.md) is the doctrine, and this package
+is what stops it drifting.
+
+```
+pip install luria
+luria init --issue-url https://github.com/owner/repo/issues
+luria index && luria lint
+```
+
+## What it does
+
+| command | |
+|---|---|
+| `luria lint` | the only command that can fail: index completeness, frontmatter, a stale generated index, and references that should be links |
+| `luria link --fix` | rewrites bare references as hyperlinks — the same scanner the lint reads, so the failure names its own remedy |
+| `luria index` | regenerates every generated view from frontmatter — the decision index and its per-tag pages, the principles document |
+| `luria ref-status` | which retired decisions are still cited, and where |
+| `luria pending` | which documents are undecided, by age **and** citation count — every scheme |
+| `luria badges` | the README's two counts, derived from the record |
+| `luria reports` | both reports as markdown, for a CI artifact |
+| `luria collect` | assembles fragment directories into their views |
+| `luria remotes` | another project's record: how each foreign reference resolves, and whether it is reachable |
+| `luria init` | scaffolds the record into a project that has none |
+
+## The four layers
+
+| layer | holds | test |
+|---|---|---|
+| design principles | standing **values**, numbered, citable and **versioned** | *have we re-derived this more than once?* |
+| decisions | a **choice among alternatives** at a point in time | *did we reject an alternative, or set a constraint?* |
+| changelog fragments | **what changed**, operator-facing | *would someone running this notice?* |
+| devlog entries | **how it went**, including the wrong theories | *will a future debugger want the narrative?* |
+
+Each contribution writes a *fragment* nobody else touches; the shared documents
+are **views**. A file every contribution appends to is a lock, and its conflicts
+carry no information ([DP-2](docs/design-principles.md#dp-2)).
+
+The tree says which is which ([DP-9](docs/design-principles.md#dp-9),
+[ADR-021](record/decisions.d/ADR-021.md)): **you read in `docs/`, you file in
+`record/`**. Browsing lands on prose and generated views; the sources sit in
+`record/`'s `.d`-suffixed containers, arrived at by link or on purpose. A view
+directory holds only what the generator wrote — a hand edit there is a lint
+failure, not a plea in a comment.
+
+```
+docs/                     READ  — doctrine + every generated view
+record/decisions.d/       WRITE — one file per decision
+record/principles.d/      WRITE — one file per principle
+record/changelog.d/       WRITE — fragments, collected into /CHANGELOG.md
+record/devlog.d/          WRITE — journal entries, yyyy/mm/dd/hhmmss.md
+```
+
+Views come in two kinds, and the difference is whether the sources survive
+([ADR-012](record/decisions.d/ADR-012.md)). The changelog is **collected**: its
+fragments are consumed, so the view can only be appended to. The decision index,
+the principles document and the devlog are **generated** — a pure function of
+sources that persist, which is the only reason `luria lint` can tell you one has
+gone stale.
+
+The devlog is a **journal**: entries are filed at their authoring timestamp
+(`record/devlog.d/2026/08/03/211926.md`), never deleted, and rendered into one book per
+month with a generated contents list ([ADR-020](record/decisions.d/ADR-020.md)). A
+dated observation was true when it was written and stays true; consuming it
+throws away the only copy of something that never expires.
+
+## Citing another project
+
+A record extracted from another project cites it constantly, and an unprefixed
+code can't mean both "ours" and "theirs". Register the remote once:
+
+```toml
+[luria.remotes.SG]
+repo = "dmarx/strata-g"
+```
+
+and `SG-ADR-032` becomes a first-class reference — `luria link --fix` writes the
+URL, `luria lint` demands it, and `luria remotes --check` says whether it still
+resolves. A remote that names its files after their codes needs nothing else; one
+whose filenames carry title slugs gets `luria remotes --refresh` once, which
+discovers them into a committed lockfile so CI and offline checkouts resolve
+identically ([ADR-016](record/decisions.d/ADR-016.md)).
+
+A citation can land before its URL does. Luria cites both `SG` (the pilot it was
+extracted from, whose filenames haven't been converted yet) and `LU` (itself,
+which the `luria init` scaffold points at). Naming the document is the durable
+half and works immediately; the URL improves when the remote does
+([ADR-017](record/decisions.d/ADR-017.md)).
+
+## Why a lint
+
+Because the same audit result keeps recurring: **every documentation surface
+with an executable guard held; every surface governed by prose alone had
+drifted.** Not toward one wrong value — toward *variety*, which is worse,
+because a reader can't learn what the convention is.
+
+So the norms that matter get walked up the ladder — prose → convention →
+mechanism → guarantee ([DP-5](docs/design-principles.md#dp-5)) — and this
+package is the last rung.
+
+## Provenance
+
+Every rule here was earned in
+[strata-g](https://github.com/dmarx/strata-g), where the machinery was built and
+run before it was extracted. The principles and decisions name the incidents
+that produced them, because a rule whose evidence is missing reads as taste, and
+taste gets re-litigated ([ADR-009](record/decisions.d/ADR-009.md)).
+
+Luria runs its own machinery on its own record — the decision index and the
+principles document in this repo are both generated by `luria index`, and these
+files are linted by `luria lint`. That is not tidiness: it is how the first
+consumer to hit a bug is this repo.
+
+## Docs
+
+- [Project memory](docs/project-memory.md) — the doctrine
+- [Design principles](docs/design-principles.md)
+- [Decisions](docs/decisions/README.md)
+- [Comment directives](docs/directives.md) — `inactive-ok`, `unexempt`
+- [Adopting Luria](docs/adopting.md)
+
+MIT.

luria-0.1.0/README.md

@@ -0,0 +1,138 @@
+# Luria
+
+[![CI](https://github.com/dmarx/luria/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dmarx/luria/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/github/license/dmarx/luria)](LICENSE)
+<!-- luria:badges -->
+[![needs decision: 0](https://img.shields.io/badge/needs%20decision-0-brightgreen)](docs/decisions/README.md)
+[![cited but retired: 0](https://img.shields.io/badge/cited%20but%20retired-0-brightgreen)](docs/decisions/README.md)
+<!-- /luria:badges -->
+
+A project's memory: the decisions, the principles, the changelog and the
+narrative log — kept where the next collaborator will find them, and kept honest
+by a lint.
+
+Half the collaborators on a modern codebase are stateless. They arrive with no
+memory, read some pages, work, and vanish. Unwritten knowledge is re-derived at
+cost, per session, forever. Luria is the machinery for a record that survives
+that: [project memory](docs/project-memory.md) is the doctrine, and this package
+is what stops it drifting.
+
+```
+pip install luria
+luria init --issue-url https://github.com/owner/repo/issues
+luria index && luria lint
+```
+
+## What it does
+
+| command | |
+|---|---|
+| `luria lint` | the only command that can fail: index completeness, frontmatter, a stale generated index, and references that should be links |
+| `luria link --fix` | rewrites bare references as hyperlinks — the same scanner the lint reads, so the failure names its own remedy |
+| `luria index` | regenerates every generated view from frontmatter — the decision index and its per-tag pages, the principles document |
+| `luria ref-status` | which retired decisions are still cited, and where |
+| `luria pending` | which documents are undecided, by age **and** citation count — every scheme |
+| `luria badges` | the README's two counts, derived from the record |
+| `luria reports` | both reports as markdown, for a CI artifact |
+| `luria collect` | assembles fragment directories into their views |
+| `luria remotes` | another project's record: how each foreign reference resolves, and whether it is reachable |
+| `luria init` | scaffolds the record into a project that has none |
+
+## The four layers
+
+| layer | holds | test |
+|---|---|---|
+| design principles | standing **values**, numbered, citable and **versioned** | *have we re-derived this more than once?* |
+| decisions | a **choice among alternatives** at a point in time | *did we reject an alternative, or set a constraint?* |
+| changelog fragments | **what changed**, operator-facing | *would someone running this notice?* |
+| devlog entries | **how it went**, including the wrong theories | *will a future debugger want the narrative?* |
+
+Each contribution writes a *fragment* nobody else touches; the shared documents
+are **views**. A file every contribution appends to is a lock, and its conflicts
+carry no information ([DP-2](docs/design-principles.md#dp-2)).
+
+The tree says which is which ([DP-9](docs/design-principles.md#dp-9),
+[ADR-021](record/decisions.d/ADR-021.md)): **you read in `docs/`, you file in
+`record/`**. Browsing lands on prose and generated views; the sources sit in
+`record/`'s `.d`-suffixed containers, arrived at by link or on purpose. A view
+directory holds only what the generator wrote — a hand edit there is a lint
+failure, not a plea in a comment.
+
+```
+docs/                     READ  — doctrine + every generated view
+record/decisions.d/       WRITE — one file per decision
+record/principles.d/      WRITE — one file per principle
+record/changelog.d/       WRITE — fragments, collected into /CHANGELOG.md
+record/devlog.d/          WRITE — journal entries, yyyy/mm/dd/hhmmss.md
+```
+
+Views come in two kinds, and the difference is whether the sources survive
+([ADR-012](record/decisions.d/ADR-012.md)). The changelog is **collected**: its
+fragments are consumed, so the view can only be appended to. The decision index,
+the principles document and the devlog are **generated** — a pure function of
+sources that persist, which is the only reason `luria lint` can tell you one has
+gone stale.
+
+The devlog is a **journal**: entries are filed at their authoring timestamp
+(`record/devlog.d/2026/08/03/211926.md`), never deleted, and rendered into one book per
+month with a generated contents list ([ADR-020](record/decisions.d/ADR-020.md)). A
+dated observation was true when it was written and stays true; consuming it
+throws away the only copy of something that never expires.
+
+## Citing another project
+
+A record extracted from another project cites it constantly, and an unprefixed
+code can't mean both "ours" and "theirs". Register the remote once:
+
+```toml
+[luria.remotes.SG]
+repo = "dmarx/strata-g"
+```
+
+and `SG-ADR-032` becomes a first-class reference — `luria link --fix` writes the
+URL, `luria lint` demands it, and `luria remotes --check` says whether it still
+resolves. A remote that names its files after their codes needs nothing else; one
+whose filenames carry title slugs gets `luria remotes --refresh` once, which
+discovers them into a committed lockfile so CI and offline checkouts resolve
+identically ([ADR-016](record/decisions.d/ADR-016.md)).
+
+A citation can land before its URL does. Luria cites both `SG` (the pilot it was
+extracted from, whose filenames haven't been converted yet) and `LU` (itself,
+which the `luria init` scaffold points at). Naming the document is the durable
+half and works immediately; the URL improves when the remote does
+([ADR-017](record/decisions.d/ADR-017.md)).
+
+## Why a lint
+
+Because the same audit result keeps recurring: **every documentation surface
+with an executable guard held; every surface governed by prose alone had
+drifted.** Not toward one wrong value — toward *variety*, which is worse,
+because a reader can't learn what the convention is.
+
+So the norms that matter get walked up the ladder — prose → convention →
+mechanism → guarantee ([DP-5](docs/design-principles.md#dp-5)) — and this
+package is the last rung.
+
+## Provenance
+
+Every rule here was earned in
+[strata-g](https://github.com/dmarx/strata-g), where the machinery was built and
+run before it was extracted. The principles and decisions name the incidents
+that produced them, because a rule whose evidence is missing reads as taste, and
+taste gets re-litigated ([ADR-009](record/decisions.d/ADR-009.md)).
+
+Luria runs its own machinery on its own record — the decision index and the
+principles document in this repo are both generated by `luria index`, and these
+files are linted by `luria lint`. That is not tidiness: it is how the first
+consumer to hit a bug is this repo.
+
+## Docs
+
+- [Project memory](docs/project-memory.md) — the doctrine
+- [Design principles](docs/design-principles.md)
+- [Decisions](docs/decisions/README.md)
+- [Comment directives](docs/directives.md) — `inactive-ok`, `unexempt`
+- [Adopting Luria](docs/adopting.md)
+
+MIT.

luria-0.1.0/docs/README.md

@@ -0,0 +1,19 @@
+# Luria docs
+
+- [Project memory: how a repo thinks](project-memory.md) — the doctrine. Start
+  here; this is what an agent file should point at.
+- [Design principles](design-principles.md) — the standing values, numbered and
+  citable.
+- [Decisions](decisions/README.md) — the choices, with their alternatives.
+- [Comment directives](directives.md) — the `inactive-ok` / `unexempt`
+  vocabulary and its scope rules.
+- [Development log](devlog/README.md) — the narrative: failed approaches, root
+  causes, and the traps worth not rediscovering. One book per month, generated
+  from the dated entries in `record/devlog.d/`.
+- [Adopting Luria](adopting.md) — putting the record into a project that hasn't
+  got one.
+
+Everything in this directory is for *reading* — the prose pages are authored,
+and the decisions index, principles document and devlog books are generated.
+Filing happens in [`record/`](../record/), whose `.d`-suffixed containers hold
+the sources ([ADR-021](../record/decisions.d/ADR-021.md)).

luria-0.1.0/docs/decisions/README.md

@@ -0,0 +1,67 @@
+# Architecture decision records
+
+A decision record is a **choice among alternatives at a point in time**. Write
+one when you rejected an alternative, chose a constraint, or made something a
+future edit could silently violate. Copy [`_template.md`](../../record/decisions.d/_template.md); the
+number is the next one free.
+
+Values that decisions *cite* live in
+[design-principles.md](../../docs/design-principles.md) instead. The split, and why
+these are separate files, is [ADR-003](../../record/decisions.d/ADR-003.md).
+
+A decision whose **choice** changes is superseded by *adding* a decision and
+flipping the old one's status — not by rewriting its body. A record you can
+quietly rewrite can't be trusted about what you used to think.
+
+That is a rule about silence, not about editing. A decision whose choice stands
+but whose *reasoning* was wrong is corrected in place, with a `version` bump and
+a `history:` entry saying what the previous version claimed
+([ADR-019](../../record/decisions.d/ADR-019.md)). Nothing here is frozen; it is only
+un-silently revisable, and this record has worked examples of both
+([project memory §2](../../docs/project-memory.md)).
+
+<!-- GENERATED below this line by `luria index` — edit README.stub instead. -->
+
+## By tag
+
+**[The record](tags/record.md)** (18) — what the four layers hold, and the rules between them:
+[001](../../record/decisions.d/ADR-001.md) · [002](../../record/decisions.d/ADR-002.md) · [003](../../record/decisions.d/ADR-003.md) · [009](../../record/decisions.d/ADR-009.md) · [012](../../record/decisions.d/ADR-012.md) · [013](../../record/decisions.d/ADR-013.md) · [014](../../record/decisions.d/ADR-014.md) · [015](../../record/decisions.d/ADR-015.md) · [016](../../record/decisions.d/ADR-016.md) · [017](../../record/decisions.d/ADR-017.md) · [018](../../record/decisions.d/ADR-018.md) · [019](../../record/decisions.d/ADR-019.md) · [020](../../record/decisions.d/ADR-020.md) · [021](../../record/decisions.d/ADR-021.md) · [022](../../record/decisions.d/ADR-022.md) · [023](../../record/decisions.d/ADR-023.md) · [024](../../record/decisions.d/ADR-024.md) · [025](../../record/decisions.d/ADR-025.md)
+
+**[Mechanism](tags/mechanism.md)** (20) — collectors, generators, the lint, the directive vocabulary:
+[002](../../record/decisions.d/ADR-002.md) · [003](../../record/decisions.d/ADR-003.md) · [004](../../record/decisions.d/ADR-004.md) · [005](../../record/decisions.d/ADR-005.md) · [006](../../record/decisions.d/ADR-006.md) · [007](../../record/decisions.d/ADR-007.md) · [008](../../record/decisions.d/ADR-008.md) · [012](../../record/decisions.d/ADR-012.md) · [013](../../record/decisions.d/ADR-013.md) · [014](../../record/decisions.d/ADR-014.md) · [015](../../record/decisions.d/ADR-015.md) · [016](../../record/decisions.d/ADR-016.md) · [018](../../record/decisions.d/ADR-018.md) · [020](../../record/decisions.d/ADR-020.md) · [021](../../record/decisions.d/ADR-021.md) · [023](../../record/decisions.d/ADR-023.md) · [024](../../record/decisions.d/ADR-024.md) · [025](../../record/decisions.d/ADR-025.md) · [026](../../record/decisions.d/ADR-026.md) · [027](../../record/decisions.d/ADR-027.md)
+
+**[Process](tags/process.md)** (8) — how the machinery is adopted, run, and reported on:
+[007](../../record/decisions.d/ADR-007.md) · [009](../../record/decisions.d/ADR-009.md) · [010](../../record/decisions.d/ADR-010.md) · [011](../../record/decisions.d/ADR-011.md) · [017](../../record/decisions.d/ADR-017.md) · [019](../../record/decisions.d/ADR-019.md) · [022](../../record/decisions.d/ADR-022.md) · [027](../../record/decisions.d/ADR-027.md)
+
+## Chronological
+
+| # | Title | Status |
+|---|---|---|
+| [ADR-001](../../record/decisions.d/ADR-001.md) v2 | Four layers, each with a one-line test for what belongs in it: design principles hold standing values, decisions hold a choice among alternatives at a point in time, changelog fragments hold what an operator would notice, devlog fragments hold how it went — including the wrong theories, which are the reusable part. Separate files rather than one document because they have different lifecycles: a principle is revised, a decision whose choice changes is superseded rather than rewritten, a fragment is collected and deleted. Rejected: one CHANGELOG holding all four (the layers' different write patterns collide, and the one that gets skipped is always the narrative), and inferring the narrative from git history (commit messages are written to a different audience, and the failed approaches — the expensive part — never appear in them). | Active |
+| [ADR-002](../../record/decisions.d/ADR-002.md) v2 | Every contribution writes a fragment nobody else touches (`changelog.d/<slug>.md`, a journal entry, one decision file); the shared documents are VIEWS assembled on a cadence, never hand-edited. A file every contribution appends to is a lock ([DP-2](../../record/decisions.d/../../docs/design-principles.md#dp-2)) — the conflicts carry no information and each hand-resolution can silently drop someone's work. Collection is deliberately NOT per-merge: the bot commit races in-flight rebases, so it runs weekly or on demand. A stub fragment (only an HTML comment) keeps "every contribution files one" enforceable when the honest answer is "nothing a reader would notice". Rejected: per-merge collection (the race), and asking contributors to hand-merge carefully (contention, not carelessness). | Active |
+| [ADR-003](../../record/decisions.d/ADR-003.md) | A decision's status comes from a closed vocabulary (Active | Proposed | Deferred | Superseded | Rejected, plus an optional em-dash note) and lives in YAML frontmatter alongside tags, date and issue — with the lint enforcing both. The vocabulary is closed because an open one drifts into synonyms: a strata-g audit found ~30 distinct status forms, with `Accepted` and `Active` split 44/46 and meaning the same thing. Frontmatter rather than a prose header because the index is generated from these fields ([ADR-004](../../record/decisions.d/ADR-004.md)), and parsing prose to build it puts a regex between a decision and its own metadata. `Deferred` earns its place: postponement stated is better than postponement faked as `Proposed`. Rejected: free-text status (drifted), and keeping the bold `**Status:**` header alongside frontmatter (two copies to drift, [DP-4](../../record/decisions.d/../../docs/design-principles.md#dp-4)). | Active |
+| [ADR-004](../../record/decisions.d/ADR-004.md) | The decision index and its per-tag pages are GENERATED from each decision's frontmatter; `luria lint` fails on a stale one. Hand-maintaining the index made it both a lock ([DP-2](../../record/decisions.d/../../docs/design-principles.md#dp-2)) and a drifting copy ([DP-3](../../record/decisions.d/../../docs/design-principles.md#dp-3)) — in strata-g, 45 of 155 rows disagreed with their own decision's status, and two were filed under a category their header didn't claim. Prose lives in a `README.stub` with `{categories}`/`{table}` placeholders so humans still edit prose in markdown. Adding a decision is one new file with no shared edit; adding a TAG needs no code change at all. Every rendered field is rebased for the directory it lands in, so a link in a summary works from both the index and the one-level-deeper tag pages. Rejected: a fragment directory like changelog.d (the data is derivable, so generation beats collection — no step to forget). | Active |
+| [ADR-005](../../record/decisions.d/ADR-005.md) | Every document code, design principle and issue number cited in prose is a hyperlink, and `luria lint` fails on one that isn't; `luria link --fix` writes exactly the links the lint demands, from the same scanner, so the linter can never demand a rewrite the fixer wouldn't make ([DP-4](../../record/decisions.d/../../docs/design-principles.md#dp-4)). In the corpus this was extracted from, 2,246 references across 160 files were bare — and the split between linked and bare was random, which is worse than uniformly bare because a reader can't learn which references are worth clicking. Non-obvious rules, each found by a wrong rewrite: markdown isn't parsed inside a raw HTML block (those get an `<a href>`); backtick pairing is per-paragraph or one stray tick inverts code-vs-prose for a whole file; a low `#N` is ambiguous and stays bare without an explicit cue; fragment links resolve from the file the collector puts them in. Rejected: absolute URLs everywhere (breaks offline and non-GitHub reading), and a prose rule with no lint (the surface that drifted). | Active |
+| [ADR-006](../../record/decisions.d/ADR-006.md) | A referable document family — ADR, RFC, SPEC — is a `[luria.schemes.X]` entry naming a directory and an in-force status, not a hardcoded prefix. The annotation vocabulary follows: the verb is `inactive-ok`, not `adr-ok`, and a code carries its prefix (`ADR-012`, never `012`), with a bare number reported as an error rather than assumed. ADRs are the only scheme this package ships, so the short forms were available and would have baked one knowledge-management system into the vocabulary — the cost of the general form is one prefix per annotation; the cost of the specific one is a rename across every annotation the day a second scheme appears. Also configured: issue URL, code globs, fragment directories, and which files are dated records. Rejected: arguments threaded through every entry point (the second caller forgets one and the linter and fixer diverge — [DP-4](../../record/decisions.d/../../docs/design-principles.md#dp-4)). | Active |
+| [ADR-007](../../record/decisions.d/ADR-007.md) | Two standing reports — `luria ref-status` (references to retired documents) and `luria pending` (undecided decisions by age AND citation count) — are WARNINGS that never fail a build, with one summary line each from `luria lint`. Citing a `Rejected` decision is often exactly right, and a decision can be legitimately open for months, so only a human can judge a row; a guard that's wrong most of the time gets suppressed, and then the times it's right go unread. A deliberate reference is silenced by an `inactive-ok:` comment (line, `-block` or `-file` scoped), counted in the report rather than hidden, and reported when it stops applying. `luria reports` writes both in full for a CI artifact, because a warning with nowhere to be read is a warning nobody reads. Rejected: a lint error (fails CI on correct citations), a bot that auto-updates statuses (invents decisions nobody made), and a ratchet on a checked-in baseline (a file every contribution touches — [DP-2](../../record/decisions.d/../../docs/design-principles.md#dp-2)). | Active |
+| [ADR-008](../../record/decisions.d/ADR-008.md) | Comment directives share one parser, one shape — `<name>[-block|-file]: <args> — <reason>` — and one scope rule with no per-directive defaults: bare is the line and the line below, `-block` the run of non-blank lines it sits in, `-file` the document. `inactive-ok` acknowledges a deliberate reference to a retired document; `unexempt` is the inverse, putting a region the linter skips (a code block) back under it. The directive must OPEN its comment, `# noqa` style, and directive-SHAPED text is never a citation — both rules exist because documenting the syntax kept invoking it, four separate times. A first pass gave `unexempt` an implicit block scope so that a plausible example would parse; that bought one example and cost the rule its predictability, and was removed. Rejected: per-directive default scopes, and a wildcard that would mute a whole file including references added later. | Active |
+| [ADR-009](../../record/decisions.d/ADR-009.md) | Luria's decisions are renumbered from 001 and rewritten as decisions about Luria, each naming its strata-g ancestor as provenance rather than importing the original number. Porting the eight ancestor decisions verbatim would have carried a numbering with gaps that mean nothing here, bodies arguing about a graph tool, and cross-references to decisions that were never extracted. The evidence is kept — every principle and decision names the incident that earned it, because a rule whose evidence is missing reads as taste and gets re-litigated. Luria also runs its own machinery on its own record, so the first consumer to hit a bug is this repo. Rejected: importing numbers verbatim (dangling cross-references), and starting clean with no provenance (throws away the only thing that makes the rules persuasive). | Active |
+| [ADR-010](../../record/decisions.d/ADR-010.md) | Name the package **chester**, after Chesterton's Fence — the parable that a fence should not be removed until you know why it was put there, which is what a decision record is for. Superseded the same day by [ADR-011](../../record/decisions.d/ADR-011.md): the allusion names only the narrowest slice of what the record does (defending existing constraints), it survives being shortened to "chester" only for readers who already know the parable, and it frames the record defensively — as an argument against change — when its actual job is to make change cheap. Kept for the record, and as the corpus's worked example of supersession. | Superseded — by [ADR-011](../../record/decisions.d/ADR-011.md) |
+| [ADR-011](../../record/decisions.d/ADR-011.md) | Name the package **Luria**, after Alexander Luria and his case study *The Mind of a Mnemonist* — a man who could not forget. The name points at the faculty the package supplies (memory that survives the session) rather than at one failure it prevents, and the book carries its own cautionary half: Shereshevsky's total recall was a burden, because a record that never forgets and never abstracts becomes unusable. That tension is the design brief, not a flaw in the allusion. Supersedes [ADR-010](../../record/decisions.d/ADR-010.md) (chester, after Chesterton's Fence), whose allusion named only the narrowest slice of the job, survived shortening only for readers who already knew the parable, and framed the record defensively when its actual job is to make change cheap. | Active |
+| [ADR-012](../../record/decisions.d/ADR-012.md) v2 | Design principles are decomposed into one fragment each, with frontmatter carrying a `version`, the decisions that shaped them (`influenced_by`), and an `origin` note; `docs/design-principles.md` becomes a generated view. This is the same move as the decision index, not a third mechanism — a scheme gains a `render` setting, `index` (a table plus tag pages) or `document` (bodies concatenated). The distinction that matters is not frontmatter but whether the sources survive: a collected view (the changelog) consumes its fragments and can only be appended to; generated views are a pure function of sources that persist, which is the only reason `luria lint` can detect a stale one. Rejected: collecting principles like a changelog (the fragments would be deleted, taking the version history with them, and staleness would become undetectable), and leaving the document hand-maintained (a lock and a drifting projection, [DP-2](../../record/decisions.d/../../docs/design-principles.md) and [DP-3](../../record/decisions.d/../../docs/design-principles.md)). | Active |
+| [ADR-013](../../record/decisions.d/ADR-013.md) | A scheme's documents are named for their code alone — `ADR-013.md`, not `adr-013-a-documents-filename-is-its-code.md` — and the title moves into a `title:` frontmatter field, which the generated views prefer over the body's H1. A slug in the filename is a third copy of the title that no tool reads, that a rename plus every inbound link is required to correct, and that therefore never gets corrected. The body H1 stays, because someone opening the file alone needs a heading, so `luria lint` guards that the two agree — rung 2 of [DP-3](../../record/decisions.d/../../docs/design-principles.md#dp-3), since rung 1 isn't available. Filename decoding, which had accumulated five separate copies, is now `Scheme.documents()` alone, and it reads legacy slug filenames so adoption isn't a rename-everything-first proposition. Rejected: dropping the H1 (unreadable on its own), and enforcing the short filename on adopters (a convention choice, not a defect). | Active |
+| [ADR-014](../../record/decisions.d/ADR-014.md) | A reference whose code names no document here was silently skipped: the fixer can't link it, so the lint — which never demands a rewrite the fixer wouldn't make — said nothing. That silence hid ten stale strata-g numbers left in ported docstrings, one of them a link to a file that does not exist. Such codes are now counted in `luria ref-status`, `luria lint` and the CI report, as a WARNING: a typo, a foreign project's decision and an illustrative example look identical to a scanner and only a human can tell them apart. `unresolved-ok:` retires a deliberate one, at the same three scopes as `inactive-ok:` and with the validity check inverted — it must name a code that *doesn't* resolve. Codes inside URLs are masked, because linking out to another project's [ADR-013](../../record/decisions.d/ADR-013.md) is the correct way to cite a foreign document. Rejected: a lint error (a foreign citation is often right), and inferring a URL for unresolvable codes (silently wrong on a typo). | Active |
+| [ADR-015](../../record/decisions.d/ADR-015.md) | Another project's decision is cited as `SG-ADR-032` — a registered remote prefix composed with that project's own code — and a `[luria.remotes.SG]` entry teaches Luria to build the URL, so `luria link --fix` writes it and `luria lint` demands it exactly as for a local code. This is the alternative [ADR-014](../../record/decisions.d/ADR-014.md) rejected, and what it was missing is a **lockfile**: a remote whose filenames carry title slugs can't be resolved by any template, but it can be *discovered* — from a local clone, or the GitHub contents API, reading the remote's own `luria.toml` for where its documents live — and the code→filename map committed so CI and offline checkouts resolve identically. `luria remotes --check` probes reachability; it is a separate command, never part of `luria lint`, because a check that opens a socket fails on a train. Rejected: a live lookup (flaky, and useless for a private remote), and a flat second scheme (loses which project a code belongs to). | Superseded — by [ADR-016](../../record/decisions.d/ADR-016.md), which drops the local-clone discovery path and makes Luria its own worked example |
+| [ADR-016](../../record/decisions.d/ADR-016.md) | Supersedes [ADR-015](../../record/decisions.d/ADR-015.md), keeping its core — a foreign record is cited as `LU-ADR-013`, a registered prefix composed with that project's own code, and the config builds the URL — and dropping the part that bent the tool around one repository. Discovery reads **public HTTPS only**; the local-clone option is gone, because a resolution that depends on what happens to be on somebody's disk is not reproducible and quietly made the ancestor's pre-convention shape Luria's problem. Luria registers **itself** as remote `LU`, which the `luria init` scaffold cites instead of pasting URLs, so the mechanism is exercised by the package rather than only by its tests. Also: `version:` becomes standard frontmatter for every scheme, not just principles, shown in the index only when it isn't 1; and `*.stub` files are linted, closing a hole where hand-written prose rendered into a page the lint skipped for being generated. Rejected: keeping the clone path behind a flag (the reproducibility problem is the same), and a credentialed fetch. | Active |
+| [ADR-017](../../record/decisions.d/ADR-017.md) | `SG-ADR-032` stays in the prose even though that URL 404s today: strata-g's filenames still carry title slugs, and the code-only convention Luria builds against is what strata-g will use once its record is ported. The reference is therefore correct and merely early. Naming a foreign document is the durable half — which project, which decision — and it survives whatever the URL does; dropping the citations to avoid a broken link would throw away the meaning to protect the plumbing. Two remotes are registered, `SG` and `LU`, and their difference is the point: `LU` is public and already on the convention, so `luria remotes --check` verifies it for real, while `SG` reports as unverifiable and stays that way until the port. Rejected: a hand-authored lockfile (a drifting projection with no guard, since the repo is private), and de-prefixing the citations back to prose (unresolvable *and* unnameable). | Active |
+| [ADR-018](../../record/decisions.d/ADR-018.md) v2 | The two decorative badges ("generated index", "versioned") said nothing a reader couldn't guess and could never be wrong, which makes them furniture. They are replaced by the two numbers the record actually has to answer for — **needs decision** (`Proposed` + `Deferred`, across every scheme) and **cited but retired** (retired documents still cited without an acknowledgement) — baked into static shields URLs that `luria index` rewrites and `luria lint` checks for staleness. Derived, not hand-written: rung 1 of [DP-3](../../record/decisions.d/../../docs/design-principles.md#dp-3). `luria pending` was generalized to every scheme in the process, since a `Proposed` principle is an open question exactly as a decision is. Rejected: a shields endpoint reading a committed JSON file (it always reports the default branch, so the count can't move in a reviewer's diff), and a live query (nothing outside this repo can compute either number). | Active |
+| [ADR-019](../../record/decisions.d/ADR-019.md) | Two ways a decision record can be wrong, and only one of them is a supersession. If the **choice** changes, add a new decision and retire the old one — the rule [ADR-001](../../record/decisions.d/ADR-001.md) has always stated. If the choice stands but a **reason** for it turns out to be wrong, correct the body in place, bump `version`, and say what changed in `history:`. Superseding over a bad argument is theatre: it retires a decision still in force, and every citation of it has to be repointed at an identical claim. Leaving the argument standing is worse, because a wrong reason is exactly what gets quoted at the next person. The version field makes the correction visible, which is the whole reason "never rewrite a body" exists — the objection is to *silent* revision, not to being wrong out loud. Rejected: superseding for any change (churn, and it makes the status vocabulary lie), and correcting silently (indistinguishable from rewriting history). | Active |
+| [ADR-020](../../record/decisions.d/ADR-020.md) | The devlog stops being a collected view and becomes a **journal**: entries live at `devlog.d/yyyy/mm/dd/hhmmss.md`, persist, and are rendered into one generated book per period plus an index. Identity is the authoring timestamp, so there is no number to assign and no name to collide on; ordering is a pure function of the tree rather than of commit order, which a rebase can change. Entries carry the standard frontmatter — `title:` is what each book's contents list shows — and `luria lint` checks the path agrees with `created:`. Rejected: a dated file per period appended to directly (two branches in the same month still conflict, which is most of them), a single growing `docs/devlog.md` (8,281 lines in 40 days at the pilot's rate), and slugs in the filename (a second name for the thing `title:` already names, [DP-3](../../record/decisions.d/../../docs/design-principles.md#dp-3)). | Active |
+| [ADR-021](../../record/decisions.d/ADR-021.md) | The repository layout is split along what a person is doing: `docs/` holds everything a reader browses — prose and every generated view — and `record/` holds everything a contributor files, each container inside carrying the `.d` suffix as the visual affordance that you have crossed into the write domain. A scheme gains a separate `output` so its index renders into `docs/` while its sources live in `record/`; the stub and `tags.yaml` move to the source side, so a view directory holds only what the generator wrote — which turns "don't hand-edit" from a comment into a lint. Rejected: marking sources with `.d` at the top level (four write locations, no single answer to "where do I file"), segregating by *project* into a `meta/` directory (the wrong axis — it split ours-vs-theirs when every repo's actual confusion is read-vs-write), and burying the write root as a dotfile (contributors work there daily). | Active |
+| [ADR-022](../../record/decisions.d/ADR-022.md) | The `url-ok` directive — and the warning it acknowledges — applies only to links whose label is a composed foreign code (`SG-DP-18`), never to local codes or arbitrary hand-targeted links. Three reasons: a warning needs a well-defined wrong, and only the remote namespace has one (a foreign code has exactly one constructed URL, so "differs" is a meaningful binary; a local code has a family of legitimate targets, so the same check would flag correct links until acknowledgement became reflex); the risk profiles differ (a local link fails loudly when its target moves, a remote hand URL fails silently, and the directive exists to compensate for the silent case); and the local want has a better answer the repo already models — register yourself as a remote, the way Luria registers `LU`. The underlying asymmetry: a local hand URL restates a fact the machinery already owns, so the remedy is mechanical, while a foreign hand URL carries a fact the construction has no home for. That reframes the directive's role: each `url-ok` reason describes a gap in what remote config can express, and a recurring shape is the cue to grow the config — per-scheme remote mappings are the known first candidate — not to keep annotating. | Active |
+| [ADR-023](../../record/decisions.d/ADR-023.md) | A remote gains per-scheme construction: `[luria.remotes.X.schemes.Y]` maps one code family to `dir` (file per code), `document` plus an `anchor` template (sections of one assembled page), or a `url` template. The remote model had assumed one directory of code-named files, so a document-rendered scheme's codes constructed confident URLs to files that never existed — the gap [ADR-022](../../record/decisions.d/ADR-022.md) predicted `url-ok` reasons would accumulate. The anchor template defaults to `dp-{number}`-shaped stable anchors, which is what Luria's own document render emits, so a remote on current conventions needs one `document` line. The lockfile's authority stays scoped to what discovery can see — files — so an anchor construction never consults it. Rejected: zero-config prefix magic (a default is a guess about the remote, and a legacy remote would get confidently wrong anchors; explicit config is a claim by the user), and anchor discovery by fetching the document (network in the resolution path, useless for private repos). The residue — legacy heading-derived anchors no template can compute — remains `url-ok`'s jurisdiction, now excusing only the anchor. | Active |
+| [ADR-024](../../record/decisions.d/ADR-024.md) | A remote need not hold a Luria-shaped record. Give it a `uid` regex and its references are the prefix, a configurable `delim` and whatever the pattern matches — an arxiv id, a ticket key — constructed through the `url` template, which can address the uid's capture groups by position (`{1}.{2}`) or take the whole tail as `{0}`/`{uid}`. A uid is exact and is never normalised: zero-padding an arxiv id would quietly cite a different paper. One rung only — no lockfile, no code-only convention, and a uid remote without a template constructs nothing rather than guessing. The refactor this forced was overdue anyway: one combined regex with a hardcoded hyphen became per-remote patterns behind `references()` and `parse_code()`, so the delimiter and tail shape are spelled in one place. Rejected: overloading `schemes` for uid families (a scheme implies documents with statuses and an index; an arxiv paper has neither), and auto-linkifying unregistered shapes (an unconfigured prefix must never match). | Active |
+| [ADR-025](../../record/decisions.d/ADR-025.md) | `[[ADR-013]]`, `[[SG-DP-18]]`, `[[ARXIV-2403.05530|the report]]` — wikilink brackets are the author asserting "this is a reference, link it", and the assertion changes the rules on both sides. Inside the brackets no prose heuristics apply: a bare `DP-3` (no `#`) resolves, a low `[[#10]]` needs no cue, any registered remote shape works. And an unresolvable wikilink is a lint violation the fixer cannot clear — the one deliberate exception to "the lint never demands what `--fix` won't do", because an explicit request deserves an explicit refusal rather than a silent skip. Wikilinks are consumed: `luria link --fix` rewrites them to ordinary markdown links (an `<a href>` inside raw-HTML blocks), because GitHub renders `[[…]]` as literal brackets and source files must read as plain markdown wherever views aren't generated. Rejected: expanding at view-generation time (fails everywhere sources are read directly), and heuristic-free auto-linking without brackets (already rejected in [ADR-024](../../record/decisions.d/ADR-024.md) — this is the sanctioned way to opt a single reference out of the heuristics). | Active |
+| [ADR-026](../../record/decisions.d/ADR-026.md) | Parallelism lands as one primitive — `parallel.pmap(fn, items)`, a thread pool that returns results in input order — applied at three seams: render units in `outputs()` (a scheme, a journal), per-file scans in the bare-reference lint, and per-URL probes in `remotes --check`. Measured honestly: the probes are the real win (6.6s → 2.9s, round-trips overlapped); renders and scans are a wash at today's cardinality, because that work is regex-CPU under the GIL — those seams are structure bought now, cheap, against the growth the issue anticipates. Threads not processes (the winning workloads are I/O; processes add pickling and spawn cost for no measured gain), ordered results not as-completed (the staleness diff and the lint report must read identically at any width), and `LURIA_JOBS=1` as the serial escape hatch. If render units ever measure in seconds, the `pmap` seam is where a process pool swaps in. | Active |
+| [ADR-027](../../record/decisions.d/ADR-027.md) | Luria publishes to PyPI through GitHub's trusted publishing: a `publish.yml` workflow whose `pypi` environment's OIDC identity is the whole credential — no token exists to leak, rotate or forget. Build and publish are separate jobs; the artifact that ships is the artifact that passed a cold-install smoke test (`pip install dist/*.whl`, then `init → index → journal new → lint` in an empty directory), which is the guard against shipping a `luria init` that only works from a checkout. The scaffold ships *inside* the package (`luria/template/` in the wheel, via hatchling force-include) while staying top-level in the repository where a visitor browses it ([ADR-021](../../record/decisions.d/ADR-021.md)) — the setuptools parent-relative package-data it replaces leaked a bare `template/` into site-packages, functional only by collision-prone accident. Publishing fires on a GitHub release (plus manual dispatch); the sdist carries build inputs, not the record — the record's browsing surface is the repository. | Active |
+

luria-0.1.0/docs/devlog/README.md

@@ -0,0 +1,30 @@
+<!-- GENERATED by `luria index` from record/devlog.d/ — edit the entries, not this file. -->
+
+# Development log
+
+The narrative that doesn't fit a changelog entry: root-cause archaeology, failed approaches, verification details, and the traps the next person would otherwise rediscover. Generated from the entries in `record/devlog.d/` — file one with `luria journal new "A title"`.
+
+## Currently — [August 2026](2026-08.md)
+
+- [4 Aug 18:44 — Shipping: the wheel that worked was working by accident](2026-08.md#20260804184404)
+- [4 Aug 18:18 — Parallelism measured first: the probes were the win, the rest is seams](2026-08.md#20260804181814)
+- [4 Aug 18:12 — Wikilinks: the brackets are consent, and typing them flips the rules](2026-08.md#20260804181244)
+- [4 Aug 17:29 — Numbers were the special case: uid remotes and one parser for a code's anatomy](2026-08.md#20260804172947)
+- [4 Aug 17:09 — A remote learns its schemes, and the url-ok loop closes on schedule](2026-08.md#20260804170921)
+- [4 Aug 15:37 — The read/write boundary: record/ for filing, docs/ for reading](2026-08.md#20260804153748)
+- [4 Aug 03:44 — The devlog becomes a journal, and the migration's timestamps came from the commits](2026-08.md#20260804034408)
+- [4 Aug 03:27 — A decision cited as a principle](2026-08.md#20260804032711)
+- [3 Aug 22:56 — Two badges that could never be wrong, replaced with two that can](2026-08.md#20260803225648)
+- [3 Aug 22:13 — Foreign decisions get a namespace, and the first version bent the tool around one repo](2026-08.md#20260803221327)
+- [3 Aug 21:50 — Four bare codes were a hole in the lint with ten real defects in it](2026-08.md#20260803215013)
+- [3 Aug 21:19 — The filename is the code, and the rename removed a copy rather than adding one](2026-08.md#20260803211926)
+- [3 Aug 21:02 — Principles become fragments, and collected turns out not to mean generated](2026-08.md#20260803210211)
+- [3 Aug 20:35 — Extracting the project-memory framework out of strata-g](2026-08.md#20260803203505)
+
+## All books
+
+14 entries across 1 book, newest first.
+
+| Book | Entries | First | Last |
+|---|--:|---|---|
+| [2026-08](2026-08.md) | 14 | 2026-08-03 | 2026-08-04 |

luria-0.1.0/luria/__init__.py

@@ -0,0 +1,11 @@
+"""Luria — a project's memory, kept where the next collaborator will find it.
+
+The four layers (design principles, decisions, changelog, devlog), the fragment
+convention that keeps them conflict-free, the generated views, and the lint that
+stops all of it from drifting.
+
+Public surface is the CLI (`luria --help`); the modules are importable for
+projects that want to extend a check rather than replace it.
+"""
+
+__version__ = "0.1.0"