V48 (specification-only): Require FAMILIARIZATION.md stay current with changes

Add BITCODE_SPECIFYING.md §16.3.1 law that the repository familiarization map
must update with structural changes (package families, hierarchy, experience
paths, routes). Mirror the duty in AGENTS.md, FAMILIARIZATION maintenance, and
V48 notes; tie it to Complete Implementation Derivability commit discipline.

Author: geraldarthurdavis

AGENTS.md

@@ -4,7 +4,7 @@
 - Never explicitly version source code without direct instruction. Source code is always implicitly versioned to the active Bitcode canon and current gate; routes, file names, CSS files, constants, classes, API paths, tests, and implementation identifiers must be written in-place as the single current Bitcode system. Do not introduce names such as `api/v1`, `v27-*`, `first-gate-*`, `wip-*`, or similar version/gate/work-in-progress source constructs unless explicitly directed for a bounded compatibility artifact.
 - Do not consider any legacy code. All legacy code is located under `_legacy/`.
 - **Source layout and modularity (required):** follow `internal-docs/BITCODE_SOURCE_LAYOUT.md` and `uapi/components/README.md`. Dependency direction is `packages` → Bitcode/Shadcn adapters → experience components → thin `uapi/app` page shells. Seven experiences (Marketing, Packs, Reads, Deposits, Docs, Conversations, Auxillaries) plus `Shadcn*` / `Bitcode*` bases. New components live in **named directories** (`ComponentName/ComponentName.tsx` — not `index.tsx`) with co-located `hooks/`, `styles/`, `__tests__/`. Prefer packages for pure domain logic. Product run language is **Pipeline**; BTD ledger language is **journal**. **Do not reintroduce Terminal** (`app/terminal` is deleted; no `/terminal` product route).
-- **Codebase familiarization:** read `FAMILIARIZATION.md` for the package catalog, uapi request path, and the inheritance pattern `*-generics` primitives → `generic-*` base implementations → product specializations (agents, tools, pipelines, prompts, LLMs).
+- **Codebase familiarization:** read `FAMILIARIZATION.md` for the package catalog, uapi request path, and the inheritance pattern `*-generics` primitives → `generic-*` base implementations → product specializations (agents, tools, pipelines, prompts, LLMs). **Keep `FAMILIARIZATION.md` up to date with changes** (`BITCODE_SPECIFYING.md` §16.3.1): any change that moves package families, inheritance hierarchy, experience entry paths, product routes, or other structure the guide teaches must update `FAMILIARIZATION.md` in the same change set (accurate short section edits preferred).
 - Highest caliber software engineering crafstmanship (maintainibility, abstractions, architectures, naming, patterns, comments, documentation, structures, algorithmic and data flow designs, UI/UX, etc.), correctness (specification and implementation precision, reliability, completeness, boundaried, scoped, encapsulated, etc.), and auditable (totalistic proofs systems from static code, build time, runtime, etc. etc. as is Bitcode, tests from unit, integration, E2E, linting and building, etc.). Every non-trivial file carries a top-of-file overview comment; obey SRP and DRY; co-locate unit tests with components when practical.
 - Do not push work directly to `main`. Create a version base branch for each draft target, such as `version/v28`, then create scoped gate branches from that version branch. Gate branches must be prefixed with the gate number, such as `v28/gate-3-read-fit-workflow` or `v28/gate-8-promotion-proof`. Pull-request each closed gate back into the version branch. Pull-request the version branch into `main` only when all gates are closed and the version is formally promoted as canon. The default branch is protected by the `Bitcode Core Contributions` ruleset and requires pull requests plus verified signatures.
 - Gate pull request titles must begin with the uppercase version and gate prefix, followed by a concise topical title, for example `V29 Gate 5: AssetPack Disclosure Rights And Preview Depth`. Version-promotion pull requests must begin with the uppercase version and name canonical promotion.

BITCODE_SPECIFYING.md

@@ -253,6 +253,12 @@ is incomplete: the specification must be brought to cover it (as
 outruns its spec. The specification↔implementation relationship of every change is
 thereby auditable from the commit history alone.
 
+When a change alters package families, inheritance hierarchy, experience entry
+paths, product routes, or other structure that `FAMILIARIZATION.md` teaches,
+that map must be updated with the change (see §16.3.1). Leaving the
+familiarization map stale while source moves is the same class of failure as
+leaving implementation undocumentable from the active teaching surface.
+
 ---
 
 # 3. Canonical File Family
@@ -1288,6 +1294,42 @@ When a code-documentation surface teaches active behavior, the current `SPEC` mu
 - what product posture it carries,
 - and what parity or proof surface validates it.
 
+### 16.3.1 Repository Familiarization Map (`FAMILIARIZATION.md`)
+
+`FAMILIARIZATION.md` is the required in-repo deep map of current Bitcode
+implementation structure: package catalog, `uapi` request path, experience
+layout, and the inheritance pattern `*-generics` primitives → `generic-*` base
+implementations → product specializations (agents, tools, pipelines, prompts,
+LLMs, and related families).
+
+**Law:** `FAMILIARIZATION.md` must be kept up to date with changes.
+
+Any change that alters how a reader must find or understand current
+implementation structure must update `FAMILIARIZATION.md` in the same change
+set (or in a immediately accompanying `specification-implementation` /
+documentation commit that lands with that work), including at least:
+
+- new or removed package families, nested `generic-*` packages, or product pipelines,
+- inheritance hierarchy changes (primitive → base → product),
+- experience modularization that moves primary entry paths or component homes,
+- product routes, host model, or public navigation posture changes that affect
+  how operators or agents enter the system,
+- and renames or splits that would leave catalog paths, package names, or
+  hierarchy diagrams stale.
+
+Prefer accurate, short section edits over full rewrites. Stale
+`FAMILIARIZATION.md` content that contradicts current source is a specifying
+defect relative to Complete Implementation Derivability: implementers and
+agents must not recover structure only from chat history or ad-hoc exploration
+when the repository already claims a walkthrough map.
+
+`FAMILIARIZATION.md` is explanatory/operational teaching of current structure,
+not a parallel product-semantics canon. Product law remains in the active
+`BITCODE_SPEC_VN` family. Layout contracts that bind filesystem placement
+remain in `internal-docs/BITCODE_SOURCE_LAYOUT.md` and related architecture
+docs; those surfaces and `FAMILIARIZATION.md` must not diverge on named paths
+or hierarchy without an intentional, documented update.
+
 ## 16.4 Boundary Honesty
 
 Accepted boundaries are allowed.

BITCODE_SPEC_V48_NOTES.md

@@ -1453,6 +1453,14 @@ Public package export paths preserved. Jest deposit/depository/synthesis suites
 
 
 
+## FAMILIARIZATION maintenance law (Garrett, 2026-07-13)
+
+`BITCODE_SPECIFYING.md` §16.3.1 now requires `FAMILIARIZATION.md` to stay
+current with structural changes (package families, inheritance hierarchy,
+experience entry paths, product routes). Operational mirror: `AGENTS.md`.
+This is part of Complete Implementation Derivability teaching surfaces, not a
+parallel product-semantics canon.
+
 ## FAMILIARIZATION.md (codebase walkthrough)
 
 `FAMILIARIZATION.md` is the in-repo deep map of packages, uapi, and inheritance

FAMILIARIZATION.md

@@ -590,14 +590,21 @@ as if they were source of product law.
 
 ## 11. Maintenance of this guide
 
+**Specifying law** (`BITCODE_SPECIFYING.md` §16.3.1): this file **must** be
+kept up to date with structural changes. Stale content here is a defect relative
+to Complete Implementation Derivability.
+
 Update `FAMILIARIZATION.md` when:
 
-- A new package family is introduced  
+- A new package family, nested `generic-*` package, or product pipeline is introduced or removed  
 - Experience modularization changes the primary entry paths  
-- Inheritance hierarchy gains a new layer  
-- Product routes or host model change  
+- Inheritance hierarchy gains, loses, or renames a layer  
+- Product routes, host model, or public navigation posture change  
+- Catalog paths, package names, or hierarchy diagrams would otherwise go stale  
 
 Prefer **accurate, short section edits** over rewriting the whole file each time.
+Land the edit with the structural change (same commit or accompanying
+`specification-implementation` / documentation commit).
 
 ---