markitect-main/docs/successor-gap-assessment.md

markitect-main → Successor Repos: Gap Assessment

Date: 2026-05-23 Author: Claude (custodian session) Status: Draft — awaiting Bernd's decisions on items A/B/C below

Purpose

Bernd is retiring markitect-main and has transferred most functionality to sibling repos. This document identifies what was provided by markitect-main that is not addressed in those successors, and flags candidates that may not fit any successor's intent.

Successor Ecosystem (5 repos, not 3)

Repo	Role
markitect-tool	Markdown syntax layer + structured-document primitives; defines source-adapter and render-adapter contracts. CLI: mkt.
kontextual-engine	Headless knowledge operations engine: artifacts, collections, persistence, relationships, workflow runs/manifests, query, quality/assessment, API.
infospace-bench	Application layer — concrete infospaces, evaluation methodology, reference pilots.
markitect-filter	Source-format ingestion adapters (source.epub3, source.pdf) implementing the markitect-tool source-adapter contract.
markitect-quarkdown	Render/export adapter — implements the markitect-tool render-adapter contract via Quarkdown.

Method

Analysis is grounded in each successor's own assessment docs (recent, May 2026):

• markitect-tool/docs/markitect-main-scope-assessment.md
• kontextual-engine/docs/markitect-main-scope-assessment.md
• kontextual-engine/docs/system-layer-extraction-inventory.md
• kontextual-engine/docs/system-layer-migration-backlog.md
• infospace-bench/docs/markitect-main-scope-assessment.md
• infospace-bench/docs/legacy-infospace-feature-inventory.md
• infospace-bench/docs/replacement-acceptance-matrix.md

Cross-checked against actual markitect-main module sizing (Python LOC) and __init__.py docstrings.

Confidence: These successor docs are authoritative on intent. They have not been line-verified to confirm every "reimplement"-classified item actually landed in the successor. Where verification matters, it's flagged.

---

A. Doesn't fit any successor's intent — needs a new home or explicit retirement

These are explicitly pushed away by tool/engine/bench and are unrelated to filter/quarkdown.

markitect-main area	LOC	What it is	Status
markitect/finance/	~8,100	Cost-tracking system: cost items, period allocation to issues, financial reports, audit trails	Orphan. markitect-main's own SCOPE.md lists "financial transactions" as out-of-scope. Belongs with issue/project-ops, not knowledge tooling.
issue_tracker/ + _issue-tracking/ + .issues/	~1,200	Issue tracking (finance allocates costs to these issues)	Orphan to the five — but likely already superseded by the issue-facade capability / use-issues skill. Verify before retiring.
markitect/profile/	~1,600	User-profile CRUD, multi-profile, DB-backed	Orphan. Unrelated to all five. (Distinct from quarkdown's render "profile".)
markitect/production/	~3,800	Deployment-readiness validation, cross-platform checks, perf benchmarking	Engine keeps only "structured error/audit ideas". Deployment-validation bulk is orphan.
tools/, services/, gitea/tddai glue	~5,500	Project-ops tooling	Out-of-scope everywhere.
markitect/legacy/ + legacy_compat.py	~2,700	Backward-compat shims	Retire by definition.

B. Rendering / asset / plugin layer — only partially covered, real residual gap

This is the most consequential gap. SCOPE.md lists "Rendering: markdown → interactive HTML via plugin system (testdrive-jsui)" as an in-scope capability of markitect-main.

Area	LOC	Covered?
markitect/plugins/ (generic processor/formatter/validator/exporter plugin system)	~8,000	No. tool defines a render-adapter contract and an extension point, but the general plugin runtime isn't carried.
markitect/assets/ (content-addressable asset store, dedup, .mdpkg ZIP packaging, symlink handling) + asset_registry.json (277 KB)	~6,000	No. Bench says "leave behind unless a concrete export needs assets."
Interactive-HTML / testdrive-jsui rendering, static/, themes/, templates/document.html, JS UI	—	Partial only. quarkdown covers a Quarkdown export path; the interactive-HTML / JS-UI path has no home.

Decision needed: spin these into a dedicated render/asset repo (sibling to quarkdown), fold the asset store into one of the existing repos, or retire the interactive-HTML path.

C. The other "Information Space" lineage — markitect/spaces/ (~11,000 LOC)

Distinct from markitect/infospace/ (which infospace-bench inherited). spaces/ is an older/parallel abstraction with features bench did not take:

• event-driven change tracking & notifications
• persistent transclusion context with cross-space references
• bidirectional directory synchronization
• HTML rendering of spaces with caching/themes

Engine takes generic persistence concepts and bench takes infospace semantics, but these specific spaces/ behaviors (bidirectional sync, event notifications, cross-space transclusion context) aren't mapped anywhere.

Likely intended as dead/superseded — but 11k LOC warrants an explicit "retire vs salvage" call.

D. Declined-by-design (confirm retirement, don't re-extract)

Area	LOC	Disposition
markitect/graphql/	~4,000	All three explicitly declined GraphQL ("evidence of API need, not a commitment").
markitect/query_paradigms/	~3,500	Engine/tool keep the QueryResult envelope concept but say "do not port the registry wholesale."
markitect/proxy/	~870	Non-markdown→md proxy with checksum/freshness tracking. Overlaps markitect-filter. Freshness/staleness-tracking mechanism may be worth checking against bench's deferred "stale-mappings."
capabilities/ (top-level)	~8,300	Capability-packaging architecture; partially maps to tool (schema generation) but the packaging approach itself isn't carried.

---

What this means

The successors are, by their own assessments, near complete for the in-scope core (parsing/schema → tool; persistence/workflow → engine; infospace lifecycle → bench; ingestion → filter; one render path → quarkdown). The truly unaddressed functionality is almost entirely the stuff markitect-main accreted beyond its stated scope: finance, issue tracking, user profiles, production/deployment validation, the asset/plugin/interactive-HTML rendering stack, and the older spaces/ abstraction.

Decisions for Bernd

Three live decisions, not a long extraction backlog:

Decision 1 — Render/asset stack (Section B)

The one with genuine product value left.

• Option 1a: new repo (sibling to quarkdown) for plugin runtime + asset store + interactive-HTML
• Option 1b: fold the asset store into an existing repo (most likely markitect-tool, behind a flag); retire interactive-HTML
• Option 1c: retire the interactive-HTML path entirely; trust quarkdown export as the single render story

Decision 2 — markitect/spaces/ (Section C)

• Option 2a: salvage bidirectional-sync / event-tracking / cross-space transclusion into engine (engine has the persistence story to support it)
• Option 2b: retire wholesale as superseded by infospace

Decision 3 — Project-ops cluster (Section A: finance + issues + profile)

• Option 3a: confirm issue-facade already replaces issue_tracker/ + finance/; retire both
• Option 3b: identify a home for any pieces worth keeping

---

Suggested verification before deciding

If verification matters before committing:

• For Decision 1: grep the five repos for any render/asset adapter that already covers the HTML path beyond Quarkdown.
• For Decision 2: check whether engine's OperationRun + collection model can express bidirectional-sync semantics, or whether new primitives would be needed.
• For Decision 3: confirm whether issue-facade truly replaces issue_tracker/ + finance/ end-to-end.

Happy to do any of these focused passes when you're ready to decide.