S436 — OKF Storage-Medium + Human-Review-Bridge Adjudication

Task: adjudicate ONLY the storage/versioning MEDIUM for the OKF bundle (L-concepts) + the non-technical human-review bridge. Read-only (this artefact is the sole write). Ratified context honoured, not re-litigated: D2 base ruling (client owns the artefact; consumption via app/viewer/MCP; storage layer is never the security boundary; direct git = optional privilege, not a product surface); the (A) two-layer derivation model (reframe §2.3); id-132 BI-14/BI-19; DR-012/013/014. Date: 2026-07-02.

A. Does the bundle NEED git? (git-repo vs client-local-fs vs fs+object-store-snapshot hybrid)

The owner’s fork is a FALSE fork — and it is already ratified as false. Reframe §2.3 D8-RECONFIRMED (line 278): “a git working-tree IS the local-fs folder cocoindex walks; commit/push/rollback is an additive operator layer.” Git does not take the files off local-fs — the .md files sit on disk exactly as a plain folder would; git adds a .git alongside them. So “git repo or local-fs” is really “plain folder vs plain folder + a near-free rollback/audit/diff layer.” The honest question is therefore: do we need that layer, or can we get its four capabilities more cheaply another way?

Dimension	git repo	plain client-local-fs	fs + object-store snapshot
Point-in-time rollback	Native, per-change, free	None (last-write-wins); must build a version store	Coarse (per-snapshot interval), not per-change
Audit / authorship trail	Native (author + message + timestamp per change)	None (fs mtime only; no author, no message)	Snapshot-job metadata only; no per-concept authorship
Atomic publish	Atomic at commit; consumers read committed state, never a half-written tree (and ours read via DB/API per ID-115, not the tree — doubly safe)	NOT atomic; a reader can catch a partial mid-regeneration dir unless you build write-temp-then-rename	Snapshot atomic; live working dir is not
Diff-ability for the review bridge	Native `git diff` between any two commits = the substrate the accept/edit/reject bridge binds to	Must retain your own “previous” copy + a diff engine = reinventing git’s object store + diff	Diff between snapshots only (coarse); still needs a diff engine
Non-technical-user burden	ZERO — user never touches the medium	ZERO (same)	ZERO (same)
Ops burden per client	One private repo + push credential (modest, well-trodden; producer already runs where the working tree lives)	Lowest infra — but you then OWE rollback+audit+atomic+diff machinery (far more to build/run than a repo)	Dir + bucket + snapshot cron; still owes per-change audit/diff
Client-ownership / exportability optics	Strongest — “clone your repo, full authorship history is yours”; the literal embodiment of “we don’t extract your value”	Weak — “here’s a folder”, no history to hand over	Weak on authorship — “folder + backups”
Interplay with L-raw staying client-side	L-concepts is a DERIVED layer; its git dir ≠ L-raw. D8: git tree = a local-fs folder → no contradiction. Client owns the REMOTE; the platform-operated producer writes a working tree it controls + pushes	Pure “client’s-own-machine local-fs” for L-concepts breaks the platform-operated producer (it can’t write to the client’s laptop)	Same producer-write problem as local-fs; bucket is platform-side anyway
Cost	≈ free (GitHub private, or Coolify-S3 as a git-remote/backup host — FB7/D8)	Free disk — but reinvented machinery is the real cost	Minor object-store cost + cron

Verdict: KEEP git. The bridge’s three load-bearing needs — rollback, per-change authorship, and a diff between last-approved and new output — are exactly what git provides for free, and exactly what plain local-fs would force us to reinvent (badly). The hybrid is strictly worse than git for the bridge (coarse diff, no per-change authorship) at added infra cost. What plain local-fs genuinely loses: rollback, per-change audit/authorship, atomic publish, and the diff substrate — i.e. everything the review bridge is built on, plus the strongest expression of the client-ownership narrative OKF exists to project. Non-technical-user burden is identical (zero) across all three because it is a property of the bridge, not the medium. Git also uniquely resolves the “platform-operated producer writes to a client-owned artefact” problem: ownership lives in the client-owned remote; write-access lives in the producer’s working tree.

B. The review bridge — design sketch (WITHOUT git in the user’s hands)

Hooks: producer output → staged diff → in-app accept/edit/reject → publish/commit.

Producer runs to a STAGING state, never straight to published. Each run’s declare_file output + TECH §356’s 3-way reconcile yields a proposed-change set (concepts added/changed/removed/moved) — the same content already written to log.md (BI-11), now also emitted machine-readable. The staged diff = git diff published..staging.
The bridge surfaces that diff IN-APP (not git): a review queue, one row per changed concept, each with a rendered before/after markdown diff. Reuse the id-117 version-chain leg (DR-013): lib/source-documents/document-diff.ts (computeDocumentDiff/computeFullTextDiff), the app/documents/[id]/diff/page.tsx pattern, components/diff/* panes, source-document-history.tsx.
A privileged user (admin/editor) picks Accept / Edit / Reject per change — the approve/reject shape from /api/governance/review + the id-120.7 curator approve/reject routes:
- Accept → the change merges into published (a platform-made commit; the user never runs git).
- Reject → dropped; published concept retained; a decision-marker prevents identical re-proposal.
- Edit → the user’s edited markdown is saved as a producer OVERRIDE (structured store keyed by concept_path + section / frontmatter-field), THEN committed to published.
The override store closes the v3-critic gap. On the NEXT regeneration the producer applies overrides ON TOP of its fresh Pass-1/Pass-2 draft before diffing (draft → apply overrides → diff → propose). An approved human edit is thus re-applied every run — it survives declare_file’s fingerprint-overwrite/orphan-delete because it is a producer input, never a file mutation the engine can clobber. This upgrades TECH §356 from “flag divergence, leave file in place” to “flag → capture-as-override → re-apply.”
Publish gate unchanged (BI-20/BI-21): first publish stays HARD-gated on the green seed-contract; the bridge merely feeds ACCEPTED state into it.

Net: humans never commit directly (no producer-vs-human merge war), edits live as inputs (idempotent over regeneration), and TECH’s inert “flag” becomes an actionable accept/edit/reject decision.

C. Recommendation (one target model)

Keep the ratified client-owned git-repo model (id-132 BI-14/BI-19 STAND). For a non-technical owner: “Yes, keep git — but ‘git vs your folder’ is a false choice. A git repo is just your folder with a memory: the files sit on disk exactly like a plain folder, and git quietly keeps every past version beside them. Your users never see git. They see one review screen — ‘here’s what changed in your knowledge map: accept / edit / reject’ — and the git layer underneath is what makes that screen possible (it is where the before/after comparison comes from) and what lets us roll back a bad change. A plain folder would mean rebuilding that memory ourselves — worse, and later.”

What changes in id-132’s spec:

Add ONE producer invariant now (id-132): approved human edits are captured as producer OVERRIDES (keyed by concept_path + section), re-applied on every regeneration — never direct file mutations. This is a producer contract that shapes how the producer merges; retrofitting “edits are inputs, not mutations” AFTER first publish is exactly the irreversible-contract class id-132 owns, so it must be ratified/frozen before first publish. It upgrades TECH §356 (BI-22 reconcile) from flag to flag + capture-as-override + re-apply, and requires the producer to EMIT the staged proposed-change set in a machine-readable form (it already computes it for log.md).
No change to BI-14/BI-19/BI-20/BI-21 (git ownership, one-commit-per-run, first-publish gate).

Invariant now vs follow-on task:

id-132 invariant NOW: the data-safety mechanism (managed-keyset boundary + 3-way reconcile + the new override-capture contract). Without it, regeneration silently destroys human edits — a producer correctness property, not a UI nicety.
Follow-on task (id-135-adjacent, DR-013 shape): the user-facing accept/edit/reject review UI + the diff surface. It is a net-new human surface — the same class DR-013 routes to id-135 — so it should NOT be crammed into id-132’s backend-producer scope. id-132 must only guarantee the producer EMITS the staged diff + honours overrides; the UI binds to that later, reusing the id-117 diff leg + governance-review + id-120.7 approve/reject patterns.

D. DR-intent draft (for the decision register — NOT written here)

OKF bundles remain in a client-owned git repository (id-132 BI-14/BI-19 stand). “Git vs local-fs” is a false fork: the git working tree IS the local-fs folder (reframe D8), and git adds near-free point-in-time rollback, per-change authorship/audit, atomic publish, and the diff substrate the human-review bridge depends on — all of which plain local-fs would force us to reinvent, and a snapshot hybrid delivers only coarsely at added cost. The storage medium is never a product surface for the non-technical user; a platform-mediated accept/edit/reject bridge is. To close the v3-critic human-edit-vs-regeneration gap, approved human edits are captured as producer overrides (keyed by concept-path/section) re-applied on every regeneration — never direct file mutations — making this a producer invariant id-132 must freeze before first publish. The user-facing review UI (reusing the id-117 diff leg + governance-review + curator approve/reject patterns) is a net-new human surface deferred to a follow-on (id-135-adjacent, DR-013 shape).