CLAUDE.md

Luria is a CLI that keeps a project’s memory — and this repository is its own first user: the record here is scaffolded, generated, and linted by the code in luria/. This file is a map, not a manual; when it disagrees with luria --help or the docs, it is this file that is wrong.

Orient first:

• Run luria --help — the live command surface; every command takes --help.
• Project memory — the model: sources vs. generated views, schemes, journals, fragments, remotes, and how references are checked.
• The record — this project’s own configuration, generated: what kinds of entry exist and what to type to file one.
• Decisions and design principles — why things are the way they are. Check here before re-deriving or re-litigating a choice.
• Comment directives — how to acknowledge a lint finding deliberately instead of working around it.

Working agreements

• Work goes to a branch and a pull request, never straight to main. The record is the deliverable; it needs a chance to be read before it becomes what the project believes.
• File the record entry in the same contribution as the work (luria new): a changelog fragment for the change, a devlog entry for anything the next person would otherwise rediscover, a decision document when a real alternative was rejected. Filed with context loaded it costs a paragraph; re-derived cold it costs a session.
• Never edit a generated file. Anything stamped GENERATED is rebuilt by luria index; edit the sources and rerun it. The README’s generated regions are rebuilt too, and so is everything below, derived from this record’s configuration:
  • the ADR index and its per-value pages: docs/decisions
  • the DP document: docs/design-principles.md
  • the Development log books: docs/devlog
  • the bootloader view: CLAUDE.md
  • the status reports: docs/reports
  • the record description: docs/record.md
  • the configuration reference: docs/configuration.md
• Never hand-write a link target for a code. Write the bare code and run luria link --fix; record prose renders into views in other directories, so only the fixer knows the frame a target must resolve from. Codes in backticks are mentions, not citations, and are left alone.
• A guard that keeps catching you is a bug report about the workflow. One catch is the net working; the same catch twice means the hazard is upstream, and the fix is to remove what generates the mistake, not to keep thanking the net.

Developing the package

python -m pytest tests -q plus luria lint is what CI runs. A new check joins the lint only if the violation is always wrong and mechanically fixable; anything needing judgement is a report with an acknowledgement directive. Fire any new guard once on a real case before trusting it, and say so in the devlog.

Principles in force

The standing values decisions cite by number, derived from the record so this list cannot name a retired one or miss a new one. The argument behind each is in the design principles.

• DP-001: No silent refusal
• DP-002: One artifact, one writer — hand out fragments, generate the view, and generate it where merges serialize
• DP-003: A hand-maintained projection of a source of truth will drift — derive it
• DP-004: One authoritative implementation, read the same way everywhere
• DP-005: Culture must be compiled
• DP-006: Fire before trusting
• DP-007: No private brains
• DP-008: File it in the same contribution as the work
• DP-009: Structure is read before text — spend affordances deliberately
• DP-010: Defaults follow the failure mode: guards opt out, disclosures opt in
• DP-011: It’s not mine, but I’ll pick it up anyway
• DP-012: One document, one thing
• DP-013: Exempting a ledger from one matcher exempts it from none of the others
• DP-014: Meet the project where it is
• DP-015: An absence reads exactly like a success — give the silent case a signal
• DP-016: An awkward structure is reporting a distinction the model has stopped expressing
• DP-017: A record states what is true now — git already keeps what was written then