chemenu/raw/notes/Conversation Transcript - Write-Once Frontmatter Fields and touch --set Session 2026-08-31.md

# Conversation Transcript - Write-Once Frontmatter Fields and touch --set Session

> Source: Claude Code session (`claude-opus-5`), llm-wiki-test1 workspace
> Collected: 2026-08-31
> Participant: Torben
> Fidelity: **faithful summary transcript, not a verbatim log.** Torben's three design
> decisions are recorded verbatim as the options he was shown and the ones he chose; command
> output quoted below is real; the assistant's reasoning is condensed.
> No second-hand material. No credentials appeared in the session.
> One of two transcripts cut from this stretch of the session; the other covers the
> Mass-Update Gate's counting rule and the measured iteration-budget calibration.

Covers Gitea issue #14, implemented as `touch --set/--add/--remove` in stack `1.4.0`
(`dbe2f73`). Issue #14 closed, #16 opened for the part deliberately left out.

---

## Turn 1 - "Führe 14 aus und lege mir die nötigen Entscheidungen jeweils mit Hintergrund vor"

The assistant read `touch.py` before proposing anything, and found the groundwork already in
place: `validate_fields()` validates **per field** rather than per document, which is exactly
what a `--set` needs. Its docstring explains why - whole-document validation would refuse to
bump `modified:` on a page that is invalid for some unrelated reason, "which is exactly the page
most in need of maintenance".

Three decisions were put to Torben, each with the trade-off spelled out.

### Decision 1 - which fields may `--set` write?

| Option | Consequence |
|---|---|
| **Denylist** (chosen) | Everything the schema declares, minus a short reasoned block list. A field added to a type-spec works immediately. |
| Allowlist | A maintained set of writable fields. Safer against surprises, but every new schema field needs a code change. |
| Denylist minus the already-flagged fields | Also blocks `summary`/`provenance`/`confidence-base`, which have their own options. Prevents two ways to do one thing, at the cost of a surprising refusal. |

**Torben chose the denylist.** The argument that carried it: an allowlist is a second copy of
the schema, and the copy is the one that drifts - AGENTS.md invariant 8 applied to a constant.

Blocked, each naming the command that owns the field instead:

- `type:` - changes the page's schema *and* its directory; that is `page-lifecycle.md`.
- `confidence:` - derived from `confidence_base` by decay, not authored.
- `related:`/`sources:`/`entities:`/`concepts:` - `xref` maintains the reverse direction and
  the body bullets; a bare frontmatter write would leave the other half stale.

### Decision 2 - what does `--set tags=a,b` mean for a list that already has values?

| Option | Consequence |
|---|---|
| Replace only | One rule. Adding a single tag means naming the whole list. |
| **Replace plus `--add`/`--remove`** (chosen) | Three options instead of one, but a single element can be changed without reading the list first. Leaves open what `--remove` does with an absent element. |

**Torben chose replace plus `--add`/`--remove`.**

The open sub-question - `--remove` on an element that is not there - the assistant decided
itself and said so: **it succeeds and reports it.** Idempotent like `xref remove`, because a
repair command that refuses to run twice is one nobody dares script; but never silent, because a
silent no-op looks exactly like a successful removal, and that is how a mistyped element name
hides.

### Decision 3 - does this pass also deliver `raw rename`?

| Option | Consequence |
|---|---|
| **`touch --set` only** (chosen) | Stays `size/S`. The file move becomes possible in two steps (`git mv`, then `touch --set raw_files=…`). The remaining gap gets its own issue. |
| Both in one release | Closes #14 fully and removes the intermediate state, at `size/M`: backward search over all `raw_files:` references, behaviour with multiple owners, contract lines for two commands. |

**Torben chose the narrower pass.** `raw rename` became issue #16 (`prio/2`, `size/S`).

---

## Turn 2 - implementation

### What moved

`_coerce_set_value`, `_parse_set_fields` and `_check_raw_files_exist` left `new_page.py` for
`commands/_util.py` and lost their leading underscores. Two commands, one implementation -
otherwise `touch --set` would have inherited the comma bug from #12 on day one. A test covers
exactly that: an existing raw file whose name contains a comma, referenced through `\,`, read
back as a single path.

`raw_files:` written by `touch` gets the same filesystem existence check `new` performs. It is
I/O, not a data shape, so no schema can express it.

### Two refusals, deliberately worded differently

A blocked field is a routing problem, so the message names the command that owns it. An unknown
field is a typo or the wrong page type, so the message lists what the page actually has - the
value is learning that `tags` was meant:

```
$ tools/wikitool touch --page "Diff-Reviewable Agent Edits" --set "sources=Source - X"
ERROR `sources` cannot be set with --set: page-reference field - use `wikitool xref add` / `xref remove`

$ tools/wikitool touch --page "Diff-Reviewable Agent Edits" --set "tag=x"
ERROR Type types/concept.md declares no field 'tag'.
  Settable fields for this page: concept_type, confidence_base, created,
  modified, provenance, summary, tags
```

### A test-harness trap, fixed once

The existing `test_touch.py` called the Typer callback directly with a full argument list, so
three new options broke seven call sites with `TypeError: 'OptionInfo' object is not iterable`.
A callback invoked directly receives `OptionInfo` objects for whatever the caller omits - the
same hazard `dist_cmd.py` avoids by keeping its logic beside the wrapper. The tests now go
through a `_touch(**overrides)` helper that supplies every option, so the next option costs one
line rather than seven.

---

## Turn 3 - the repair that proves it

`kb/concepts/Diff-Reviewable Agent Edits.md` had been created hours earlier by an ingest whose
`--set tags=` value carried a trailing comma; everything after the separator was lost. That
subagent correctly worked through all three ways out and rejected each: `touch` could not set
`tags:`, hand-editing frontmatter comes too close to invariant 1, and `rm` + `new` would have
broken the `concepts:` reference the source page already held. The page kept `[agent-workflow]`
permanently, because of a comma.

Against the real corpus:

```
$ tools/wikitool touch --page "Diff-Reviewable Agent Edits" --add "tags=context-engineering,tooling"
  tags: added 'context-engineering', 'tooling'
OK Touched kb/concepts/Diff-Reviewable Agent Edits.md

$ tools/wikitool touch --page "Diff-Reviewable Agent Edits" --add "tags=context-engineering" --no-date
OK 'Diff-Reviewable Agent Edits' already up to date; nothing to change.

$ tools/wikitool touch --page "Diff-Reviewable Agent Edits" --remove "tags=vertippt" --no-date
  tags: not present, nothing removed: 'vertippt'
OK 'Diff-Reviewable Agent Edits' already up to date; nothing to change.
```

The page now carries `[agent-workflow, context-engineering, tooling]`.

---

## The defect this closed, stated once

A field `new` wrote once - `tags:`, `raw_files:`, `source_url:` - was afterwards unreachable.
`touch` did not know it; hand-editing frontmatter is what the tool exists to prevent; deleting
and recreating the page breaks every reference already pointing at it. And `new` is **not
idempotent**, so the window to get the value right was exactly one command wide.

The evidence that this was a rate rather than an accident: three failures across three
consecutive ingests on the same day, at two different fields, by three different agents. One of
them was a trailing comma.

---

## Outcome

| Artifact | Result |
|---|---|
| Stack version | `1.4.0` (MINOR - new capability, backwards compatible) |
| Commit | `dbe2f73` - 9 files |
| Tests | 674 passing, in the normal and the hardened environment |
| Gitea | #14 closed with the three decisions recorded; #16 opened (`prio/2`, `size/S`) |
| Corpus | The unrepairable page repaired |