docs: ownership-and-templates benennt die gemischte Zustaendigkeit im Seiten-Type-Spec (Nachzug zu #99)
CI / verify (push) Successful in 48s

Files changed:
- docs/ownership-and-templates.md
This commit is contained in:
2026-09-15 16:29:42 +02:00
parent c64479fe02
commit ef60e2984c
+26
View File
@@ -16,6 +16,7 @@ overwriting them would silently erase a choice someone made on purpose.
- [Why silent overwrite is the failure being designed against](#why-silent-overwrite-is-the-failure-being-designed-against) - [Why silent overwrite is the failure being designed against](#why-silent-overwrite-is-the-failure-being-designed-against)
- [Why the boundary is a predicate rather than a list](#why-the-boundary-is-a-predicate-rather-than-a-list) - [Why the boundary is a predicate rather than a list](#why-the-boundary-is-a-predicate-rather-than-a-list)
- [Why a `.template`, not just an absent file](#why-a-template-not-just-an-absent-file) - [Why a `.template`, not just an absent file](#why-a-template-not-just-an-absent-file)
- [Where the file boundary strains](#where-the-file-boundary-strains)
- [The consequence in practice](#the-consequence-in-practice) - [The consequence in practice](#the-consequence-in-practice)
<!-- /wikitool:toc --> <!-- /wikitool:toc -->
@@ -91,6 +92,31 @@ also why `ENVIRONMENT.md` only warrants a WARN rather than a FAIL when absent -
checkout among possibly several and is gitignored for that reason, so its absence is a normal checkout among possibly several and is gitignored for that reason, so its absence is a normal
state rather than a sign setup was skipped. state rather than a sign setup was skipped.
## Where the file boundary strains
"The file itself already answers that" holds for every file above except one shape, and it is
worth naming rather than discovering: a `root: kb` type-spec has two audiences inside one file.
Its authoring guidance - when to use this type, what each frontmatter field means, how to cite -
is instruction to an agent. It reads like the stack's own prose because it *is* the stack's own
prose: a later release that learns something about writing entity pages would want to improve it
everywhere. Its `## Template` block and its `layout:` titles are the opposite: they become the
literal headings of pages this instance writes, in the language this instance chose, and no
release has any business touching them.
Ownership is per file, so the instance keeps both halves. The template half is correct that way.
The guidance half pays for it: an instance that adopted its type-specs at setup will never
receive an improvement to them again, because `dist upgrade` writes the `.template` beside the
adopted file and never the file itself. Nothing breaks, and nothing reports it - the instance
simply keeps reading the guidance it was handed the day it was created.
This is not an argument against the per-file boundary; the boundary is what makes an upgrade
safe at all, and merging inside a shared file is the failure the whole section above is about.
It is an argument that this particular file is cut in the wrong place. Splitting it - the
template block into its own instance-owned file, the guidance staying stack-owned and shipping
verbatim - would put the boundary back where the audiences actually divide, and would cost a
migration for every instance that already adopted one.
## The consequence in practice ## The consequence in practice
An upgrade sorts every shipped path into three categories, not two - and the third one only An upgrade sorts every shipped path into three categories, not two - and the third one only