Roadmap

Crosswalker is a meta-system for ontology lifecycle management, not just a framework importer. The roadmap reflects this — architecture decisions come first, features are built on that foundation, and every significant decision is logged with rationale.

See vision alignment decisions for the philosophical foundations.

How this roadmap is maintained

This page is the living roadmap — only active and future phases live here. When a phase completes:

1. Move its checklist to a new archive page: reference/roadmap/vX-Y-name.mdx
2. Add a “What carried forward” section noting items that moved to later phases
3. Link the archive from the Archive section below
4. Update ROADMAP.md at the repo root to stay in sync

Every significant decision gets a dated entry in the decision log. Link roadmap items to their log entries so the why is always reachable from the what.

---

Current phase: v0.1 implementation (design phase closed 2026-05-04)

✅ Design phase complete — 2026-05-04

All named architectural questions resolved through five fresh-agent research challenges (Ch 20–24). Concrete implementation work begins now. The plain-markdown mirror of this roadmap lives at ROADMAP.md at the repo root.

Architectural commitments locked:

• Schema-as-primitive reframe — Tier 1 schema is the load-bearing contract; engine + ETL are convenience (ETL pillar)
• Closed 5-mechanism recipe grammar — folder | file | heading | tag | wikilink × layout × also_emit × graph_edges; render(Recipe, ConceptIdentity) → Address as single coupling point (Ch 22 synthesis)
• TypeScript in-plugin engine for v0.1; Path C (optional Python producer) reserved for v0.5+ (Ch 23 synthesis)
• Tier 2 substrate stays on @sqlite.org/sqlite-wasm + sqlite-vec; libSQL/Turso Cloud/Limbo all rejected (Ch 24 synthesis)
• Runtime-agnostic recipe schema as load-bearing modularity commitment
• Output query layer: Bases (Dataview removed)

Machine-readable contracts shipped: spec/tier1.schema.json + spec/recipe.schema.json. Dev infrastructure: tools/generate-fixtures.ts + bun run fixtures. See the 2026-05-04 import engine design log for the full state.

Long-horizon watch register for substrates and adjacent file-based tools considered and not adopted today: see embedded-vs-server-substrates § watch register.

v0.1 implementation milestones (active work)

The v0.1 implementation phase breaks into 9 sequenced milestones. Each has its own page with concrete tasks, dependencies, and success criteria.

Milestone	Title	Effort	Status
v0.1.1	Type system + validation foundation	1–2 days	📋 Planning
v0.1.2	render() v1 — folder + file + heading	3–5 days	📋 Planning
v0.1.3	Generation engine integration	3–5 days	📋 Planning
v0.1.4	Junction notes + crosswalk edges	2–3 days	📋 Planning
v0.1.5	Tier 2 sqlite-wasm sidecar projector	5–8 days	📋 Planning
v0.1.6	Bases query layer	3–5 days	📋 Planning
v0.1.7	Exporters (STRM TSV / OSCAL JSON)	2–3 days	📋 Planning
v0.1.8	Audit trail T1 default	1–2 days	📋 Planning
v0.1-RC	Bundle, polish, ship	2–3 days	📋 Planning

Total estimate: ~3–6 weeks of focused work. See the milestone hub for the full sequencing detail and dependency graph.

Foundation — “Get the architecture right” (closed)

Architecture decisions before more code. The three interconnected schemas (_crosswalker metadata, FrameworkConfig, StewardshipProfile née EvolutionPattern) must be designed together — getting any wrong is expensive to fix later. Decision: architecture first

After three research waves on 2026-05-02 and the v0.1 stack-pivot, Foundation is now organised around a concrete v0.1 build target plus the genuinely-still-open spec items.

Architectural safety guarantee — load-bearing principle

Tier 1 (canonical files) is the source of truth. Tier 2 and Tier 3 are projections — fully deletable, fully recoverable from Tier 1. Delete the .sqlite, the plugin reprojects on next vault load. Delete the server, restart from git history. Tier 1 alone is functional (slow on large vaults, but functional). Performance enhancements and integration features layer on top of canonical files; the canonical files are what survives.

This property is what enables the Progressive Tier Architecture to be safely additive: shipping Tier 2 in v0.1 doesn’t trap the user. See v0.1 stack-pivot log §2.

v0.1 build target — what ships first

Concrete, shippable. ~1.2 MB total. Tier 1 + Tier 2 sqlite-wasm sidecar bundled together.

Build against the unified v0.1 schema spec — the four interconnected schemas (_crosswalker metadata, FrameworkConfig v2, junction note 13-field schema, Tier 2 sidecar SQL) in one place.

v0.1 stack (full commitment):

• Tier 1 storage: markdown files with YAML frontmatter; STRM predicate vocabulary (is_equivalent_to, is_broader_than, is_approximate_to, intersects_with, no_relationship); junction notes (13-field schema, Ch 07 resolution) for evidence links
• Tier 1 in-memory index: plain JS Map built at vault-load time over frontmatter; works without Tier 2 (slow on large vaults but functional)
• Tier 2 sqlite-wasm sidecar projector: @sqlite.org/sqlite-wasm (~600 KB) + sqlite-vec; auto-projects from Tier 1 on vault load; deletable; reprojected on next load. Per Ch 18 expressivity matrix, 4 ✅ tractable rule types + 4 ⚠️ caveat-tractable cover the realistic GRC workload comfortably under 100K mappings
• Crosswalk-render plugin: Dataview-style queries on frontmatter for the Tier 1 path; recursive CTE over Tier 2 sidecar for transitive closure / multi-framework joins / coverage matrices / perspective views
• STRM-shaped TSV exporter (NIST IR 8278A r1 OLIR template shape, Excel-friendly CSV) + OSCAL JSON profile exporter + SSSOM-flavored TSV emission (optional, for academic interop). Hybrid SSSOM↔STRM resolution per v0.1 pivot §6
• Audit trail (T1 default): git commits + Ed25519-signed releases for shared mapping bundles; auto-generated FRE 902(13) certification PDF available on demand. Per v0.1 pivot §8
• Bundle target: under 500 KB plugin core + ~600 KB sqlite-wasm sidecar = ~1.2 MB compressed total

Plugin scope: a single, focused import wizard + crosswalk-render plugin + Tier 2 sidecar projector. Performance enhancements (DuckDB-WASM, Oxigraph, Nemo, Comunica federation) live in separate companion plugins released later.

✅ Resolved Foundation decisions

These are committed direction, with deliverables and decision logs. They feed v0.1 and beyond.

• ✅ Crosswalk edge semantics — STRM + SSSOM — STRM (NIST IR 8477) as required predicate_id vocabulary; SSSOM as row-schema envelope. Hybrid resolution: STRM-shaped TSV is the user-facing wire format, SSSOM is the internal validation envelope. Both emittable. v0.1 pivot §6 · 04-10 synthesis
• ✅ Junction notes for evidence links — one markdown file per edge, 13-field flat-YAML schema, isomorphic to OSCAL by-component. Three orthogonal status dimensions (status × freshness × evidence_type). Ch 07 archive
• ✅ Pairwise crosswalks + optional inheritable pivot — pairwise-first; SCF available as inheritable spine for users who want hub-and-spoke. Ch 06 archive
• ✅ Progressive Tier Architecture (confirmed) — Tier 1 (files canonical) → Tier 2 (sqlite-wasm sidecar) → Tier 3 (optional server). Files always source of truth. Each tier shares the same schemas. v0.1 ships Tier 1 + Tier 2 bundled. Ceiling rationale
• ✅ Distribution architecture (research done) — pnpm monorepo: @crosswalker/core + plugin + CLI; VaultAdapter interface bridges platforms. Implementation: monorepo restructure remains an open task below.
• ✅ StewardshipProfile rename + meta-schema lifecycle commitment — EvolutionPattern renamed to StewardshipProfile; “Crosswalker eats own dog food” — every internal schema is versioned and migration-aware. Rename ripples deferred (~24 file edits).
• ✅ Audit trail floor — Tier 1 = git + signed commits — git commits + Ed25519-signed releases + on-demand FRE 902(13) PDF. T2 OpenTimestamps and T3 audit profiles surface as opt-in compliance-export mode in v1.0+. Ch 08 deliverable · Ch 13 deliverable · Ch 15 deliverable · Ch 19 deliverable
• ✅ Identifier strategy — UUIDv7 + sha256 CIDs + CURIEs (ORCID for SSSOM authors); CWUUID is display-only. Ch 09 deliverable

Genuinely-still-open Foundation items

These are design / spec items that need work before/during v0.1 implementation. Most are documentation or schema specifics, not architectural questions.

Schema spec work:

• Unified v0.1 schema spec (2026-05-03) — the four interconnected schemas designed together as the v0.1 build target. Implementation of the four schemas below proceeds against this spec.
• ImportRecipe v1 schema (formerly FrameworkConfig v2 — see naming history) — implement the recipe shape in src/types/config.ts; migration script for legacy saved configs
• _crosswalker metadata v2 — extend src/generation/generation-engine.ts to write the v2 fields (ontology_id, ontology_version, recipe_id); idempotent migration for existing notes
• Junction note 13-field schema — implement junction-note generation as new code path in the generation engine; non-destructive, git-history-preserving
• Tier 2 sidecar SQL schema — new packages/core/ projector module; auto-runs on vault load; lazy closure cache
• Migration strategy matrix — given StewardshipProfile + old/new version → recommended SCD type + handling strategy

Implementation infrastructure:

• Monorepo restructure — extract ~50-60% of current codebase into packages/core/, keep plugin UI in packages/plugin/, create packages/cli/. Sequence rationale
• Obsidian Bases direction research — Dataview is deprecated. Understand Bases API for the viewing/querying layer on native Obsidian capabilities. Datacore as backup option. Context in 04-10 synthesis
• Transform engine — custom build (14 engines evaluated, none fit). 24 transform types, ChunkyCSV-style operations, optional Arquero/JSONata escape hatches. Research
• Ontology diff primitives implementation — implement the 9 atomic operations + 4 recognized composites as the structural diff engine. Spec is settled; implementation remains.

Documentation tasks (surfaced 2026-05-02; non-blocking but valuable):

• OSCAL ↔ Crosswalker mental model — extend reference/registry/oscal to map OSCAL terms (catalog ↔ source-ontology web, Control Mapping Model ↔ crosswalk edges, Assessment Result ↔ junction notes) into Crosswalker’s vocabulary. Per TL;DR §3.3
• DB-choice architecture page — extend architecture/file-based-graph-database explaining why Tier 1 + sqlite-wasm sidecar is the right choice (and why not pure graph DB). Per third-wave §3.3
• Comunica honest+practical assessment — per third-wave §7.2, Comunica federation conditional confirmation pending honest assessment before v1.0 companion plugin work
• StewardshipProfile rename ripples — propagate the rename across ~24 docs files where the old “EvolutionPattern” term still appears

Research items remaining (not v0.1-blocking):

• SEACOW + folder-tag-sync prior-art integration — decide what Crosswalker reuses from the project owner’s prior tools
• Graph scope decision — directed graphs now (covers 95% of use cases). DAG and hypergraph support deferred. Pluggable layers: Thread 2
• StewardshipProfile vs transformation recipes — investigate whether per-version-transition transformation records replace or complement framework-level classification. Both may coexist.

Infrastructure (non-blocking):

• PII scanning in CI/CD — automated detection of personal paths, secrets, API keys before push
• Expand E2E smoke tests minimally (don’t test wizard UI — it will change)
• Fluid layout scaling — replace rigid Nova breakpoints (768/1152px) with clamp() CSS. ~3-5 hours.

---

Formats — “Import anything, transform it properly”

Built on the Foundation spec. The wizard UI is redesigned around FrameworkConfig v2.

• Complete import wizard UI — steps 2-4 redesigned around the new config schema
• Complete settings tab — all 8 sections reflecting new schema
• Complete config browser modal — search, select, delete, import/export
• XLSX parser — integrate xlsx package into wizard with sheet selector
• JSON/JSONL parser — structured data import
• Transform system — implement 20+ transform types defined in schema (string, array, type conversion, conditional). Current types
• Improved preview — expandable folder tree, full note preview in Step 3
• E2E test suite — full import wizard workflow tests, built from spec

---

Crosswalks — “Link frameworks to each other and to evidence”

The evidence mapping workflow — the core value proposition for GRC teams.

• Cross-framework linking engine — generate typed WikiLinks between imported frameworks using crosswalk data. Crosswalk specs
• Link insertion commands — “Insert framework link” with search modal and metadata form. Link metadata system
• Batch re-import — update existing framework folders with version awareness and diff preview. Resilience patterns
• FrameworkConfig presets — per-framework configs with sheet selection, custom transforms, column overrides. Community-contributed via the as-code format.
• CLI implementation — headless import, crosswalk generation, batch operations

---

Performance — “v1.0+ companion plugins”

Performance enhancements and integration capabilities researched on 2026-05-02 (third research wave) and reframed by the v0.1 stack-pivot as opt-in companion plugins that ship after v0.1 lands. Each is fully researched; the deliverables are ready-made designs.

These are not v0.1 build target. They are v1.0+ work for users who outgrow the Tier 2 sqlite-wasm sidecar default.

• “Crosswalker Power Query” companion plugin — DuckDB-WASM + Oxigraph-WASM + Nemo-WASM layered Tier 2 stack (~5 MB compressed). Triggered when a user vault exceeds Tier 2-Lite’s ~100K mapping ceiling (per Ch 18 migration triggers) OR demands recursive SHACL / multi-stratum Datalog / SPARQL property paths. Ch 11 deliverables A/B/C · Ch 14 deliverable
• Comunica federation companion plugin — Comunica + N3 + HDT for cross-vault, cross-org, external SPARQL endpoint queries. ~250–300 KB gzipped core. Conditional — see third-wave §7.2: user flagged Comunica as “seems bulky or overengineered”; honest-and-practical assessment needed before locking in
• Compliance-export mode — opt-in profile picker exposing T2 OpenTimestamps and T3 audit options (“US litigation”, “EU regulated”, “Federal ATO”, “Supply-chain”) per the Ch 15 deliverable §E. Each profile pre-configures 4–6 settings. v0.1 default remains T1 (git + signed commits).
• Migration trigger UX — status-bar indicator and modal prompts for “you’ve outgrown Tier 2-Lite” per Ch 18 §3.2. Detects performance / scale / feature triggers; suppressed on platforms that can’t migrate (Obsidian Mobile)
• PQC dual-sign migration — Ed25519 → ML-DSA-44 dual-sign starting 2027 per Ch 15 §5.6 crypto-agility plan. Ahead of NIST IR 8547 2035 deadline.

---

Deployment — “v2.0+ Tier 3 server guide”

Server-tier deployment options for users who genuinely need a shared multi-team server. Documented as a deployment guide rather than bundled into the plugin.

• Default recommendation: Postgres + JSONB + recursive CTE — boring tech, broadly operable, “you probably don’t need anything fancier.” Per Ch 16 deliverable §2.3
• Apache Jena Fuseki + oxigraph-server — same-API alternative for users who want SPARQL natively (oxigraph-server uses the same engine as the v0.1 Tier 2, just with serve mode). Architectural symmetry with Tier 2.
• Layered Fuseki + DuckDB-on-server — power-user upgrade path for multi-team mixed SQL+graph workloads, multi-million mappings. Federated via SPARQL SERVICE and DuckDB httpfs / postgres_scanner
• TerminusDB v12 — opt-in vault-mirror for users who want server-side git-style branch/diff. Small-vendor (DFRNT) risk explicitly flagged
• Apache AGE on Postgres — supported fallback for Postgres-standardized environments. AGE’s killer feature (graph queries inside an existing Postgres instance) has no substitute
• Migration from AGE — for early adopters who started on AGE during the Ch 10 era. The SSSOM-canonical files-first architecture turns “migrate from AGE” into “re-run the projector against the new engine,” not “translate AGE data” — see Ch 16 §5

---

Evolution — “The meta-system”

Implement the ontology evolution classification system designed in Foundation. This is the novel contribution — no existing tool solves this.

• Entity-aligned migration UX — design the experience for entities (agents or people) going through and fixing things. Guided form → migration plan YAML → CLI. Progressive depth. User-first maintenance
• Version registry standard — define the interface for declaring “framework version X exists.” Community builds implementations (GitHub repo, API, scrapers). Detection is pluggable, not primitive.
• Per-framework decisioning format — the taxonomy-over-taxonomies config. Per-ontology handling strategy overrides layered on default primitives.
• Progressive classification UX — community pre-classified → guided wizard → auto-detect
• Evolution profile registry — YAML/JSON per framework, community-contributed
• Migration strategy engine — old version + new version + user evidence → suggested handling + diff preview. Built on the structural diff engine.
• Stale crosswalk detection — surface when imported frameworks have newer versions available
• Community marketplace research — Obsidian ecosystem constraints, distribution model options

---

Community — “Share and scale”

Build the ecosystem around the spec.

• Community config registry — start with GitHub repo, evaluate built-in registry later
• OSCAL export — export to Open Security Controls Assessment Language for GRC tool integration
• Compliance dashboards — Bases views for gap analysis, coverage tracking
• Report generation — exportable compliance reports for auditors
• Custom migration transforms — user-defined transformation logic for version migrations. From inline expressions to named transforms to custom scripts. Progressive depth applied to migration.
• AI-assisted transforms — LLM-based property mapping using templates (like Obsidian web clipper AI templates but for ontology node properties). Map source schema to target schema via AI suggestion.
• Extended graph support — research and implement DAG and hypergraph support beyond basic directed graphs
• Community plugin submission — publish to Obsidian plugin registry
• Spec publication — publish EvolutionPattern taxonomy and structural diff engine as standalone specifications

---

Decision log

Every significant architectural decision is captured with rationale in the log:

Recent (2026-05-02 / 2026-05-03) — three research waves + v0.1 stack pivot:

• v0.1 initial-stack pivot — Tier 1 + Tier 2 sqlite-wasm sidecar bundled as v0.1; layered third-wave engines reframed as v1.0+ companion plugins. Read this for the v0.1 build target.
• Direction third-wave architectural shifts — Ch 14/15/16 deltas (Tier 2 confirmed-and-extended, Tier 3 default flipped to Fuseki/oxigraph-server, audit-trail 4-tier model). Reframed as back-pocket research by the v0.1 pivot.
• Direction commitments TL;DR — concise concluding artifact for the second research wave (Ch 11/12/13)
• Direction research wave + roadmap reshape — full research record for the second wave
• 05-01 Foundation commitments + follow-on research — pairwise + optional pivot, junction-notes-by-tier, StewardshipProfile rename, meta-schema lifecycle commitment
• Evidence-link edge model synthesis — junction notes commitment (Ch 07 resolution)
• 04-10 Foundation research synthesis — STRM + SSSOM crosswalk edge semantics, files-canonical ceiling, synthetic spine question

Earlier (2026-04) — first-principles foundations:

• Vision alignment decisions — 10 foundational decisions
• Deep research synthesis — ontology meta-tools, plugin state, E2E testing
• Architectural direction — the “what are we building?” question
• First principles: ontology change — 13 structural primitives, Path A/B/C
• Atomic operations research — literature survey, provably complete operation set
• User-first ontology maintenance — entity-aligned experience design
• Primitives depth + pluggable layers — detection, decisioning, custom transforms

See also: ROADMAP.md on GitHub, research deliverables, research challenges

---

Archive

Past roadmap versions are preserved here for reference:

• v0.1 MVP roadmap — the original MVP scope (complete)