luria

One scaffold for every entry kind — `luria new`, driven by the config

4 min read

Graph View

ADR-036: One scaffold for every entry kind — luria new, driven by the config

Status Active · Version 2 · Filed 2026-08-07 · Issue #42 · Influenced ADR-048 · ADR-049

Context

Entry creation was mediated for exactly one layer: luria journal new stamped a devlog entry’s timestamp-path and frontmatter. The other layers had the same shape without the tooling — decisions and principles are “copy _template.md to the next free number” instructions in CLAUDE.md, and changelog fragments carry a branch-slug naming convention a contributor reconstructs by hand (#42).

Review on ADR-030 named the generalization: every scheme a project associates with its record is already discoverable in the config, so any prefix-coded scheme could have its fragments templated and new entries mediated by the CLI — and the journal-only command was the special case pretending to be the feature.

Decision

luria new [kind], where the kinds are the config. Journals by name, schemes by lowercased prefix, fragment directories by their basename minus .d. A project that adds [luria.schemes.RFC] gets luria new rfc with no code change, and --help lists what this project scaffolds.

Compute identity, never content. The command fills in exactly what a machine can know — the next free number, the timestamp path, today’s date:, the fragment’s timestamped filename (v2; see history:) — substitutes the real code for the template’s <PREFIX>-NNN placeholders, prints the path, and stops. A fragment is authored in a markdown-aware editor; the CLI’s job ends at handing over a file that will pass the lint’s structural checks.

Fields are settable, not demanded. --title, --status, --summary, --tags write frontmatter inline — useful for a tool driving the CLI — and --title keeps the body heading in agreement so the scaffold never fails the title check it just created. Nothing prompts; nothing is required.

A fragment is named for its filing moment (v2; see history:), the identity the devlog already uses, so two contributions can never collide on a name. An explicitly --named fragment is an address: asking for it again reopens it rather than duplicating it. Two stamped fragments from one contribution is fine — they collect into the same dated batch, so the ADR-002 reading intent is preserved by the collector rather than by filename discipline.

luria journal is removed, not shimmed (ADR-030): luria new is the scaffold, luria index renders the books, and python -m luria.journal remains for the interactive look at what is filed.

Alternatives considered

  • Interrogate for fields on the command line — the journal command’s posture (luria journal new "A title" demanded the title). Rejected by the review that prompted this: documents have multi-field frontmatter, and a human authors it in an editor after the file exists; a required positional argument just makes the scaffold harder to reach.
  • Hardcode the three known kinds. Simpler dispatch, and it breaks the moment a project configures a second scheme or journal — the exact one-command-per-thing drift ADR-030 removed, rebuilt one layer down.
  • Keep luria journal beside luria new. Two spellings of one scaffold, one of them narrower — the projection that drifts (DP-3), on the CLI surface that was just cleaned.
  • Generate from parsed-and-redumped YAML instead of line substitution. Structurally cleaner, and it strips the templates’ teaching comments — which are most of what a template hands a first-time author.

Consequences

  • The contributor surface stays at six commands: journal leaves as new arrives, and the scaffold instructions in CLAUDE.md, the README table and the template scaffold now say luria new.
  • The lint’s journal remedy (“run luria new to file entries”) and the publish smoke test use the new spelling.
  • A scheme with no _template.md still scaffolds: a minimal lint-passing fallback (status, title, tag, date, agreeing heading), so luria new works in a project that deleted the teaching templates.
  • This decision’s own changelog fragment and devlog entry were filed with luria new — the guard fired before being trusted (DP-6).

Backlinks