dmarx / dmarx/luria

Contract transitions: report the obligations a semantic edit introduces (gated on a measured case)

Open
#185 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
21
Forks
2
Avg merge
4h 13m
Merged PRs (30d)
98

Description

Split from #141 (Proposal 7), which is closed. Kept open as its own narrow issue so the idea and its gate survive the umbrella.

## The idea

Once a document's contract is a function of its own values (ADR-082: `required_when`), a change to those values has computable consequences. Moving `status: Proposed → Superseded` introduces `superseded_by:`; adding a tag that carries an obligation introduces that obligation. The proposal was to compute the difference between the contract before and after an edit and report what the edit newly demands — at the moment of the edit, rather than as a lint finding discovered later.

Two constraints from the original that still hold:

- **Removing an obligation must not delete information.** If the condition that required `evidence:` stops holding, the field stays. Contracts constrain validity; they do not synchronise destructively. (ADR-082 already defers the related question of a condition that outlives its status.)
- **No new semantic core.** Whatever computes the diff reads the same compiled contract the lint reads (`contract.py`), or it is a second implementation of "what does this scheme demand".

## The gate

Nothing here is built until a record produces the failure it would have prevented: an author changes a status or a value, the newly required field goes unfilled, and the lint catches it only later or not at all. Today `luria lint` reports the unfilled field on the next run, which may be enough; this issue is for the case where it measurably is not.

When that case exists, the question to answer first is *where the report lands* — `luria lint` already runs on every branch, so a transition report is only worth having if it is read somewhere the lint is not (an editor, `luria new`, a pre-commit hook).

## What is not in scope

A general `[[constraints]] when = …` language, precedence between sources, or inference of one value from another — all rejected on #141 and again in ADR-082's alternatives.

Contributor guide

Open the contributing guide

Research direction

Start by reading ADR-082 and contract.py, then run luria lint to understand the existing contract evaluation and when unfilled fields are reported. Before implementation, identify a measured case where lint is too late or insufficient and determine whether the report belongs in an editor, luria new, or a pre-commit hook. Done means the case and report destination are established without adding a second contract implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.