Skip to content

ROADMAP.adoc

Latest commit

 

History

History
306 lines (203 loc) · 7.76 KB

ROADMAP.adoc

File metadata and controls

306 lines (203 loc) · 7.76 KB
Raw

Reposystem Roadmap

f/i staged development plan for Reposystem — the railway yard for your repository ecosystem.

Table of Contents

Vision

A visual wiring layer that sits above individual repos, allowing you to:

  1. Import repositories (yours + upstreams)

  2. Identify components/slots/providers

  3. Rewire projects by switching providers (local ↔ ecosystem ↔ fallback)

  4. Tag with aspects (security, reliability, etc.) and flip views

  5. Reason about the dependency graph including contingency paths

Current Status (2026-01-26)

Reposystem is in implementation phase with the core pipeline complete:

  • Local scan + graph store + JSON/DOT export

  • Slots/providers/compatibility registry

  • Plans, diffs, rollback + apply/audit flow

  • TUI explorer

  • Web UI prototype (static graph explorer, ER mode, annotations)

Technology Stack

Layer Language Notes

Core data model

Rust

Graph store + persistence

CLI + TUI

Rust

Cross-platform with Ratatui for TUI

State files

Guile Scheme

STATE.scm, META.scm, ECOSYSTEM.scm

Web UI (prototype)

HTML/CSS/JavaScript

No-build static UI under web/

Graph export

DOT/SVG + JSON

Standard formats

f/i Staged Plan

f1 — Freeze: MVC Graph + Tagging + Export

MUST (Freeze Criteria)

  • ✓ Repo importer — Import from local folder of git clones

  • ✓ Persistent graph store — Nodes, edges, groups in JSON

  • ✓ Manual edges — Create relationships between repos

  • ✓ Manual groups — Cluster repos into logical units

  • ✓ Manual aspect tags — Tag nodes/edges with aspects

  • ✓ View filters — Filter by group, by aspect

  • ✓ Export DOT — Graphviz-compatible output

  • ✓ Export JSON — Machine-readable graph export

  • ✓ Re-import fidelity — Re-import exported JSON → identical graph

SHOULD

  • ✓ Lightweight auto-suggestions (non-authoritative)

  • ✓ Basic edge auto-detection from config/imports

COULD

  • ✓ Basic "weak link" lens

  • ✓ Simple TUI for interactive exploration

Freeze Criteria

You can import 50+ repos, group them, tag them, export the graph, re-open it later unchanged.

i1 — Seam Review: Graph ↔ Evidence ↔ Export

  • ✓ Graph determinism check

  • ✓ Tag provenance check

  • ✓ Export fidelity check

f2 — Freeze: Slots/Providers Registry

MUST

  • ✓ Slot definitions — Declare what can be swapped

  • ✓ Provider definitions — Declare what provides a slot

  • ✓ Repo-to-provider links — Provider X is implemented by repo Y

  • ✓ Slot/provider overlay in graph — Visual indication

SHOULD

  • ✓ Compatibility metadata (version, interface kind)

  • ✓ Adapter stubs (declared, not executed)

COULD

  • ✓ Scenario snapshots (local vs ecosystem) in graph only

  • ✓ "What if" visualisation without actual changes

i2 — Seam Review: Slot Model ↔ Aspect Model

  • ✓ Provider substitution invariants

  • ✓ Aspect attachment invariants

  • ✓ No hidden edges

f3 — Freeze: Plan Generation + Dry-Run Diff

MUST

  • ✓ Create plan from scenario — Choose switches, generate plan

  • ✓ Dry-run diff — Show intended file changes as patches

  • ✓ Rollback plan — Define reversal (even if not executed yet)

SHOULD

  • ✓ Validate plan against compatibility + smoke-test hooks (declared)

  • ✓ Risk assessment per edge change

COULD

  • ✓ Auto-fallback logic (policy-level)

  • ✓ Plan comparison between scenarios

i3 — Seam Review: Plan ↔ Apply ↔ Rollback

  • ✓ Plan replayability

  • ✓ Diff accuracy

  • ✓ Rollback completeness

f4 — Freeze: Apply + Rollback Execution

MUST

  • ✓ Apply plan — Execute changes to repos

  • ✓ Rollback — Revert to previous state

  • ✓ Audit log — Record all applied changes

SHOULD

  • ✓ Health checks post-apply

  • ✓ Auto-rollback on failure

COULD

  • ✓ Staged apply (one repo at a time with confirmation)

  • ✓ Backup before apply

f5 — Freeze: Interactive UI (TUI + Web)

MUST

  • ✓ Switch toggles (local/ecosystem/auto)

  • ✓ Preview diffs before apply

  • ✓ Show risk flags per change

  • ✓ Keyboard navigation

  • ✓ Mouse support

SHOULD

  • ✓ Aspect flip views

  • ✓ Scenario comparison side-by-side

COULD

  • ✓ Web UI with annotations + ER mode

f6 — Freeze: GUI Railway Yard (Polish)

COULD

  • ❏ Drag-and-drop canvas

  • ❏ Point-switches with visual feedback

  • ❏ Animated routing preview

Docs & OPSM Next Steps

  1. Refresh documentation across the stack — Update README, ROADMAP, and the six machine-readable SCM files (STATE.scm, ECOSYSTEM.scm, META.scm, PLAYBOOK.scm, AGENTIC.scm, NEUROSYM.scm) so the current status, blockers, and next actions are explicit for both humans and agents.

  2. Populate GitHub wiki — Publish developer, platform maintainer, scientist, and layperson sections for Reposystem + Git Dispatcher so contributors can quickly understand the architecture, the OPSM relationship, and the documentation expectations (ASCII diagrams, licensing notes, accessibility goals).

  3. Align with OPSM / opsm-ui — Ensure opsm.toml, Mustfile, and integration-notes cross-reference the OPSM strategy and share the same indigo + high-contrast branding; add explicit references to opsm-ui, git-hud, git-dispatcher, and the odds-and-sods package manager in doc artifacts.

  4. Accessibility + branding — Document the requirements (2.3 AA contrast, keyboard + screen-reader support, crow’s-foot ER mode, zoom/snap controls) inside the roadmap and README so downstream UIs know what to maintain.

  5. Dependency hygiene campaign — Track and reduce open Dependabot backlog in highest-load repos first (for example academic-workflow-suite, pow-the-game, affinescript, candy-crash), then fold recurring updates into grouped automation policies.

    • ❏ Contingency paths visualisation

    • ❏ Multi-user collaboration

"Hello Yard" Milestone

Scope

Pick one slot and support it end-to-end:

  • Slot: container.runtime

  • Providers: podman (local), cerro-torre (ecosystem)

  • Consumer repos: 2–3 repos that do container work

Deliverables

  1. spec/DATA-MODEL.adoc — Done ✓

  2. spec/CONCEPTS.adoc — Done ✓

  3. registry.adoc — Done ✓

  4. CLI commands — Done ✓

MVP Definition

What’s In

  • Import repos from local folder

  • Create graph (nodes = repos, edges = relationships)

  • Group repos manually

  • Tag nodes/edges with aspects manually

  • "Flip view" to show chosen aspect

  • Export to DOT + JSON

What’s Out (for Now)

  • Forge API integration (GitHub/GitLab)

  • Auto-application of changes without explicit plan

Existing Tool Mapping

Where existing tools can help:

Component Existing Tool Notes

Graph visualization

Graphviz, D2, Mermaid

DOT export target

TUI framework

Ratatui (Rust)

Terminal UI

Diagramming reference

Structurizr, PlantUML

Concept inspiration

Gap Analysis

What doesn’t exist yet (the value proposition):

Gap What Reposystem Provides

Multi-repo component graph

Graph of repos + components + programmable switches

Aspect tagging

Orthogonal view layers on dependency graph

Component substitution with rollback

Built-in provider swap with reversibility

Scenario comparison

A/B testing with aspect impact analysis

Success Criteria

f1 Complete When

  • Import 50+ repos, group and tag them, export and re-open without loss.

f6 Complete When

  • Non-technical users can explore and annotate the ecosystem safely.

OPSM Integration

OPSM Core
  |
  v
reposystem (graph/context source for OPSM ecosystem views)