assessment of forgotten functionality

docs/successor-gap-assessment.md

@@ -0,0 +1,141 @@
+# 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.