Skip to content

fix(config): say the metadata axes govern what is written next, not that they rewrite - #4

Merged
adammharris merged 1 commit into
mainfrom
agent/backlog-metadata-axes-claim-a-rewrite
Oct 20, 2026
Merged

adammharris merged 1 commit into
mainfrom
agent/backlog-metadata-axes-claim-a-rewrite

Conversation

@adammharris

Copy link
Copy Markdown
Member

What changed

config_schema.rs showed this sentence on metadata.format and metadata.embed, both on the row and as the Confirm consequence a frontend reads before Apply:

Rewrites the metadata of every document in the workspace.

Both now say what applying the change actually does. For example, metadata.format:

Applies to metadata written from now on: a new document takes its parent's format. Existing documents keep theirs until converted with prov convert <root> metadata.format <value> -r.

metadata.embed gets the same sentence, saying "shape" and metadata.embed. The doc comment on rules::costly no longer says every costly axis rewrites the workspace.

Why

Nothing on Apply rewrites anything. prov's rule for a config axis (prov/docs/config-vocab.md, "Restating existing documents") is that the setting governs what is written next, and prov convert … -r is a separate, deliberate step. A warning that overstates is one people learn to click through. This takes option 1 of the task, "Say what happens".

Tint (Warning) and severity (Confirm) are left as they were. The task suggested a Notice might be the more honest weight, and that call is left to a maintainer.

Closes

docs/tasks/metadata-axes-claim-a-rewrite.md (marked status: done in this branch, with a status note).

The task also asks for the reference axes to be checked against the same rule. references.notation, references.path_style and references.target (and their relations.* overrides) still say "Rewrites every link in the workspace.", and that is just as untrue. This PR leaves them alone: target has no prov convert axis, and wikilink is offered for notation but isn't one of prov convert's documented values, so their sentences need a decision first.

Verification

  • New test a_metadata_axis_says_it_governs_what_is_written_next. It failed before the fix and passes after. For both axes it checks that the sentence makes no rewrite claim, says existing documents keep their spelling, names the exact prov convert command, and matches the consequence Apply reads.
  • ship ci: all 6 jobs pass (fmt, clippy -D warnings, test, docs, package-isolation, MSRV).
  • prov check gives the same 2 findings as on main: retired view keys in config/prov.yaml. This change doesn't touch them.

…hat they rewrite

The consequence on `metadata.format` and `metadata.embed` claimed a rewrite of
every document, which nothing on Apply performs. Both now state prov's rule: the
setting applies to metadata written from now on, a new document takes its
parent's carrier, and existing documents keep theirs until
`prov convert <root> metadata.<axis> <value> -r`. A test holds the row's
description and the consequence Apply reads to that sentence.

Closes docs/tasks/metadata-axes-claim-a-rewrite.md.

Behavioural-change: the description and on-change consequence message for metadata.format and metadata.embed in config_schema are new sentences; tint and severity are unchanged.
@adammharris
adammharris merged commit e8705a7 into main Oct 20, 2026
7 checks passed
@adammharris
adammharris deleted the agent/backlog-metadata-axes-claim-a-rewrite branch October 30, 2026 01:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant