# Fractal_Kernel_Migration_Procedure

> **CANONICAL DOCUMENT — the kernel-side migration/update standard (OQ-33): how any child instance adopts a newer anchored kernel release, governedly.** Identity: `Fractal_Kernel_Migration_Procedure_v0.1` — versioned canonical standard (C-040/C-061: every substantive change is a new version, each with its own DOC identity; the versionless alias tracks the newest). Registry class: §2 Procedure (prose + checker half per Registry contract rule 2 — honest status in §7).

> **SUPERSEDED (2026-08-23): `Fractal_Kernel_Migration_Procedure_v0.2` is the standard of record** — this file is retained as frozen history, its own DOC identity kept (the C-061 pattern).

**Version:** 0.1 · **Status:** Ratified (2026-08-17, in-conversation per C-033 — decision C-117, Max's *"go with (a)"* on the UF1 landing; per Protocol v0.53) · **Domain:** GOV · **Author:** Claude (UF1 flight, 2026-08-17 — distilled from the executed KNet beta-0.1→beta-0.5 migration; refutation pass applied, 18 defects cured) · **Parent:** GENESIS §7 (the update doctrine — this is its executable half) · **Provenance (Registry rule 4):** OQ-33; TF1-1..17 (`Flight_2026-08-17_Migration-Test.md`); KNet P-007 v0.2 / P-008; the executed migration (KNet commits `6c71bb4`, `846503c`) · **Document ID:** DOC-01M08EV47A6TVWYYNPM1XD4CGD (minted 2026-08-17 via `close.py --create`; stamped by the post-mint revise)

Citation abbreviations: **PROT** = KNet_Fractal_Kernel_Migration_Protocol.md (P-007 v0.2) · **RCPT/ASSESS/VAL** = KNet's Upstream Receipt / Adoption Assessment / Migration Validation for beta-0.5 · **KM-n** = ASSESS §6 findings · **TF1-n** = test-flight findings · **PKT** = the mother's advisory packet (Upstream_Advisory_2026-08-17_KNet-Kernel-Migration) · **ADD** = the TF1 advisory addendum (instructions 1–23).

---

## §1 Scope and sovereignty

1. This procedure governs the **demand side** of the release seam: a child instance adopting a newer anchored kernel release. The supply side — mother→mirror/public — is the C-116 rider; same seam, two sides, one interface: anchored release tags with receipts [Protocol v0.52 §1; GENESIS §7].
2. **Adoption is the child's own recorded decision** (a `P-` row), never an obligation. A never-migrating instance is fully conformant and works forever [GENESIS §7.4; Registry contract rule 5; executed: P-008 as KNet's own decision].
3. The gate skeleton is P-007's, adopted nearly verbatim: **Gate 0** clean pushed checkpoint → **Gate 1** pin → **Gate 2** audit → **Gate 3** human acceptance → **Gate 4** apply on a branch → **Gate 5** validate → **Gate 6** land. No partial red landing; forward-only correction after landing [PROT §6–§7; executed: the six-gate trace in RCPT/ASSESS/VAL].
4. **The human gate is mandatory.** Gate 3 stops at the instance owner; every conflict resolves there or defers there [PROT rule 4; executed: C-099.b and C-115.b resolved by Max at Gate 3].
5. Jurisdictions stay parallel: mother and child connect only through handed-over files and the human — no live coupling, no run-time upstream calls [Protocol v0.51 §4; GENESIS §7].
6. **Prospective effect.** Adoption binds forward only; earlier child history retains the meaning of the constitution under which it occurred. No history is rewritten or reinterpreted [PROT rule 5; executed: KNet Register §1 wording].
7. Migration is **never a store merge**; stores stay sovereign and append-only [GENESIS §6/§7, OQ-31].
8. Everything the mother hands over is **audited, never obeyed** — including severity ratings and this procedure's own per-release supplements [ADD posture line; executed: KNet's DEFER of close.py against ADD instr. 13, and of stats.py against a TF1 green].

## §2 The pin (Gate 1)

1. A child updates only from an **anchored release tag** (C-090: signed tag + external timestamp attestation) — never from the living mother tree [C-116 lag boundary; GENESIS §7.2].
2. **Resolve the SHA yourself.** A copy of a SHA is not a pin; your resolving it against the tag is. Record tag name, tag-object SHA, and commit SHA independently [recorded: RCPT §1; independent resolution: RCPT §2 — `beta-0.5^{commit}` resolved independently to `18d4104…`].
3. **Signed-tag verification requires the signers bind.** Before `git tag -v`, bind the allowed-signers file — `git config gpg.ssh.allowedSignersFile "$(git rev-parse --show-toplevel)/.allowed_signers"` (or the `-c` one-shot form); a bare `git tag -v` fails in a fresh clone [TF1-5, High; executed: RCPT §2 "as TF1-5 predicted"].
4. **Verify by fingerprint and principal, never by mother-side key labels** ("key G" is un-derivable from the shipped tree) [TF1-8; executed: RCPT §2 "no mother-side label … was assumed"].
5. Run `git fsck --strict`; record the result [executed: RCPT §2 "completed with no finding"].
6. **The structurally-absent-own-receipt rule.** A release tree cannot contain the attestation of its own tag; the receipt pair (`.txt` + `.ots`) is handed over separately, cited *as supplied*, with SHA-256 of each hand-off document recorded and the OTS state (pending/final) disclosed. **Pending-at-issue is expected and non-blocking**: signed tag + clean fsck suffice to pin; pendency is rechecked at Gate 5 and cured post-landing by a forward commit that appends the finality evidence as a new section — **both receipt hashes (supplied and upgraded) recorded, the historical pending verdict preserved in substance; prior prose may be restated, but the recorded verdict is never reversed** [TF1-6; PROT §9.6; executed: RCPT §3, VAL §6, KNet commit `846503c` — receipt v0.2→v0.3 keeping both `.ots` hashes].
7. **Transport with remote-severing.** `git clone --no-local` → checkout the tag → **record the remote's URL in the receipt, then `git remote remove origin`**. The frozen clone is a reference copy — read-only evidence, never a working surface, never push-capable [TF1-7; C-091; executed: RCPT §1 recorded-then-removed].
8. **Self-contained bundle option.** For full rehydration independence, retain in-repo a complete-history Git bundle of the signed tag plus its SHA-256, at an **instance-parameterized upstream-provenance location**, verified by bundle-only checkout and tag re-verification. The bundle's home and the receipt pair's home may differ — the executed exemplar keeps the bundle under `Claude/Project Governance/Upstream/<release>/` and the receipt pair under `Provenance/Upstream/`; the receipt names both locations. This is the tested strongest transport; the out-of-repo frozen clone alone leaves a rehydration dependency [executed: ASSESS §7.1, VAL §2 rows 1–2 and §4].

## §3 The adoption transaction (Gates 2–3)

1. **The upstream receipt** is a named artifact with a fixed home: `<Instance>_Upstream_Receipt_<release>.md`, sibling to the instance's governance documents. Minimum fields: source identity and transport; tag name + tag-object SHA + commit SHA; acquisition time; verification evidence (fingerprint, principal, fsck); worktree and remotes state (including the severed remote's recorded URL); SHA-256 of every hand-off document; timestamp state; the locations of the retained release pack and the receipt pair (§2.8 — they may differ); and the child's **baseline inheritance clause quoted verbatim** as the comparison anchor [TF1-17; KM-04; executed: RCPT as the template exemplar].
2. Migration working artifacts (receipt, assessment) are **not governance changes**: they may exist before Gate 3 and commit only on the migration branch [TF1-17 fix; ADD instr. 6; ratified in P-008].
3. **The adoption matrix** covers every decision in the delta (child baseline upper edge → release upper edge). Two-natured decisions split into `.a/.b/.c` **sub-rows** (rule / tool / parameter / artifact), each carrying **exactly one** of the seven dispositions — **INHERIT · BIND · EXCLUDE · SUPERSEDE · CONFLICT · MIGRATE · DEFER** [dispositions: PROT §5; sub-row grammar: PROT §4, ratified via ASSESS §9 item 7 / P-008; TF1-15; KM-05; executed: ASSESS §3, ~45 sub-rows] — with the split recorded, never smoothed.
4. **Classification source of record: FRACTAL Architecture State §6 *as shipped in the pinned target release*.** Its kernel/parameterized/instance partition governs classification through the tagged Register's upper edge; where any advisory or hint disagrees, **that pinned §6 wins**. Mother-side edits to §6 reach a child only through the next release the child sovereignly pins — never at run time [TF1-11; TF1-14; KM-01/KM-03; §1.5 no-live-coupling; PROT rule 1; executed: RCPT §4 "the maintained partition in FRACTAL Architecture State §6 governs classification **through C-115**"]. GENESIS §3.4's inheritance clause anchors the child's *baseline lower edge only*; it ships stale at its own release and must not classify the delta.
5. **Instance-birth-document EXCLUDE rows are pre-printed.** The child's root `GENESIS.md` and `BOOTSTRAP.md` are never overwritten — the birth record is frozen history; BOOTSTRAP may advance its *content* under its own retained identity [executed: ASSESS §3 root rows + §5 Bootstrap binding row; `BOOTSTRAP.md` modified in `6c71bb4` with KNet identity retained]. Also pre-printed EXCLUDE: mother store, contexts, Register rows, and biography [TF1-1, High; executed: VAL §2 identity PASS].
6. **The conflict register** stops at the human gate and names its class. Classes include child-vs-kernel conflicts **and the upstream-internal class** — mother-vs-mother contradictions (advisory hint vs the pinned Architecture State §6: the pinned partition wins; packet claims about child state the child's corpus does not contain: treat as recommendations, infer no state) [TF1-14; TF1-16; KM-01; KM-02; ratified PROT §9.1].
7. **Tool discipline.** A kernel tool carrying instance-named constants (known: `close.py`'s `Fractal_` alias regex; the fieldnote roster) is **BIND/MIGRATE, never plain INHERIT** — or DEFER if the tool class itself is unadopted [TF1-4; ADD instr. 13; executed: C-112.b DEFER]. A child's **locally-ahead tool wins** over the kernel copy when the kernel copy fails the child's evidenced facts; record it as a local binding, not drift to erase [KM-08, doctor.py]. Tool availability never silently creates governing authority [PROT §5; executed: stats.py deferred despite a TF1 green].
8. **The frozen-assessment discipline.** The Gate-2 assessment freezes at Gate-3 acceptance and is never edited to describe execution; execution proof lives only in the validation record [executed: ASSESS §1 vs VAL — the anti-laundering separation].

## §4 The change-set (Gate 4)

1. **Branch discipline.** All changes on a dedicated migration branch off the pushed Gate-0 checkpoint; applied source-first (provenance → inherited sources → bindings and mechanisms → contexts/index/board last); landed only whole [PROT §6; executed: VAL §1, branch `codex/fractal-beta-0.5-migration`].
2. **Manifest maintenance.** Every newly adopted kernel file is appended to `.inherited` **in the same change-set**, one line per file, **bidirectionally paired** to its matrix row: every manifest addition traces to one INHERIT/MIGRATE row, and every such row resolves to an actual file. Child-authored files never enter the manifest. The manifest's mechanics are fixed by the tooling: it lives at `Claude/Knowledge Graph Store/.inherited` — beside `check_versions.py`, which hard-codes that location, where `genesis.py` writes it at birth — one **repo-relative** path per line (absolute or `../` paths are hard errors), `#` comments permitted; its companion `.version-registry` projection lives in the same directory. (No shipped tool appends; sanctioned hand-editing until the §7 tooling lands.) [TF1-2, High; KM-06; ADD instr. 16; mechanics: check_versions.py `inherited_registry()`, genesis.py manifest write; executed: VAL §2, 12 additions paired both directions]
3. **Prose-half residence.** An adopted standard's document either joins the child's governance tree as an inherited copy at its pinned edition (+ `.inherited` entry) or is cited at the pinned anchored release; the child's self-containment rule decides. The §2.8 bundle is the tested third leg for full independence [TF1-12; ADD instr. 14; executed: ASSESS §7.2, nine standards copied at pinned editions].
4. **Adapter re-projection duty.** Every client adapter is re-projected from the newly adopted Settings and restamped in the same change-set; multiple adapters carry identical rules; all adapters join the strict version scope [executed: ASSESS §7.3, VAL §2 Adapters row — dual CLAUDE.md/AGENTS.md]. Where the instance runs `check_versions.py` at all — the tool class is shipped ready-to-adopt, never demanded (GENESIS §6, the C-081 gate) — its `.version-registry` projection is updated wherever living documents are renamed or re-pointed [executed: KNet `.version-registry` update; check_versions.py `living_overrides` mechanism].
5. **Post-birth kit installs (the retrofit pattern).** Newborn components arrive by hand-rolled install, **each a per-component recorded decision**; newborn-only components are **never** retrofitted; pre-retrofit absence is conformant state, not damage. The concrete per-release component sets — which files, which command surfaces — are per-release advisory content and live in the §8.6 supplement, because they depend on the release's component roster and the child's client surfaces (command files are adapter-tier per C-097; a child on other surfaces has none) [TF1-10, High; TF1-13; ADD instr. 8/18; executed: VAL §2 fieldnote-boundary and adapters/opener PASS — the beta-0.5 exemplar set: named opener + fieldnote door].

## §5 Validation (Gate 5 — the semantic gate)

1. **Green checkers are necessary and insufficient.** The `.inherited` exemption is purely path-based: a naive copy fails loud, but a naive copy **plus an unaudited manifest append launders destruction green** [TF1-3 — destroyed birth documents passed with 204 citations exempted; ADD danger model].
2. Two semantic checks are therefore mandatory: **(a)** diff every instance-class document's Version/Author identity stamps against the Gate-0 checkpoint; **(b)** verify manifest-to-matrix pairing in both directions — an unmatched exemption is itself a finding and fails the gate [TF1-3; KM-07; ratified PROT §9.3; executed: ASSESS §8 checks 7–8, both PASS in VAL §2].
3. **Scratch-clone rehydration is the landing gate.** In an isolated location with no mother checkout reachable: clone the Gate-0 checkpoint clean, **apply the exact staged migration change-set to it**, then prove on the candidate — all checkers reproduce, the retained bundle clones independently, the tag signature re-verifies, plus the instance's own content checks (the KNet exemplar: 16 PDF hashes re-verified) [PROT rule 6 self-contained rehydration + §6 Gate 5 "prove in a scratch clone"; executed: VAL §4 — "the exact staged candidate was applied to a clean clone of the Gate 0 history"]. Validating only the pre-migration checkpoint proves nothing about the migration; the applied candidate is what must rehydrate.
4. A validation plan covers at least these **categories** (values are per-release/per-child): release-pack integrity · upstream authenticity · store fold · version agreement · health/secrets · source parity (imported files byte-match the tag) · preserved-local-machinery blob identity · matrix/manifest pairing · semantic identity · namespace separation · adapters/opener · isolated rehydration — plus **instance-parameterized rows** for the child's own content-safety obligations (experiment boundaries, corpus/PDF hash re-verification, or the instance's equivalents) [executed: ASSESS §8's 15-point plan; VAL §2's 16 rows — **15 PASS plus the disclosed-pending timestamp row**, itself the §2.6 pendency doctrine executed].
5. **Verification-boundary honesty.** Record what could *not* be checked and what compensated; never present a compensation as the missing check [executed: RCPT §3 / VAL §6 — two-explorer header agreement recorded in lieu of a local node].

## §6 Landing and records (Gate 6)

1. Land as **one reviewed change-set**: fast-forward from the migration branch, a single `[GOV]` adoption commit, pushed [PROT §6; executed: `6c71bb4`, 42 files].
2. The committed record set: the **receipt** in its final state (pendency disclosed if unresolved); the **frozen assessment**; the **validation record**; the **decision-register row** naming the exact accepted commit, the resolved conflicts, and any procedure amendments; the migration **return package** [executed: RCPT/ASSESS/VAL/P-008/RP-MIG all in the change-set].
3. Post-landing cures (timestamp finality, deferred items maturing) land as separate forward commits; the receipt upgrades by **appending the final evidence as a new section, keeping both receipt hashes and the substance of the historical Gate-5 verdict — prior prose may be restated, the recorded verdict never reversed** [PROT §9.6/§7; executed: `846503c`, RCPT v0.2→v0.3 keeping both `.ots` hashes and the pending-at-Gate-5 substance].
4. **The feedback offer.** The mother asks for the migration's frictions and greens through the owner — the §8.5 feedback ask [PKT §5, the C-094 loop; ADD instr. 21]. Offering them is the **child's choice**: a never-reporting child is fully conformant (the mirror of Registry rule 5 and GENESIS §7.4). The material lands in the mother's ledger, via the owner's hand only [C-096; executed mother-side: OQ-33 → this document]. §8.5 carries the only normative weight of this loop; nothing here adds a child-side Gate-6 duty.

## §7 The checker half — honest status (Registry contract rule 2)

**Status: prose-first; checker triggers named.** What exists mechanically today: `verify.py` (store gate, incl. the C-114 `vocabulary_local.json` extension hook); `check_versions.py` (version agreement, the path-based `.inherited` exemption, the `.version-registry` instance projection); `doctor.py`; the signed-tag + fsck + bundle Git machinery of §2 [executed: all exercised green in VAL §2]. What does **not** exist, with build triggers:

1. **`adopt <path>` manifest subcommand** — appends to `.inherited` and enforces the §4.2 matrix-row pairing. Trigger: the second executed migration, or the first hand-pairing failure [TF1-2; ADD instr. 20].
2. **`genesis.py --retrofit`** — tooled §4.5 kit install (genesis.py is birth-only by explicit refusal). Trigger: the second retrofit demand [TF1-10; ADD instr. 21].
3. **The clause-span pack-time check** — GENESIS §3.4's clause upper bound = the Register's max C-number at tag time (mother-side; genesis.py reads the clause live, so staleness propagates into newborns mechanically). Trigger: the next C-090 tagging close [TF1-11; ADD instr. 9/22].
4. **Mechanized §5.2 semantic checks** in check_versions.py (stamp-diff + pairing). Trigger: the first semantic-check failure found by hand, or the third migration [TF1-3].
5. **Delta-inventory generator + machine-readable §6 partition** — mechanical derivation of the §8.3 inventory (Register rows since the child's baseline × Architecture State §6 classes). §6's partition is maintained as narrative prose today, so derivation is by hand until this lands. Trigger: the second advisory authored, or the first hand-derivation error found.

Until a trigger fires, the hand procedures in §§2–6 are the standard — each was executed once end-to-end and passed [executed: the full KNet migration, VAL §5 "Gate 5 passes"].

## §8 What the mother owes per release (the advisory template)

Hand-written packets are retired: TF1 found five defects in the one hand-written packet (missing signers bind, key-label phrasing, impossible in-tree receipt citation, live remote, unverified child-state claims) [TF1-5/6/7/8/16]. Each anchored release ships an advisory **hand-instantiated from this template** (mechanically generated once §7.5 lands):

1. **Pin identity** — tag name, commit SHA, tag-object SHA, signing-key fingerprint + principal (never a label), and the §2.3 signers-bind line verbatim [TF1-5/8].
2. **Transport** — the §2.7 recipe including `git remote remove origin`, and the bundle option [TF1-7].
3. **Delta inventory** — hand-derived from the two named sources (Register rows since the child's baseline × the pinned Architecture State §6 partition — read by a person until §7.5 exists); disposition *hints* cite the pinned §6 and never freelance a classification [TF1-14; KM-01]; any claim about child state cites the child file read at a C-096 look, or is phrased as a recommendation [TF1-16; KM-02].
4. **Receipt hand-off** — the receipt pair supplied separately with the structural-absence note and current OTS state [TF1-6].
5. **The feedback ask** — the C-094 fieldnote loop closing the seam, always phrased as an ask through the owner, never a child-side duty [PKT §5; ADD instr. 21].
6. **The retrofit component set** — the release's newborn-kit components with exact per-component file sets for post-birth install under the §4.5 pattern, scoped to the child's actual client surfaces; newborn-only components named as never-retrofit. (The beta-0.5 set: the named opener's command file, obsolete opener deleted, plain vocabulary kept; the fieldnote door — `fieldnote.py` + self-targeted roster + root ledger + command file + parameter-7 growth recorded without rewriting the genesis fact; First Loops Rail excluded.) [TF1-10/13; ADD instr. 8/18]
7. **Pack-time hygiene** (owed once, checked per release): the §7.3 clause-span check; migration-proof GENESIS §5 shelf pointers; qualified GUIDE newborn phrasing; the Registry §1.5 residence clause; the close.py prefix parameterization [ADD instr. 22 slate — landing proposed at the UF1 close, see the cure change-set].
8. **Optional pre-flight**: a TF1-style dress rehearsal (adversarial probes + independent refuter, sandboxed pinned clones, child-sandbox probes serialized) whose surviving findings feed the per-release supplement [Flight_2026-08-17 method note, incl. the shared-sandbox false-positive lesson].

---

**Refresh triggers:** the next executed migration (any child, any release); a §7 build trigger firing; a change to Architecture State §6's partition mechanics; a C-094 fieldnote showing a clause misses or misleads.
**Revision history:** v0.1 (2026-08-17) drafted by the UF1 flight from the executed KNet beta-0.1→beta-0.5 migration (P-007/P-008), the TF1 test flight (17 findings, all confirmed real in execution), and the beta-0.5 kernel literature; corrected in the same flight by a three-track refutation pass (18 unique defects cured — the append-only overclaim weakened to the executed shape, the §6 classification source pinned to the release, the rehydration gate restated as apply-then-prove, five citation pointers repaired, release-specific content moved to §8). Ratified the same day as C-117 (per Protocol v0.53, Max's "go with (a)" — the restatable-receipt doctrine his explicit call); Registry §2 row landed in the same change-set.