S436 spec/ledger state audit — OKF chain, goose, Raindrop, forms retirement

S436 spec-state audit

Citations: docs-site = ${KH_PRIVATE_DOCS_DIR}/src/content/docs/. Ledger via bun scripts/ledger-cli.ts (read-only).

Q1 — id-132: is git repo purely a versioning/audit/rollback substrate that clients do NOT access directly?

VERDICT: GAP (on the “clients won’t access git directly / git = pure substrate” claim; the versioning/rollback/audit purpose is partially present).

Evidence — id-132 specs/id-132-okf-concept-producer/PRODUCT.md:

BI-14 (lines 240–244): “The bundle lives in a client-owned private git repository — not inside the Canonical application repo and not in the L-records DB. Canonical operates the producer; the client owns the artefact… This is what makes ‘we don’t extract your value / you keep your canonical files’ literally true.”
BI-19 (lines 269–273): “A git ‘knowledge-sync’ writer, outside cocoindex, commits producer output to the client-owned private repo and supports point-in-time rollback… The git layer is what makes the bundle versioned and the irreversibility (Group E) durable.”
TECH.md §Git knowledge-sync (lines 358–360): “commits to the client-owned private repository — one commit per producer run (ratified), with point-in-time rollback via the git history.” Auditability implicit via BI-11 log.md (append-only change history, one block/run).

Analysis: The rollback + versioning + audit-substrate purpose IS spec’d (BI-19 + one-commit-per-run + BI-11 log.md). But no invariant states clients will not access git directly, and BI-14 frames the repo as a client-OWNED artefact with “you keep your canonical files” — an access-positive framing that cuts against “git is a backend substrate clients never touch.” The intended human/AI consumption surface (read-only viewer TECH §Viewer, id-135 UI, wholesale context-load BI-24, vector index BI-25) is spec’d, but the chain never says “…and therefore the client consumes via the app, not git.” The s435 explainer’s mental model (“git purely for observability/audit/rollback”) is not what the spec asserts.

Proposed fix (proposal only): Add an explicit access-model note to id-132 PRODUCT (or the client-deployment runbook) resolving: is the client granted git access (BI-14 ownership implies yes) or does it consume ONLY via app/viewer/MCP with git as a Canonical-operated audit/rollback substrate? Reconcile BI-14 with the s435 “backend substrate” framing.

Q2 — id-132/id-131: OKF change-propagation — what triggers concept create/update when source_documents change?

VERDICT: PARTIAL (incremental delta mechanism covered; run trigger/cadence/staleness UNSPECIFIED).

Evidence:

id-132 PRODUCT BI-18 (lines 265–267): producer is incremental — “re-running regenerates only concepts whose source records/corpus changed (the declare_file memoised FILE-target pattern)… A no-op re-run produces a no-op diff.” → covers WHAT regenerates.
id-132 TECH.md (lines 151–153): producer “invoked as a discrete producer command — NOT folded into the ingest walk (different cadence, different source, different irreversibility profile).” → “different cadence” is named but never pinned.
id-132 subtasks (task 132, 14 subtasks G-SOURCE…G-VIEWER): none is a trigger/cadence/staleness subtask; delta-only lives inside {132.10} G-BUNDLE (no-op-diff test). No subtask fires the producer on record change.
id-131 PRODUCT BI-18/BI-22 (lines 243–283): record_lifecycle freshness/expiry axis is {source_document}-only (cron-driven), but nothing links record staleness → OKF producer re-run.

Analysis: The producer knows how to regenerate incrementally, but what invokes it when source_documents are added/changed is undefined — no post-ingest hook, no cron/schedule, no staleness watcher on source_documents.updated_at/content_hash. It is an operator-invoked CLI command with an unpinned “different cadence.”

Proposed fix: Add a producer-run trigger/cadence subtask/section to id-132 (e.g. pipeline-runs webhook fires the producer post-walk, OR a scheduled cadence, OR a staleness-driven trigger keyed on source_documents deltas).

Q3 — id-134: (a) spec chain updated post-{134.6}/{134.7} re-spec? (b) synthetic OKF for Platform E2E corpus?

(a) VERDICT: STALE — TECH.md NOT updated; re-spec is journal-only.

specs/id-134-promotion-confidence-e2e/ contains only TECH.md (dated 28 Jun 01:23; no PRODUCT/PLAN). It still specs the retired forms machinery:

Forms folder §2.1 tree: forms/procurement/synthetic-sq-officesupplies.pdf + synthetic-itt-groundsmaint.docx (forms route · PDF/DOCX).
Forms manifest binding §1.3 + RATIFY-1b: root manifest binds forms/procurement/ → Platform — Procurement; the forms workspace_id is “the one per-target-variable value.”
G3 §4.2: “form_templates WHERE op_id=run = 2, each workspace_id = Platform — Procurement.”
G5 §4.2: content_items(succ) = 5 (id-131 eliminates content_items).

The re-spec lives ONLY in the pending subtask journals (both pending, “PAUSED” per task-134 status_note):

{134.6} journal (S429, 2026-06-28): “id-134 spec authored last-night predates the wider OKF work; do NOT build the gate off the stale spec… RE-DERIVE G1–G9 via a fresh Planner pass” — G5 replace content_items→source_documents/q_a_pairs; G3 form_templates has NO op_id column (proven by S429 prod+staging walks). Correction same session: “forms need NO structure manifest… forms are MANUALLY-UPLOADED, NOT corpus-walked.”
{134.7} journal (S430, 2026-06-30): “DROP all forms-route language: forms are manual-upload… the gate does not assert form_templates.” M5 follow-up: content_chunks.embedding→record_embeddings(owner_kind=content_chunk).
task-134 status_note: “{134.6}/{134.7} PAUSED — fresh Planner re-spec vs id-131(content_items gone, G5), id-133, id-128 + DROP forms route/G3.”

(NB the brief said “S434 re-spec”; the journals are actually dated S429/S430. task-134 session_refs is empty [].) Matches s435 §(g) flag #7.

Proposed fix: Run the fresh-Planner re-spec named in {134.6} to re-author id-134 TECH.md (drop forms folder/manifest/G3; re-home G5→source_documents/q_a_pairs, G6 content_chunks→record_embeddings); OR add a “SUPERSEDED — see {134.6}/{134.7} journals + BL-392” banner to TECH.md until it lands.

(b) VERDICT: GAP — no synthetic OKF bundle spec’d for Platform E2E (need acknowledged, deferred).

id-134 chain: no mention of an OKF concept bundle for the Platform corpus (it covers L-records ingest + the row-delta gate only).
id-132 TECH.md D10 coordination note (lines 364–370): “The producer’s git knowledge-sync writer is what physically creates the OKF bundle repo. The ratified ID-134 corpus-ownership call (D10: commit the corpus in-repo for now, defer a standalone Platform OKF repo, and keep a synced copy outside the main repo for integration testing) flags that ID-132’s producer work may build the Platform OKF repo imminently — so the repo creation / ownership / naming must be coordinated with ID-134.”
No subtask in id-132 or id-134 covers producing a synthetic Platform OKF bundle.

Analysis: The need is acknowledged (D10: standalone Platform OKF repo DEFERRED; producer “may build it imminently”) but not planned. Platform has no real client corpus, so E2E-testing the id-132 producer + id-135 UI + OKF-consumer MCP requires a synthetic bundle that nothing currently specs.

Proposed fix: Add an id-132 (or id-134) subtask to produce a synthetic Platform OKF bundle from the {134} synthetic corpus and resolve the deferred D10 Platform-OKF-repo provisioning, enabling OKF-producer/id-135/consumer E2E without a client corpus.

Q4 — id-71 goose: per-client deployment (each client VPS / Server A) covered?

VERDICT: GAP — goose is scoped as a Platform-only pilot; per-client rollout is unspecified.

Evidence:

specs/id-71-ai-tooling/goose-pilot-deploy-plan.md Decision 4 (OQ-A RESOLVED, S420): “deploy on 87.106.72.59 (Server B = Platform box + Coolify control plane; client is 88.208.255.178).” Deploy gates G0–G6 describe ONE Platform-box pilot (G4 supervised first run → G5 ~7-day soak → G6 adopt). No per-client / Server-A / per-tenant goose.
id-71 PRODUCT/TECH/PLAN: the only “per-tenant” hits are PI-15 per-tenant taxonomy-sync (BROKEN since {68.23}, RETIRED Option A 2026-06-14, PRODUCT lines 638–662; TECH M42) — unrelated to goose deployment. task-71 ledger raw grep: same PI-15 hits only.
Baseline s435 §(e): goose = a Platform-VPS (Server B) pilot; {71.24} done, {71.26}/{71.27} in_progress/pilot-gated.

Analysis: goose per-client (on each client VPS / Server A, as part of client deployments) appears nowhere in the id-71 spec or ledger. It is implicitly a post-pilot-success rollout, currently unplanned.

Proposed fix: After pilot success (G6 adopt), open a per-client goose rollout Task/subtask (deploy kh-goose-pilot per client on Server A, per-tenant MCP bearer + recipe) — absent today.

Q5 — id-104 Raindrop: per-client/local-instance deployment + AI-tooling-setup story?

VERDICT: COVERED as a LOCAL dev-workflow tool wired to ID-104; per-client deployment is deliberately EXCLUDED by design (not an omission).

Evidence:

id-71 RESEARCH §475: “Raindrop Workshop (raindrop-ai/workshop, MIT) — Adopt (dev-workflow). Local per-run trace inspection + agent-authored evals. Keep usage local… Hosted Raindrop for in-platform agents = deferred.”
id-71 PRODUCT (lines 129, 262–266): “Hosted Raindrop on client data. Workshop-local only (HR-5 / WS-14)”; B-INV-15 “never via Raindrop cloud … zero client-data egress.”
id-71 TECH:604/:610: “Raindrop Workshop local viewer (localhost:5899, OTel-fed — for agents/recipes)”; “Hosted raindrop.ai stays EXCLUDED (HR-5 client-data).”
goose-pilot-deploy-plan OQ-F: “eval harness wiring into ID-104 (Raindrop Workshop-local, zero egress).”
task-104 (done, S367): “three layered surfaces (Raindrop Workshop LOCAL + create-skill viewer + KH /admin/refinement)”; lib/eval/graduation.ts zero-egress assertion (gating test); outcome-signal enum win|fail|loop|refusal = “Raindrop-derived starter set.”

Analysis: Raindrop = a local dev-workflow observability/eval-authoring tool (Workshop, localhost:5899) feeding ID-104’s KH-owned harness (evals never Raindrop-proprietary, no client-data egress). It is not a client-deployed component — “per-client Raindrop deployment” is intentionally N/A (hosted excluded; hosted-for-in-platform-agents deferred). The local-instance + AI-tooling-setup story IS covered.

Proposed fix: None on deployment (by-design local dev tooling). Optional/deferred: a client-facing agent-observability surface would be a new Task — no action now.

Q6 — v1-completion-sequence.md + task-45: does the forward map reflect current reality?

VERDICT: STALE — forward map frozen at S419 (25/06), predates the entire OKF re-architecture.

File: themes/canonical-pipeline/reference/v1-completion-sequence.md (593 lines; §Deploy-topology, §0 You-are-here, §1 lane-board, §2 cross-lane deps, §3 near-term planning order).

Stale entries:

Header “Last updated: S419 (25/06/2026)” — now 2026-07-01 (S435+); ~16 sessions / 6 days behind.
{127.4} still described as “synthetic corpus + manifest — operator file task” (header + §1 line 515) — reframed into id-134 (promotion-confidence E2E gate), and ”+ manifest” is superseded by DR-014 (forms manual-upload).
OKF still only “bl-367 (OKF spike)” backlog (lines 515, 588) — but the id-131/132/133/134 4-Task chain now exists; id-131 umbrella merged PR #110 (recent commit 40d3f244 “land OKF id-131..135 umbrella”). Not reflected.
No id-131/132/134 lanes; no “image-then-walk” sequencing; no OKF chain in §3 near-term planning order (which centres ID-130 → ID-45 Spine).
The only “umbrella” in the doc is ID-130 (procurement) (lines 452, 591), not the id-131 OKF umbrella.
task-45 corroborates the Spine still real but unmoved: in_progress; {45.1}/{45.2} done, {45.3} TECH/{45.4} PLAN DEFERRED (gated {64.7}/{64.8}/ID-57 + bl-106); subtasks {45.5}/{45.6} cutover-wiring pending.

Proposed fix: Refresh header “Last updated” + §1 lane-board + §3 planning order to add the id-131/132/133/134 OKF chain, reframe {127.4}→id-134, replace “bl-367 OKF spike” with the landed chain (PR #110), and insert image-then-walk ahead of ID-45.

Q7 — BL-392: does it capture the full forms-route retirement scope?

VERDICT: COVERED (comprehensive) — status spec_needed (not yet scheduled).

show backlog 392: “Retire corpus forms-route — forms = manual-upload (okf-v3 §8.2)”, type tech_debt, status spec_needed, priority should, track canonical-pipeline, session_refs [S430].

Scope (5 items + sequencing): (1) retire RouteKind 'forms' in scripts/cocoindex_pipeline/workspace_resolver.py:65 + the forms fork; (2) retire/repurpose the BI-7(c) gate test_platform_manifest_gate.py:476 (corpus-walks a forms/*.docx, mints form_templates); (3) update test_workspace_resolver.py forms-route tests; (4) remove the vendored forms seam (fixtures/platform-corpus/forms/… + forms route-tag in .kh-workspace-map.json.example); (5) CONFIRM the §J manual-upload path (id-52 Path-A/B/C → form_template_requirements, 96 rows live) is the SOLE remaining forms ingest. SEQUENCING: land atomically with the {134.8} platform-corpus-shape guard.

Analysis: Captures code + tests + fixtures + confirmation + sequencing — the full retirement. Matches s435 §(f)/§(g) flag #8 (live code on main still has RouteKind "forms"; forms ARE corpus-walked until BL-392 lands).

Proposed fix: Promote BL-392 from spec_needed to a scheduled Task (or fold into the id-134 re-spec / id-131 landing) so the live-code contradiction is retired, not just tracked.

Cross-cutting note

Q3(a), Q6, and Q7 are the same fault line: the {134.6}/{134.7} + okf-v3 §8.2 forms-drop + id-131 content_items-elimination re-architecture is fully captured in journals + DR-014 + BL-392, but the committed spec artefacts (id-134 TECH.md) and the forward map (v1-completion-sequence.md) were never updated — they still describe the pre-OKF world. The single highest-leverage docs-consolidation action is re-authoring/annotating those two files against the journal truth.