Skip to content

F16.3 — Cut over onto kiln

State Closed
Parent E16
Iteration Release 8
Start Date 2026-10-17
Closed Date 2026-11-14
Predecessors F16.1, F16.2, F16.4, F16.5, F15.1, F15.3, F19.2, F19.3, F21.3, F21.5; kiln F6.7, F6.8 and F6.9

Stories: 10 Closed · 2 Removed

Story State Depends on
S16.3.11 — Format to kiln's formatters ahead of the overlay Closed (2026-11-12) —
S16.3.12 — Specs take kiln's derived regions Closed (2026-11-12) —
S16.3.1 — Cut over by overlay Closed (2026-11-12) —
S16.3.2 — Generated CI replaces main.yml Closed (2026-11-14) S16.3.1
S16.3.3 — Docs format ahead of kiln init Closed (2026-11-03) —
S16.3.4 — The planner leaves Closed (2026-11-13) S16.3.2
S16.3.5 — Sonar's gate passes on pykit's code Closed (2026-11-12) —
S16.3.6 — Edits that need no kiln Closed (2026-11-07) —
S16.3.7 — The board script retires Removed —
S16.3.8 — Root config as kiln new writes it Removed —
S16.3.9 — Test code passes ruff without the ALL ignore Closed (2026-11-12) —
S16.3.10 — Test output moves from .out/ to .tmp/ Closed (2026-11-12) —

Entry criteria: the work runs first as rehearsals from kiln feature/v1 on the cutover branch, and merges once task kiln:apply re-renders with no change (task kiln:diff prints no difference) at the configured [kiln] ref (S16.3.1). This page holds the whole cutover, so it can be rerun from the page alone, many times, before the cutover merges: the kiln new input (three files beside this page), every step as a script and the acceptance block. kiln keeps only the general cutover runbook, and its S7.2.4 is a gate that links here.

The cutover runs on kiln's feature/v1 with [kiln] ref = "feature/v1", so kiln keeps being refined from pykit's findings, and it may merge on that ref. Moving [kiln] ref to a tag later is a ref bump followed by task kiln:apply, not part of this feature. The steps are S16.3.1's numbered list; a rerun follows them verbatim.

Outcome: pykit adopted kiln's python-lib archetype in place, by an overlay that kept its git history. F16.3's stories closed on feature/kiln-cutover, which merged locally into feature/release-8 (owner decision 2026-11-13), and the feature/release-8 → main pull request ships Release 8; the kiln apply check held on 2026-11-13 at 9783dee.

Context

Outcome: the cutover's only dependency on kiln is the [kiln] ref in config.toml and the observable task kiln:diff entry criterion, so ADR-0008 holds for every acceptance line. pykit sets archetype = "python-lib", its ten members and modules, import_contracts = "own" and [ci] release = "pypi", and stopped owning main.yml, its other workflows, .github/dependabot.yml and docs/_update_board.sh, which kiln renders or replaces. Over kiln's defaults pykit keeps the root ruff lint tables (a member has no [tool.ruff] table, so the root's applies), the root conftest.py and pytest markers (the scaffold suite runs from the root), rn-forge-web's guide examples (its tests execute them) and the root [project] metadata.

S16.3.11 — Format to kiln's formatters ahead of the overlay

State: Closed (2026-11-12) · pre-cutover

Outcome: pykit's Markdown, TOML and YAML were reformatted once to kiln's formatter configuration in the S16.3.11 commit on feature/kiln-cutover, extending S16.3.3, so the overlay's diff held only what kiln owns and pykit's nuances. pykit's old gate could not pass on that commit: 26 files already failed its mdformat check.

Acceptance:

  • The commit changes only *.md, *.toml, *.yml and *.yaml files: git diff --name-only HEAD~1 HEAD | rg -v '\.(md|toml|ya?ml)$' prints nothing.
  • No file on the overlay's path list changes: git diff --name-only HEAD~1 HEAD | grep -cxF -f <(sed 's/^...//' "$PATCH.overlay") prints 0.
  • pykit's existing gate on that commit is not expected to pass (step 5 above).
  • A rerun of S16.3.1 from it shows no formatting-only hunk in a file pykit owns.

S16.3.12 — Specs take kiln's derived regions

State: Closed (2026-11-12) · pre-cutover

Outcome: the S16.3.12 commit replaced the old board:start and scope:start fences with kiln's derived fences and removed the 75 hand-written feature rows whose features have a file, so S16.3.1 carried no spec-table noise. The epic tables lost their per-feature Scope summaries, and E12 its Trigger and Tags columns, which kiln does not regenerate.

Acceptance:

set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
absent 'board:start|scope:start' docs/specs/index.md docs/releases/release-*/index.md
grep -qx '<!-- BEGIN derived board -->' docs/specs/index.md
for r in docs/releases/release-*/index.md; do grep -qx '<!-- BEGIN derived scope -->' "$r"; done
for e in docs/specs/epics/E*/index.md; do
  if compgen -G "$(dirname "$e")/F*.md" >/dev/null; then grep -qx '<!-- BEGIN derived features -->' "$e"; fi
done
for f in docs/specs/epics/E*/F*.md; do grep -qx '<!-- BEGIN derived stories -->' "$f"; done
# the commit changes only Markdown under docs/ and packages/*/docs, and no overlay path
test "$(git diff --name-only HEAD~1 HEAD | grep -vcE '^(docs|packages/[^/]+/docs)/.*\.md$' || true)" = 0
test "$(git diff --name-only HEAD~1 HEAD | grep -cxF -f <(sed 's/^...//' "$PATCH.overlay") || true)" = 0

S16.3.1 — Cut over by overlay

State: Closed (2026-11-12)

Outcome: on 2026-11-12 the owner ran steps 0 to 17 from reference c9cc5da (kiln c94f5e0): the overlay copied every managed file and block from a kiln new reference byte for byte, applied pykit's nuances as explicit steps, and committed c1670df, 004be8b, 85ed42b and 01aeff3; task kiln:diff then showed no difference. A difference pykit needs inside a managed file or block is a kiln finding, never an edit of the copy.

Acceptance: steps/16-acceptance.sh, step 16, is the block a rerun executes. It asserts:

  • the four legacy workflows, src and docs/_update_board.sh are gone, and kiln's workflows are in;
  • the board and scope fences are kiln's, with none of the old board:start or scope:start fences left;
  • every managed file is the reference's, byte for byte, and .yamlfmt.yaml exists;
  • the three managed blocks (AGENTS.md, .importlinter, .gitignore) are the reference's, git diff --numstat -- AGENTS.md is 31 0, and .gitignore is the reference's plus the .out/ line;
  • config.toml has no [source] table and holds the input's values;
  • the service tables are replaced, no guide names a removed workflow or the board script, and no gate runs through uv;
  • the root pyproject.toml differs from the reference's only by pykit's nuances, with a blank line before every table and [tool.pyright] sorted;
  • every member has the reference's build pin, pyright table and source-exclude, and no site_dir;
  • nothing under src/ or tests/ changed, nothing is staged, and the changed non-Markdown files and the untracked files are exactly the two lists in the script.

Expected git status: the four legacy workflows deleted (D); src/pykit/ and docs/_update_board.sh deleted; the Markdown files steps 3, 10 and 13 changed (and step 12 wrapped, in those files only); the non-Markdown files in the first list changed; the fourteen untracked entries in the second list. Nothing is staged or committed when the block runs.

Outcome: three findings went to kiln: mkdocs.yml is managed but its nav is derived, state.json's config_hash follows config.toml's bytes, and kiln's .gitignore block has no .out/. kiln is not a dev dependency: the generated tasks run it through uvx (kiln F7.4).

S16.3.2 — Generated CI replaces main.yml

State: Closed (2026-11-14) · Depends on: S16.3.1

Outcome: kiln's generated ci.yml, with [ci] release = "pypi", replaced main.yml, internal-ranges.yml, umbrella-release.yml and broker-profile.yml, and renders F21.3's release behaviour; the release runbook describes it.

Acceptance:

  • main.yml no longer exists, and kiln doctor . --full exits 0 with no finding.
  • A pull request run and a run on main pass (the pull request is feature/kiln-cutover → main); ci-ok is the only required check.
  • After the run on main, each package's site is served at packages/<package>/latest/ beside the root site.
  • The run on main runs internal-ranges and umbrella-release, and the integration job runs the keycloak service of rn-forge-auth.

Outcome: run 43591842240 on main at 637a7df (2026-11-14) passed every job, and all ten package sites and the root site returned 200. ci.yml's own docs job deploys the package sites, so no separate docs.yml ever raced it. The pull requests were #31 and #34, not feature/kiln-cutover → main. The umbrella step created tags and releases release-1 to release-5 at 637a7df instead of release-8; the fix is the owner's and kiln's kiln-devops umbrella.

S16.3.3 — Docs format ahead of kiln init

State: Closed (2026-11-03)

Moved pykit's docs to kiln's story-heading format and docs/specs/ideas/index.md on feature/release-8, ahead of the overlay.

S16.3.4 — The planner leaves

State: Closed (2026-11-13) · Depends on: S16.3.2

kiln's ADR-0017 moves the planner into kiln as kiln-devops (kiln F6.7). E19's range check stays in pykit, and S16.3.2 declares it to kiln's generated CI. The package index is gone by F21.5.

Outcome: rn-forge-devops keeps only requirements and umbrella, with a breaking minor bump; its subcommand reference describes them, and ADR-0012 records that kiln's ADR-0017 supersedes it for the planner.

Acceptance:

  • uv run rn-forge-devops --help lists requirements and umbrella and no planner subcommand, notes or index.

S16.3.5 — Sonar's gate passes on pykit's code

State: Closed (2026-11-12)

kiln's pykit-shape CI run 41549190853 (2026-11-02) failed only Sonar's quality gate, on pykit's own findings. They are fixed before the cutover, so the cutover's first pull request run does not fail on them.

Outcome: rn_forge.commons.testing type-checks under assertpy 2.35.0, and the Django models pass SQL values as parameters with quoted identifiers.

Acceptance:

  • pyright, ruff and the commons and django test suites pass on a lock with assertpy 2.35.0.
  • The Sonar quality gate on rn-forge_pykit passes on the feature/kiln-cutover → main pull request's run (kiln's ci.yml runs on pull requests to main only).

Outcome: the owner accepted assertpy 2.35.0, a typed rewrite released under the original name by a new maintainer (2026-11-03), and every floor is assertpy>=2.35. TruncateModelMixin.truncate runs Django's sql_flush statements, so pykit formats no SQL. The gate passed on PR #30's run 43368251001 (78f4948, 2026-11-12).

S16.3.6 — Edits that need no kiln

State: Closed (2026-11-07)

Landed the CLAUDE.md and README.md wording and the F13.4 note that needed no kiln, ahead of the overlay.

S16.3.7 — The board script retires

State: Removed

Folded into S16.3.1: steps 5, 10 and 16 delete the script, check that no guide names it, and assert both.

S16.3.8 — Root config as kiln new writes it

State: Removed

Folded into S16.3.1: the root pyproject.toml, .gitignore and the members' pyproject.toml and mkdocs.yml take kiln's shape in its steps 3 and 6 to 8.

S16.3.9 — Test code passes ruff without the ALL ignore

State: Closed (2026-11-12)

S16.3.1 step 6 keeps "**/tests/*" = ["ALL"] in the root pyproject.toml, as pykit had it, with a comment that it is debt. This story pays it: the ten tests/ directories pass ruff with kiln's four test ignores and pykit's justified Bandit rules, and nothing else.

Outcome: the 597 ruff findings measured under ruff 0.17 were fixed, and the seven Bandit rules that tests legitimately trip stay ignored.

Acceptance:

  • "**/tests/*" in [tool.ruff.lint.per-file-ignores] is exactly ["ANN", "D", "PLR2004", "S101", "S105", "S106", "S107", "S108", "S310", "S603", "S607"] and ALL appears in no per-file-ignores entry.
  • task lint exits 0.
  • task test exits 0, with the same number of tests collected as before the story (the story changes style, not what tests prove).
  • No # noqa was added: git diff -U0 -- '*/tests/*' | rg '^\+.*noqa' prints nothing.

S16.3.10 — Test output moves from .out/ to .tmp/

State: Closed (2026-11-12)

The output_path fixture in rn_forge.commons.testing (packages/rn-forge-commons/src/rn_forge/commons/testing.py) writes under <rootdir>/.out/<scope>/tests/output/<node-id>/. kiln's standard names .tmp/ for scratch output, ignores it and cleans it, so the fixture follows. Entry criterion, observable from outside kiln: the .gitignore block that S16.3.1 step 3 copies from the reference lists .tmp/. Until then this story does not start.

Outcome: output_path writes under .tmp/<scope>/tests/output/, the root .gitignore no longer lists .out/, and the rn-forge-commons changelog records the breaking change for its next minor release (ADR-0004).

Acceptance:

  • rg -n '\.out' packages/rn-forge-commons/src prints nothing, and test_testing.py asserts .out is not in the path.
  • task test exits 0 and, afterwards, packages/rn-forge-commons/.tmp exists and packages/rn-forge-commons/.out does not.
  • git status --short --ignored packages/rn-forge-commons/.tmp shows the directory ignored (!!).
  • rg -n '^\.out' .gitignore prints nothing.
  • task lint exits 0.

Acceptance

S16.3.1's block is the one a rerun executes; this feature-level block follows it with the steps after the overlay. The uv run check does not list pytest, because the narrower runs in the development guide stay (S16.3.1 step 10).

set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
task validate                                   # S16.3.1 (after S16.3.2: no findings)
kiln doctor . --full                            # S16.3.1, S16.3.2
test ! -e .github/workflows/main.yml            # S16.3.2
test ! -e .github/workflows/docs.yml            # S16.3.2
grep -q '^release = "pypi"' .rn-forge/kiln/config.toml   # S16.3.2
absent '\buv run\b' .github/workflows           # S16.3.2
test ! -e packages/rn-forge-tooling/src/rn_forge/tooling/settings.py   # S16.3.1
test ! -e docs/_update_board.sh                 # S16.3.1
test ! -e src                                   # S16.3.1
test -f docs/specs/ideas/index.md               # S16.3.3
test -d packages/rn-forge-devops/docs/guides    # S16.3.1
test ! -e packages/rn-forge-devops/src/rn_forge/devops/ci.py   # S16.3.4
absent -g '*.md' 'uv run (ruff|pyright|mkdocs|lint-imports|--group)|uv sync' CLAUDE.md README.md docs/runbooks docs/guides/development.md  # S16.3.1
absent '"ALL"' pyproject.toml                   # S16.3.9
absent '^\.out' .gitignore                      # S16.3.10
task lint                                       # S16.3.1

S16.3.9 and S16.3.10 are post-cutover; each carries its own acceptance.

Not scripted: S16.3.1's findings apart from those it excepts, and the "pykit keeps" tables, are read from the run; S16.3.2's pull request and main runs, the ci-ok required check, and the live package sites are checked on GitHub.