feedback_snapshot_vs_floor_pin_discipline

Rule: BUILD-PLAN-style files (and any cross-referencing markdown that pins versions of OTHER live files) use two distinct kinds of version-pin, and they have different semantics. NEVER conflate them.

Kind	Purpose	Bumps when?	Example
Snapshot-pin	records a historical fact (extraction/derivation provenance)	NEVER — it records what was true at extraction time	canonical_role: "Extracted from master plan v1.4 per Rich 2026-04-28" / changelog row “extracted from master plan v1.4 (now v1.5)“
Floor-pin	records the minimum live version the BUILD-PLAN content is consistent with	Each /review-plan reconciliation pass when the referenced doc has advanced beyond the prior floor’s content-equivalence threshold	Body text “see arch-state floor-pin v3.0+” / “master plan floor-pin v1.8+”

Both kinds carry a current-at-reconciliation parenthetical (e.g. current v3.8 at this v1.2 reconciliation) so the reader can see staleness without checking the referenced file’s lastmod.

Why: BUILD-PLAN v1.1 (2026-04-28T08:00) was authored against master-plan v1.5 + arch-state v2.92. By 19:45 the same day, master-plan was v1.8 + arch-state was v3.8 — an 11-hour drift cycle. The v1.1 §6 self-prescription “If the master plan has advanced beyond v1.5, re-verify” assumed all “v1.5+” pins were floor-pins, but canonical_role: "extracted from v1.5" was actually a snapshot-pin (extraction provenance). Treating snapshots as floor-pins would have falsely flagged v1.1 as drifted at extraction time. Treating floor-pins as snapshots would have left them stale forever. Distinguishing them resolves both errors.

How to apply:

1. At authoring time, label every version-reference as either snapshot or floor in the surrounding prose. Don’t make readers infer.
2. At /review-plan reconciliation, only the floor-pins need bumping. Snapshot pins on stale references are deliberate provenance, NOT drift.
3. Floor-pins must include a (current vX.Y at this vN.M reconciliation) parenthetical — otherwise readers cannot tell how stale the floor has become.
4. Snapshot-pins should reference the historical version explicitly (“extracted from v1.4 per …”), not v1.4+ syntax. The + floor-syntax is reserved for live cross-references.
5. Pre-commit pin-drift hooks should check floor-pins against current target file version:, NOT snapshot-pins. The current check-frontmatter-pins.py walks companion_files: { version_pinned } blocks — these are floor-pins by convention. (Hook extension to legacy frontmatter patterns tracked at richard-tasks-tt.md #182.)

Anti-patterns observed in BUILD-PLAN v1.1:

• Mixing both pin types in same paragraph without label
• Bumping snapshot-pins on each pass (would break extraction-provenance audit trail)
• Floor-pins with no current-at parenthetical (drift becomes invisible until next reconciliation)
• §6 drift-detection text that conflated the two and self-prescribed re-verification on snapshot drift

Documented in: code-inherit-v2/BUILD-PLAN.md v1.2 §6.1 (canonical implementation reference) — copy this discipline forward when bumping sister BUILD-PLANs (code-inheritkit / code-ias / code-inheritv2-www / code-inheritv2-test-suite) from v1.1 → v1.2.