chemenu/raw/notes/Conversation Transcript - Comma Bug, Budget Refund and Lint Report Path Session 2026-08-31.md

Conversation Transcript - Comma Bug, Budget Refund and Lint Report Path 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. Reconstructed by the assistant at the end of the session. Torben's instructions are quoted verbatim where they are short; the assistant's reasoning is condensed. Command outputs quoted below are real. No credentials appeared in the session. One of three transcripts cut from the same session; the other two cover issue triage and planning, and the harness's auto permission mode.

Covers the fix for Gitea issues #12 and #13, the second defect it uncovered in frontmatter serialization, and the restoration of a raw file that had been renamed to work around the bug. Resulting commits: 40adbb7 (stack 1.2.0), 5426a6e (content correction). Gitea issues #12 and #13 were closed by this session; issue #14 was opened from a gap it exposed.

---

Turn 1 - /stack-dev "Fixe 12 und 13. verdopple die Tool call Limits zusätzlich."

Torben had just received a rough prioritisation of all open issues (see the companion transcript on issue triage) and picked the top two off it. The added instruction: "verdopple die Tool call Limits zusätzlich. Wir sind da schon immer sehr knapp unterwegs."

The assistant read the affected code before touching it: commands/_util.py, commands/new_page.py, commands/run_budget.py, commands/lint.py, cli.py, tools/CONTRACT.md, instructions/gates.md.

Issue #12 - --set cannot express an array value containing a comma

parse_list() split hard on , with no escape. Shell quoting is no help: the quotes are gone long before the value reaches the parser. A raw_files: path with a comma in the filename was therefore not expressible, and during the ingest of 2026-08-30 the raw file had been renamed to fit the flag - a violation of raw/CONTRACT.md's immutability rule.

Both proposals from the issue were implemented, because they serve different cases:

• \, is a literal comma that survives the split, implemented as a lookbehind (re.compile(r"(?<!\\),")) plus an unescape per element. This also reaches xref add --entities, which uses the same helper.
• Repeating --set for an array field now appends instead of replacing. Scalar fields keep "last one wins" - there is nothing to append to. This is the separator-free form and therefore the right one when an element contains a comma.
• _check_raw_files_exist now names the comma split as the cause and both ways out, explicitly including "never rename the raw file to fit the flag".

The second defect, found by the test rather than by the issue

The end-to-end test - create a raw file whose name contains a comma, reference it with \,, read the written page back - still failed. Escape and append were correct; the file was not.

dump_frontmatter writes lists in flow style ([a, b]), but _format_scalar decided on quoting using a document-level round-trip probe, where a comma is an ordinary character. Inside [...] it is an indicator:

raw_files: [raw/notes/Versioning, CI-CD.md]   # reads back as two elements

So --set would have parsed the value correctly and the write would have taken it apart again. Fixed in frontmatter_io.py:

• _round_trips_as_string(text, flow=True) probes in the context the value is actually written in - it still asks the YAML loader rather than enumerating rules, which is the file's stated design principle.
• A new _quote() helper asks the dumper for a one-element flow sequence and strips the brackets, because a bare plain scalar from safe_dump comes back carrying a ... document-end marker - correct for a document, nonsense inside a list.

Verified that existing output is unchanged: tags: [k8s, ci-cd] stays unquoted, year: '1945' stays quoted exactly as before. Only values that used to break silently are now quoted.

Issue #13 - the budget counted friction rather than iteration

Refund on a declined call. The design decision was where to draw the line. Keying the refund on exit code 1 alone would have made lint --fail-on-error free whenever it found something. The assistant keyed it on _util.fail() instead:

• fail() means the command declined - a rejected argument, or a read-only check reporting findings. Nothing happened; refund.
• A command that already did its work and then reports a non-zero result raises typer.Exit(1) directly and stays counted. lint --fail-on-error is exactly that case: it has written its report first.

record_and_check() now returns whether it charged, and cli._run_traced calls run_budget.refund() in its finally block when the process left through fail(). The call stays in recent, so the loop-breaker still sees it - the issue itself argues that the loop-breaker, not the counter, is the right instrument for a repeated broken invocation.

Considered and rejected: marking mutations at the write sites (35 sites across 15 files) so the refund could be keyed on "nothing was written". Rejected as fail-open - a new write site that forgets the marker would silently weaken a gate.

Ceiling 30 → 60, per Torben's instruction. The calibration band (5-15 simple, 15-25 complex) was left alone: it describes the work. The ceiling described nothing - it sat so close to the band that the overhead of a real ingest reached it on its own. Pulled through AGENTS.md, instructions/gates.md, tools/CONTRACT.md, README.md, the work plan template, and the unit sizing in migrate-corpus.md (now "near 55 pages; aim for 48 or fewer").

The loop-breaker was deliberately left at 3. The assistant flagged this back to Torben rather than doubling it silently: it is a detector for three identical calls, not a budget, and doubling it would let a stuck agent spin twice as long.

Issue #13 - lint forced a second call

The finding turned out sharper than the issue's headline. Without --markdown, lint wrote no file at all - it dumped the full report to stdout. So there was no path to name, and no way back to a skipped section except a second run.

• The full report is now always written, by default to reports/Lint Report <date>.md, and the path is printed. --markdown still overrides the target.
• Only sections that found something are printed. --full prints everything; --json prints the findings and writes nothing.
• wiki-lint and wiki-status were both updated to say: read the file, do not run lint again. wiki-status step 3 now takes the hub statistic from the report file, because it is a statistic rather than a finding and no longer appears in the printed summary.

Not implemented: exempting lint from the budget entirely (the issue's third proposal). The issue itself says that should be decided separately, and the case has moved - lint now writes a file.

Verification

658 tests pass. Two of the new tests initially failed under the hardened environment from issue #8 (GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null HOME=<empty>) with ERROR No author configured for this instance - the third and fourth instance of that same silent environment dependency. Both now set WIKI_AUTHOR themselves, and the suite is green in both environments.

The refund was measured against the real tool rather than only in tests:

$ tools/wikitool new source --name "Refund Probe" --set "raw_files=raw/notes/Versioning, CI-CD.md"
ERROR raw_files path does not exist: raw/notes/Versioning
  This is one element after splitting the value on commas. ...

$ tools/wikitool budget status
Calls so far: 0 (limit 60)
Recent calls:
  - new source --name Refund Probe --set raw_files=raw/notes/Versioning, CI-CD.md

docs verify, instructions verify and doctor all clean. lint clean over 255 pages.

---

Turn 2 - the Mass-Update Gate fires, and Torben clears it

publish refused with exit 42 on a 21-file changeset, printing the breakdown by area and the --confirm 8c3ee8ff0ad6 line. The assistant reproduced the full file list in its reply - the groups, the paths and the per-file line counts - and stopped, as the gate's own output demands.

Torben replied: "Freigegeben". The confirmed publish produced 40adbb7:

[main 40adbb7] fix: --set-Arraywerte mit Komma, lint nennt Reportpfad, Budget-Refund und Ceiling 60 (1.2.0)
 21 files changed, 593 insertions(+), 73 deletions(-)

Verified afterwards that HEAD equals origin/main, the tree is clean, and VERSION reads 1.2.0 - rather than trusting the tool's own success line.

---

Turn 3 - "Benenne die Referenz mit Komma um, damit sie wieder stimmt"

The raw file renamed during the 2026-08-30 ingest got its original name back:

raw/notes/Conversation Transcript - Versioning, CI-CD and Content Migration Session 2026-08-30.md

Done with git mv (100% similarity, history preserved). The source page's raw_files: entry and its **Raw-Dateien:** prose line were corrected, sources rebuild-index rebuilt the provenance index, sources coverage reported 0 uncovered and 0 broken references, lint was clean over 255 pages, and a log append --op update entry recorded what happened and why.

Worth noting: the corrected value is now written quoted in the frontmatter - raw_files: ['raw/notes/…Versioning, CI-CD…'] - which is exactly the second defect fixed earlier in the session. Without that fix the rename would have taken itself apart again on write.

Published as 5426a6e, five files, below the Mass-Update Gate threshold.

The gap this exposed - issue #14

No wikitool command writes raw_files: on an existing page. touch handles the fields that describe the page itself; xref handles the page-reference arrays (related:/sources:/entities:/concepts:), and raw_files: is none of those - it points at a path, not a page title. new source --set raw_files=… writes the field once, at creation, and never again.

AGENTS.md invariant 1 does not forbid hand-editing it - its list names the catalog, log.md, provenance.md, the skill directories, the two JSON files and the page-reference arrays, and raw_files: is in none of them. But it contradicts the core principle that anything mechanical is done by the tool. lint and sources coverage report broken raw_files: references reliably; nothing can repair them. That asymmetry sends an agent into exactly the hand-edits the rest of the stack is built against.

Filed as issue #14, proposing sources relink or, more closely, a raw rename that does the git mv and every referencing source page in one step - the only form where the intermediate state "file gone, reference dangling" never exists.

---

Outcome

Artifact	Result
Stack version	1.2.0 (MINOR - new capability, backwards compatible)
Commits	40adbb7 (fix), 5426a6e (content correction)
Tests	658 passing, in the normal and the hardened environment
Gitea	#12 and #13 closed with the reasoning; #14 opened
CI	Runs 62, 63, 64 all green