UI parity audit — every lifecycle stage gets a face, config is the escape hatch

What this is — the anti-tunnel-vision guard

The 2026-06 ingestion sprint built a lot of headless capability fast (JSON iterator reader, melt extractor, --depad, --where…). This audit checks that speed against the product vision: per the ontology lifecycle, a user must be able to peer into and drive every stage through UI. Config files, recipes, and CLI flags are the escape hatch and the programmatic path — never the only door. Sanctioned exception: prose sources (PDF/HTML) below the input floor, which are explicitly external-ETL territory.

The principle

1. UI first, config as escape hatch. Every capability a user needs in the lifecycle gets a UI surface. The JSON recipe / CLI invocation behind it stays available for automation, agents, and power users — that duality is the point of schema-as-primitive, not a license to skip the UI.
2. Parity is tracked, not assumed. New headless capability must name its UI surface (existing or roadmapped) in the same change. The pre-commit habit: “does this flag have a face?”
3. The architecture makes this cheap. Recipes and queries are AJV-validated JSON data; render() is pure; the wizard and the headless tools share the same validator. A UI is a thin editor over objects that already exist — no rework debt accrues by building headless first, as long as the gap is named.

Parity matrix (as of 2026-06-12)

Lifecycle stage	Programmatic / escape hatch	UI today	Gap status
Acquire	user obtains source files	wizard file picker	✅ by design (prose/PDF stays external ETL)
Import — Parse	harness: CSV · XLSX (--sheet/--header-row) · JSON (--iterator/--where)	wizard parses CSV · XLSX (sheet picker + header-row offset) · JSON (iterator + row-filter inputs) — ✅ closed same day (the stubs dated to the MVP)	✅
Import — Transform	recipes (--map, --where, template filters)	wizard column-config (CSV); config save/load/match/browse modals	🟡 partial — no recipe editor UI; recipes are JSON-file-only
Import — Generate	render() + engine, deterministic harness	wizard step 3 preview + step 4 generate	✅
Crosswalks / edges	crosswalk-from-olir.ts, crosswalk-from-melt.ts	SSSOM TSV import modal ✅ — but workbook-extraction (OLIR / melt) has no UI	🟡 named gap — “Import crosswalk from workbook” wizard path
Enrich	user_preserve frontmatter contract	native Obsidian editing	✅ by design
Query / analyze	query frontmatter schema (escape hatch by design)	create / embed / browse commands + crosswalkerPivot + native Bases (v0.1.6 Phases 4.5–6.3)	✅ — the strongest stage
Maintain	re-import merge semantics; diff primitive (Phase 6)	re-run wizard; no diff/what-changed UI yet	🟡 planned — v0.1.8 audit trail is exactly this
Share	recipes as JSON; SSSOM TSV artifacts	config browser ✅; config export/import UI still TODO; exporters = v0.1.7	🟡 planned

Named gaps → tracking homes

1. Wizard XLSX + JSON wiring ✅ closed 2026-06-12 (same day) — src/import/parsers/{xlsx-parser,json-parser}.ts + Step-1 sheet picker / iterator + filter inputs; the JSON core moved INTO src (json-source-core.ts) and the harness now imports it from there — one reader, two doors.
2. Crosswalk-extraction UI (edges 🟡) — OLIR + melt are CLI-only; a “Import crosswalk from workbook” flow can reuse the SSSOM modal’s preview pattern.
3. Recipe editor and library (Transform 🟡) — active-import editing now preserves canonical recipes through RecipeDocument; the remaining gap is durable save/open/browse/export under _crosswalker/recipes/import/, after the public UI term is settled. 3a. Derive hierarchy from an id ✅ closed 2026-06-13 — the wizard’s new “Folder tree (from id)” column role parses a taxonomy id (DE.AE-02 → DE/ → DE.AE/ → DE.AE-02.md) by auto-detecting its delimiters; the “In the vault” preview shows the tree, and smart-defaults auto-pick it for structured-id columns. Same result the nist-csf-2-cprt-hierarchical.json recipe produces, now point-and-click.
4. Diff / maintain UI (🟡) — lands with v0.1.8 audit trail; the diff primitive (Phase 6) is already built for it.
5. Config/recipe share UI (🟡) — SavedConfig is not a substitute for a portable ImportRecipe lifecycle; recipe save/open/export/import buttons remain v0.1.7-adjacent.

2026-07-11 addendum: workbench, fast path, and workspace view

The shape-workbench side-arc (2026-07-05 → 2026-07-11, tracked as v0.1.6 Phase 7) moved several rows below. Kept terse per this page’s original format — only the rows that changed, plus the honest new gaps the arc surfaced.

Lifecycle stage	What changed	Gap status
Import — Transform	The shape workbench (beta, opt-in setting) is a real UI over an editable mapping projection. Correction: the July 11 claim that every mapping already round-tripped to a recipe file overstated the durable boundary. As of the 2026-07-21 fidelity slice, recognized/fresh canonical recipes now survive the active workbench losslessly for supported fields through RecipeDocument; portable-save blockers are explicit.	🟢 for active-import editing fidelity; 🟡 for durable lifecycle — no standalone save/open/browser/export UI under _crosswalker/recipes/import/ yet
Acquire	The recognized-source fast path gives the six bundled vetted recipes (NIST CSF 2.0, MITRE ATT&CK, CIS Controls, NIST 800-53, CRI Profile, SCF) a calmer on-ramp — a “Recognized: [source]” trust card instead of the full detection flow. Still file-picker based; the gap this closes is confidence, not capability.	✅ by design, now friendlier
Enrich	Pass 1.5 batch enrichment (managed children lists, facet hub notes, edge-count stat) runs whenever the effective recipe declares target.enrichment — true for the shape workbench and native recipe / headless harness paths, but not the classic Step-2 column-table wizard path (workbench off), whose legacyConfigToRecipe translation never sets an enrichment block. So it is closer to “two of three import paths,” not “every path” — verified against src/generation/generation-engine.ts and src/generation/legacy-recipe-shim.ts, 2026-07-11, correcting CHANGELOG.md’s “applies uniformly to every import path” framing. Where it does run, it is fully automatic and headless — no on/off toggle or configuration surface in either wizard path.	🟡 two named gaps: (1) “Enrichment knobs are recipe-only” — no UI to turn a facet hub off, rename it, or pick which relations get the children-list treatment; (2) “Classic wizard path has no enrichment wiring” — turning the workbench off silently drops connectedness entirely, with no UI signal that this happened
(new) Home / navigation	The new Crosswalker workspace tab (ribbon icon + command) hosts the entire import flow — file select through recognized card, workbench, review screen, and generate — rendered wide, in-tab, via a host-agnostic ImportFlow/ImportFlowHost split. The settings-launched modal is now a thin back-compat host of the same flow, not a separate implementation. The tab’s Installed ontologies list shows live note/link counts per imported folder plus a one-click “Import again” (re-runs the matched recipe, skipping fingerprint detection).	✅ closed same arc — the deferral named in the design doc (.workspace/2026-07-05-shape-first-wizard-spec.md §7n) landed before ship

Still true, unchanged by this arc: crosswalk-extraction UI (gap #2), diff/maintain UI (gap #4), config/recipe share UI (gap #5) — none of those stages were touched by the wizard rebuild.

Related

• Ontology lifecycle — the stage model this audit walks
• ETL and import — schema-as-primitive (why UI stays cheap) + the input floor (the prose exception)
• Operational landscape — the five tiers of work; UI surfaces are Tier 1–2
• Ingestion tooling dev log — the headless sprint this audit balances
• URM ingestion readiness — the corpus scoreboard
• v0.1.6 milestone — the query-stage UI that sets the parity bar; Phase 7 is the 2026-07-11 addendum’s source
• Shape-workbench architecture synthesis (2026-07-11) — the full record behind the addendum above
• Settings reference — the Live mapping workbench toggle the addendum discusses