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

# Conversation Transcript - Versioning, CI/CD and Content Migration Session

> Source: Claude Code session (`claude-opus-5`), llm-wiki-test1 workspace
> Collected: 2026-08-30 (session spanned 2026-08-29 to 2026-08-30)
> Participant: Torben
> Fidelity: **faithful summary transcript, not a verbatim log.** Reconstructed by the assistant
> at the end of the session. Torben's questions and decisions are rendered closely; the
> assistant's reasoning is condensed. Command outputs quoted below are real. No credentials
> appeared in the session; internal hostnames mentioned are already documented in `kb/`.
> Revised 2026-08-30 with turns 10-13, which happened after the first version was written; the
> model attribution was corrected at the same time (the first version said "Claude Sonnet 5",
> the session log records `claude-opus-5` for all 501 messages).

Covers three pieces of work that turned out to be the same mechanism seen from different ends:
stack versioning with CI and release artifacts (shipped as `0.1.0`, then `1.0.0`), a content
migration strategy built on top of it, and finally getting the pipeline to actually run.
Resulting commits: `2508f7a`, `7d63d61`, `c3034ab`, `db03b08`, `aace3e7`, `401d700`, `b94166b`.

---

## Turn 1 - "Bearbeite den CI/CD-Punkt aus todo.md ... Was denkst du?"

Torben invoked the `stack-dev` skill and asked for the CI/CD item from `TODO.md` to be built
such that semantic versioning comes with it, that the version then drives update detection, and
that release files come out with which a wiki can be set up.

Assistant proposal, after reading `TODO.md`, `tools/CONTRACT.md`, `dist_cmd.py`, `cli.py`,
`docs_verify.py` and `.gitignore`:

- A root `VERSION` file versioning the **stack**, not the content. Key argument: no auto-bump
  from commit messages, because `publish --message "ingest: ..."` writes content commits into
  the same repository, so a conventional-commit reading would turn every ingest into a release.
- A `wikitool version` command group; `.gitea/workflows/ci.yml` with the four steps from the
  TODO plus a version gate and an export smoke test; `.gitea/workflows/release.yml` triggered by
  a `VERSION` change, tagging and publishing a `dist export` tarball.
- Update detection via a stamp file written into every export, compared against the origin's
  release feed.
- Explicitly *not* shipping CI into a distributed instance, because `runs-on: linux-docker` is a
  site-specific runner label.

## Turn 2 - Three design decisions

The assistant asked three questions with recommendations. Torben's answers:

| Question | Decision |
|---|---|
| Network call in `wikitool` vs. strictly offline | **`version check` may make the network call** - own command, no key, timeout, injectable fetch so tests never touch a network |
| Build the upgrade path now, or detection only | **Detection first**, `dist upgrade` later |
| Start at `1.0.0` or `0.1.0` | **`0.1.0`** (against the assistant's recommendation) |

Because `0.x` was chosen, the assistant defined compatibility as "same leftmost non-zero
component" (the rule Cargo's caret ranges use), so that `0.1.x -> 0.2.0` carries the
migration signal that `MAJOR` carries from `1.0.0` on.

## Turn 3 - "Prüfe die Actions gegen den Gitea Runner, die Doku liegt im Wiki"

Sent mid-turn. The assistant ran `wiki-query` against the corpus before writing the workflow
YAML. **The wiki corrected two assumptions:**

1. Authentication is `${{ gitea.token }}`, documented on the `Act Runner` page under
   "Gitea-Token" - not `secrets.GITEA_TOKEN`, and not a 1Password secret, since nothing in these
   workflows leaves the instance.
2. The label-to-image mapping for `linux-docker` is **the one thing the wiki does not record**,
   and it decides whether a `python3` exists at all. The job image was therefore named
   explicitly (`container: image: debian:trixie-slim`, the base Scenario B already proves works
   with `actions/checkout@v4`).

Also confirmed from the corpus: routing labels are `linux-docker`, `container-builder`,
`k3s-deploy`; `actions/upload-artifact@v3` (v4 support is limited).

A local finding of the same kind: setting `WIKI_TRACE=0` job-wide breaks two telemetry tests
that assert a trace is written, so CI sets `WIKI_TRACE_DIR` outside the workspace instead.

## Turn 4 - Publish, and the Mass-Update Gate

`wikitool publish` exited 42 with a 21-file breakdown, which was reproduced in full for Torben.
He replied "Freigegeben", and the clearance line published `2508f7a`.

## Turn 5 - A correction: the origin repository is private

Attempting to verify whether CI had run, the assistant discovered that its own earlier inference
was wrong. Before the push, `version check` had returned HTTP 404 and this was read as "no
release published yet, so the feed is anonymously readable". It is not:

```
$ curl -s -w "\nHTTP:%{http_code}\n" ".../api/v1/repos/torben/llm-wiki-test1"
{"message":"not found",...}   HTTP:404
$ curl -s -w "\nHTTP:%{http_code}\n" ".../api/v1/repos/torben/definitely-not-a-repo-xyz"
{"message":"not found",...}   HTTP:404
```

Gitea answers an anonymous caller identically for an invisible repository and a non-existent
one. Consequence: `WIKITOOL_UPDATE_TOKEN` is a requirement rather than an exception while the
repo stays private, and **no conclusion about CI state can be drawn from outside**. Corrected in
`CHANGES.md` and `INSTALL.md`, published as `7d63d61`.

## Turn 6 - "Die Runner laufen nicht" + the next task

Torben: the runners do not run; he will debug it later at his PC and will provide a **Gitea MCP
server** for it. (Dictated "kaufen" for "laufen".) Then the new task:

> "Wie gehen wir denn mit semantischen Änderungen am Content um, die machen wir ja gerade
> mehrfach. Lass uns eine Migrationsstrategie erarbeiten und umsetzen. Wir brauchen erst mal
> einen Plan."

## Turn 7 - Research: the methodology already existed and had been deleted

The assistant recovered the closed `translate-kb-de` workshop from git history
(`git show de0862f:work/translate-kb-de/README.md` and `plan.md`) and found a complete working
methodology that had been thrown away when the workshop closed:

- Units sized by the **iteration budget** (30 calls → ceiling near 24 pages, target ≤ 21), and
  batches sized separately by the **Mass-Update Gate** - conflating the two "cost eleven
  unnecessary clearances in the first cut of this plan".
- Per unit, **before anything else**: frontmatter, H1, wikilink targets and cite-ids compared
  against `HEAD`.
- `lint` read in full every unit, not just the plausibly-affected sections - unit 1's
  frontmatter bug surfaced as a schema error on a field nobody had edited.
- Summaries written by the orchestrating session, never pasted from a subagent ("they
  embellish: one turned 'measuring application performance and responsiveness' into 'Latenz und
  Durchsatz unter Lastbedingungen'").

Two further findings from reading the code:

- `kb_scan.extract_wikilinks()` returns a **set**. That is correct for `lint` (does the
  reference resolve?) and wrong for a migration check (did one go missing?). Three of the four
  defects the translation found had unchanged link sets and only changed counts.
- `sections.py` already documents a named migration pattern in its docstring: canonical name
  plus aliases is "what lets a corpus migrate page by page instead of all at once", and removing
  an alias is a breaking change rather than a cleanup.

## Turn 8 - Plan rejected, with three substantive points

Torben rejected the first plan:

> "Lass uns doch mit Version 1.0.0 anfangen, damit wir den 0.* Sonderfall nicht implementieren
> müssen.
> Wo speichern wir denn die aktuelle Version einer KB?
> Wie decken wir ab, dass eine KB ggf. über mehrere Versionen aktualisiert werden muss? Wir
> müssen ja eigentlich sowas wie 'migrate from 1.3.1 to 1.4.0' und dann 'migrate from 1.4.7 to
> 2.0.0' in Sequenz ausführen?
> In diesem Kontext müssen wir keine Beta oder ähnliche Version Keys unterstützen. x.y.z ist die
> maximale Granularität, die wir brauchen."

The second question exposed a real error in the plan: it had **conflated the stack version with
the content version**. An instance can carry machinery 1.4.0 while its content is still in 1.2.0
shape - and that is the state every upgrade passes through. The first plan had written this off
as a "known limitation" instead of solving it.

Revised design:

| Fact | File | Written by | Answers |
|---|---|---|---|
| Stack version | `VERSION` | `version bump` | which machinery is installed |
| Release stamp | `.wikitool-release.json` | `dist export` | where that machinery came from |
| **KB version** | `.wikitool-kb.json` | `migrate done` | what shape the content is in |

Separate files because the two have opposite rules - the stamp is generated and must never be
hand-edited, the KB state is mutable instance state.

On sequencing: `migrate status` builds the interval `(kb_version, VERSION]` from the migration
documents and orders it ascending; 1.3.1 → 2.0.0 runs 1.4.0, then 1.7.0, then 2.0.0. That no
migration targets 1.3.x is not a special case - it is simply not in the interval. `migrate done`
refuses any version that is not the next link, making a skip impossible and an interrupted
multi-step upgrade resumable.

Starting at `1.0.0` also removed a self-contradiction the assistant had shipped in `0.1.0`: the
guidance in `stack-dev/SKILL.md` assigned `--minor` to both "new capability" and "requires
migration", which cannot both be true under `0.x`. The `compat_key` code needed no change - it
is stated uniformly - only the guidance did.

Plan approved on the second attempt.

## Turn 9 - Implementation and verification

Built: `corpus_diff.py`, `kb_state.py`, `migrate_cmd.py` (`list`/`status`/`verify`/`done`/
`baseline`), `instructions/migrate-corpus.md`, the `migrates_to:`/`migration_kind:` schema
fields, boundary enforcement in both `version bump` and `docs verify`, and a `kb-version` check
in `doctor`. Deliberately not built: mechanical runner primitives (a DSL for zero migrations)
and `dist upgrade`.

**Verification against the real corpus, which unit tests cannot replace:**

1. `migrate verify --from 1c3ca39` over 248 pages: zero invariant violations in 2.2 s - but 13
   reported "removed pages" that are not pages. The historical side listed every `.md` under
   `kb/` while the working-tree side used `iter_kb_pages`, which skips `COLLECTION.md`,
   `INDEX.md` and the kb-root meta files. **Two different definitions of "page."** Fixed with a
   shared `kb_scan.is_page_path`, and pinned by a regression test.
2. Negative control: one of two `[[Docker]]` occurrences removed from `kb/entities/tools/Act
   Runner.md`, leaving the link *set* unchanged.

   ```
   $ tools/wikitool migrate verify --from HEAD --fail-on-error
   248 page(s) compared, 0 added, 0 removed, 1 finding(s).
   - kb/entities/tools/Act Runner.md: wikilinks - 'Docker' 2->1
   $ tools/wikitool lint --fail-on-error   # exit 0, all 21 checks silent
   ```

   This is the claim the whole strategy rests on: `lint` reads a single revision, so a reference
   that went missing leaves a corpus that is still perfectly consistent.

3. `version bump --major` correctly refused without a migration document, then succeeded with
   `--no-migration "no distributed instance exists yet; 1.0.0 is the migration baseline"` - the
   new mechanism's first real use.
4. The dev tree itself became the first `migrate baseline` case: it predates `.wikitool-kb.json`,
   but its content never lagged its machinery, so `1.0.0`.
5. 630 tests, `docs verify`, `instructions verify`, `lint --fail-on-error`, and a full
   `setup-instance.md` replay against a fresh `dist export`.

Published as `c3034ab` after the Mass-Update Gate breakdown (29 counted files) was reproduced
and cleared.

---

## Turn 10 - "Store this conversation in the wiki as raw source in /raw/notes"

The first version of this file. `raw/CONTRACT.md` lists "conversation transcripts" under
`notes/` explicitly, and a sibling already existed (`Conversation Transcript - AGENTS.md Skill
Restructuring Session 2026-08-04.md`), so the format was inherited rather than invented. Labelled
a summary rather than a log, because a verbatim reconstruction would have been fabrication.
Published as `db03b08`.

Immediately afterwards the Gitea MCP server became available, and a read-only diagnosis of the
long-standing "the runners don't run" item produced the opposite of what had been assumed:

```
list_runs -> 6 runs; 46-51 all conclusion: failure
OCI runtime exec failed: exec: "node": executable file not found in $PATH
  ❌  Failure - Main actions/checkout@v4
exitcode '127': command not found
```

The runners had been picking the workflows up all along. `actions/checkout` is a JavaScript
action that act_runner executes with `node` **inside the job container**, and the pinned
`debian:trixie-slim` has none. The image was pinned precisely as a precaution against the
undocumented `linux-docker` label mapping - the precaution caused the failure.

## Turn 11 - "Check the gitea-mcp repo, branch ci-build"

Torben pointed at two working workflows on another repo and asked for their shape to be picked
up, plus: the wiki workflows must not run on content changes.

`torben/gitea-mcp@ci-build`, `ci-build.yaml`, runs 42-45 green. The whole answer was one
line in an apt list:

```yaml
- name: Install CI Dependencies
  run: apt-get install -y --no-install-recommends git nodejs curl unzip ca-certificates build-essential
- name: Checkout Code
  uses: actions/checkout@v7
```

`nodejs` installed **before** the checkout, and checkout at `@v7`. Both were adopted in `ci.yml`
and `release.yml`. `runs-on: linux-docker` was kept: runs 46-51 proved it routes and starts the
container, so the label was never the problem.

For the second half, `paths-ignore` on everything `publish` touches. Three choices are worth
recording because they are all *refusals to infer*: `kb/CONTRACT.md` is deliberately not
excluded (it lives under a content directory but belongs to the stack); no `!**/CONTRACT.md`
negation, because Gitea's support for negated filter patterns is undocumented; and the list is
written twice instead of shared through a YAML anchor, because GitHub's parser rejects anchors
outright and Gitea's is not documented to accept them. The patterns fail open - anything
unanticipated still triggers CI. Published as `aace3e7`.

## Turn 12 - The first green run finds a real bug

Run 52 got past checkout and reached `pytest` for the first time ever. Two of 630 tests failed:

```
FAILED test_new_page.py::test_new_source_author_falls_back_to_git_config
FAILED test_provenance.py::test_new_source_with_multiple_raw_files
AssertionError: ERROR No author configured for this instance.
2 failed, 628 passed in 13.85s
```

`config.default_author()` runs `git config user.name` with `cwd=config.ROOT`; the fixture root
is not a repository, so the answer came from the **global git config of whoever ran the suite**.
In the container, as root, there is none. Both tests had been green on every developer machine
for months without ever testing what their names claimed.

Fixed in the tests rather than by giving CI an identity: the first now makes its fixture root a
real repository with a *local* `user.name` and asserts the concrete name, which tests the
fallback more sharply than before; the second sets `WIKI_AUTHOR`, since it is a `raw_files:`
test and authorship was only a precondition. Verified locally with
`GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null pytest` - 630 passed.

That made it `1.0.1`, and because `VERSION` moved, `release.yml` fired on its own. It answered
the last open question of the session without being asked:

```
Created release v1.0.1 (id 54).
Uploaded llm-wiki-stack-1.0.1.tar.gz.
Uploaded llm-wiki-stack-1.0.1.tar.gz.sha256.
```

`${{ gitea.token }}` may create releases and tags and upload assets. No Actions secret with
`write:repository` is needed. Published as `401d700`.

## Turn 13 - "Can we take the CI/CD part out of todo.md?" then: move it to issues

Two cleanups. First `TODO.md`: the entire retrospective went out (64 lines), because the same
history was already in the `0.1.0`, `1.0.0` and `1.0.1` changelog entries and a second copy is
exactly the drifting duplicate the stack avoids everywhere else. Published as `b94166b`.

Then the remaining work moved to Gitea issues #7-#11 - `dist upgrade`, hardening the suite
against silent environment dependencies, the nightly drift check, coverage, and confirming
`paths-ignore` actually matches. `TODO.md` now links to them instead of describing them.

The split was made along a line worth naming: issue #11 is explicitly *an observation, not a
build task* - the proof arrives on its own with the next content-only publish. Filing it as work
would have invited someone to build machinery for a question that answers itself.

---

## Decisions worth carrying forward

- **The version describes the stack; content has its own version.** Conflating them makes the
  mid-upgrade state unrepresentable.
- **Compatibility = leftmost non-zero component.** Uniform across `0.x` and `1.x`; from `1.0.0`
  it reads as plain semver. No pre-release suffixes - a second ordering rule would have to be
  honoured by the release feed, the migration chain and the compatibility check alike.
- **Migrations are `manual: true` instructions** under `instructions/migrations/`, so they ship
  with `dist export` without a second export path. Baseline is `1.0.0`; anything older is
  re-exported, not migrated.
- **Count, never set**, when asking whether a rewrite dropped something.
- **CI tags, never an agent** - which is what keeps AGENTS.md invariant 5 intact.
- **The wiki corrected the assistant twice** in this session (the Gitea token form, the runner
  image), and the assistant's own inference was wrong twice more: anonymous API access, and the
  claim that the runners never accepted the workflows. Checking the corpus before writing
  infrastructure code paid for itself; inferring past what the corpus actually said did not.
- **A CI run is evidence; a local run is a habit.** Two tests asserted a fallback they never
  exercised, and stayed green for months, because every machine that ran them happened to
  satisfy the precondition. Nothing short of a foreign environment would have found it.
- **The failure and the fix lived in different places.** The symptom was in CI, the defect was
  in the tests. Giving CI a git identity would have made the run green and left the bug.

## What this changed about the runner, in one place

For anyone writing the next workflow against the CI runner - do not re-derive this:

- A pinned `container:` image must `apt-get install nodejs` **as the first step, before
  checkout**. act_runner executes JavaScript actions with `node` inside the job container.
- `actions/checkout@v7`, `actions/upload-artifact@v3` (v4 is limited on this instance).
- `debian:trixie-slim` works and carries python3 3.13. Labels `linux-docker` and
  `container-builder` both accept a job that names its own image.
- `${{ gitea.token }}` suffices for releases, tags and asset uploads.
- The repo is **private**, and Gitea answers anonymous callers with an identical `404` for an
  invisible repo and a non-existent one - so `curl` proves nothing. Read runs through the MCP
  server.

## Open at the end of the session

The pipeline runs. `v1.0.1` is published with tarball and `.sha256`. What remains is tracked as
Gitea issues rather than prose: **#7** `dist upgrade`, **#8** hardening the test suite, **#9**
the nightly drift check, **#10** coverage, **#11** confirming `paths-ignore` matches.

One item is genuinely unresolved rather than merely unbuilt: whether Gitea evaluates the
`paths-ignore` patterns as expected. It needs no work, only a look at `list_runs` after the next
content-only publish - and after this session, that is exactly the kind of claim that should not
be assumed.