Vyasa Extension Refactor Audit and Execution Plan

Current Biggest RisksURL copied

core.py global state makes route extensions hard to register cleanly. Fix with an app factory and frozen runtime.

Markdown currently acts as a feature hub. Fix by moving each fence renderer out and deleting fallback branches.

Shared scripts.js couples unrelated features through global events. Fix by adding a tiny event bus and extension-owned JS.

Search/tree/bookmarks are tangled. Fix with a row decorator contract.

Slides touches Markdown headings, document actions, layout mode, and routes. Fix only after the document action and heading action contracts exist.

Static build duplicates live behavior. Fix after live extension asset collection works.

2	✦
3	✦ > Documents Read
4	✦ > Contract Baseline
5	✦ > Current Work That Was Done
6	✦ > High-Level Diagnosis
7	✦ > Architecture Decision Framework
8	✦ > Architecture Decision Framework > Deletion Test
9	✦ > Architecture Decision Framework > Real Seams And Hypothetical Seams
10	✦ > Architecture Decision Framework > Dependency Categories For This Refactor
11	✦ > Architecture Decision Framework > Interface Is The Test Surface
12	✦ > Architecture Decision Framework > Design Decisions From The Architecture Skill
13	✦ > Architecture Decision Framework > Deepening Opportunities > 1. Extension Registration Module
14	✦ > Architecture Decision Framework > Deepening Opportunities > 2. Markdown Pipeline Module
15	✦ > Architecture Decision Framework > Deepening Opportunities > 3. Theme Selector Module
16	✦ > Architecture Decision Framework > Deepening Opportunities > 4. Layout Module
17	✦ > Architecture Decision Framework > Deepening Opportunities > 5. Search Module
18	✦ > Architecture Decision Framework > Deepening Opportunities > 6. Bookmark And Annotation Modules
19	✦ > Architecture Decision Framework > Deepening Opportunities > 7. Static Asset Module
20	✦ > Architecture Decision Framework > Deepening Opportunities > 8. Static Build Module
21	✦ > Architecture Decision Framework > Deepening Opportunities > 9. Admin UI Module
22	✦ > Architecture Decision Framework > Deepening Opportunities > 10. Agent Module
23	✦ > Non-Negotiable Rules For The Next Refactor
24	✦ > Current Contract Violations > `VyasaExtension` Does Not Exist
25	✦ > Current Contract Violations > `VyasaExtensionApp` Does Not Exist
26	✦ > Current Contract Violations > Extension Metadata Is Too Weak
27	✦ > Current Contract Violations > Core Still Assigns Default Providers After Runtime Build
28	✦ > Current Contract Violations > Mermaid Extension Does Not Own Mermaid Rendering
29	✦ > Current Contract Violations > D2 Extension Does Not Own D2 Rendering
30	✦ > Current Contract Violations > Cytograph Extension Does Not Own Cytograph Rendering
31	✦ > Current Contract Violations > Tasks Extension Does Not Own Tasks Rendering
32	✦ > Current Contract Violations > Cryptograph Has No Extension
33	✦ > Current Contract Violations > Markdown Renderer Still Has Hard-Coded Fallbacks For Disabled Extensions
34	✦ > Current Contract Violations > Markdown Renderer Imports Extension Implementations
35	✦ > Current Contract Violations > Wikilinks Are Ambiguous In The Current Language
36	✦ > Current Contract Violations > Asset Bundles Are Mostly Fiction
37	✦ > Current Contract Violations > Storage Namespaces Are Not Used
38	✦ > Current Contract Violations > Routes Are Still Core-Owned
39	✦ > Current Contract Violations > `theme_extensions` Is In The Wrong Place
40	✦ > Current Contract Violations > Static Build Is Not Extension-Aware
41	✦ > Current Contract Violations > Tests Validate Metadata, Not Extension Behavior
42	✦ > Target Folder Shape
43	✦ > Target Core Shape
44	✦ > New Contract To Implement > `VyasaExtension`
45	✦ > New Contract To Implement > `VyasaExtensionApp`
46	✦ > New Contract To Implement > Registration Validation
47	✦ > New Contract To Implement > Runtime Freeze
48	✦ > Extension Runtime Build Order
49	✦ > File-Level Audit And Target Ownership > `vyasa/__init__.py`
50	✦ > File-Level Audit And Target Ownership > `vyasa/admin_views.py`
51	✦ > File-Level Audit And Target Ownership > `vyasa/agent.py`
52	✦ > File-Level Audit And Target Ownership > `vyasa/assets.py`
53	✦ > File-Level Audit And Target Ownership > `vyasa/bootstrap.py`
54	✦ > File-Level Audit And Target Ownership > `vyasa/build.py`
55	✦ > File-Level Audit And Target Ownership > `vyasa/config.py`
56	✦ > File-Level Audit And Target Ownership > `vyasa/content_routes.py`
57	✦ > File-Level Audit And Target Ownership > `vyasa/content_tree.py`
58	✦ > File-Level Audit And Target Ownership > `vyasa/core.py`
59	✦ > File-Level Audit And Target Ownership > `vyasa/document_pages.py`
60	✦ > File-Level Audit And Target Ownership > `vyasa/extensions.py`
61	✦ > File-Level Audit And Target Ownership > `vyasa/favicon.py`
62	✦ > File-Level Audit And Target Ownership > `vyasa/file_search.py`
63	✦ > File-Level Audit And Target Ownership > `vyasa/helpers.py`
64	✦ > File-Level Audit And Target Ownership > `vyasa/layout_helpers.py`
65	✦ > File-Level Audit And Target Ownership > `vyasa/layout_page.py`
66	✦ > File-Level Audit And Target Ownership > `vyasa/logging.py`
67	✦ > File-Level Audit And Target Ownership > `vyasa/main.py`
68	✦ > File-Level Audit And Target Ownership > `vyasa/nav_views.py`
69	✦ > File-Level Audit And Target Ownership > `vyasa/page_shell.py`
70	✦ > File-Level Audit And Target Ownership > `vyasa/page_views.py`
71	✦ > File-Level Audit And Target Ownership > `vyasa/rbac_config.py`
72	✦ > File-Level Audit And Target Ownership > `vyasa/rbac_store.py`
73	✦ > File-Level Audit And Target Ownership > `vyasa/runtime_context.py`
74	✦ > File-Level Audit And Target Ownership > `vyasa/search_http.py`
75	✦ > File-Level Audit And Target Ownership > `vyasa/search_pages.py`
76	✦ > File-Level Audit And Target Ownership > `vyasa/search_service.py`
77	✦ > File-Level Audit And Target Ownership > `vyasa/search_views.py`
78	✦ > File-Level Audit And Target Ownership > `vyasa/sidebar_helpers.py`
79	✦ > File-Level Audit And Target Ownership > `vyasa/tree_rendering.py`
80	✦ > File-Level Audit And Target Ownership > `vyasa/tree_service.py`
81	✦ > File-Level Audit And Target Ownership > `vyasa/tree_tables.py`
82	✦ > File-Level Audit And Target Ownership > `vyasa/auth/*`
83	✦ > File-Level Audit And Target Ownership > `vyasa/static/scripts.js`
84	✦ > File-Level Audit And Target Ownership > `vyasa/static/header.css`
85	✦ > File-Level Audit And Target Ownership > `vyasa/static/present.css` And `present.js`
86	✦ > File-Level Audit And Target Ownership > `vyasa/theme_extensions/*`
87	✦ > Built-In Extension Inventory > `markdown`
88	✦ > Built-In Extension Inventory > `tabs`
89	✦ > Built-In Extension Inventory > `mermaid`
90	✦ > Built-In Extension Inventory > `d2`
91	✦ > Built-In Extension Inventory > `cytograph`
92	✦ > Built-In Extension Inventory > `tasks`
93	✦ > Built-In Extension Inventory > `cryptograph`
94	✦ > Built-In Extension Inventory > `slides`
95	✦ > Built-In Extension Inventory > `default_layout`
96	✦ > Built-In Extension Inventory > `themes`
97	✦ > Built-In Extension Inventory > `blog_home`
98	✦ > Built-In Extension Inventory > `default_search`
99	✦ > Built-In Extension Inventory > `bookmarks`
100	✦ > Built-In Extension Inventory > `annotations`
101	✦ > Built-In Extension Inventory > `filesystem`
102	✦ > Built-In Extension Inventory > `documents`
103	✦ > Built-In Extension Inventory > `tree_document`
104	✦ > Built-In Extension Inventory > `pdf_document`
105	✦ > Built-In Extension Inventory > `live_reload`
106	✦ > Built-In Extension Inventory > `code_highlight`
107	✦ > Built-In Extension Inventory > `math`
108	✦ > Built-In Extension Inventory > `embeds`
109	✦ > Mechanical Migration Plan > Phase 0: Freeze Current Behavior
110	✦ > Mechanical Migration Plan > Phase 1: Build The Real Contract
111	✦ > Mechanical Migration Plan > Phase 2: Convert Built-In Registry To Extension Objects
112	✦ > Mechanical Migration Plan > Phase 3: Move Themes Under Built-In Extensions
113	✦ > Mechanical Migration Plan > Phase 4: Extract Diagram Renderers From Markdown
114	✦ > Mechanical Migration Plan > Phase 5: Extract Tasks Rendering From Markdown
115	✦ > Mechanical Migration Plan > Phase 6: Create Cryptograph Extension
116	✦ > Mechanical Migration Plan > Phase 7: Make Markdown A Pure Pipeline Host
117	✦ > Mechanical Migration Plan > Phase 8: Split Global JavaScript Into Extension Assets
118	✦ > Mechanical Migration Plan > Phase 9: Split Global CSS Into Extension Assets
119	✦ > Mechanical Migration Plan > Phase 10: Move Default Layout
120	✦ > Mechanical Migration Plan > Phase 11: Move Blog Home
121	✦ > Mechanical Migration Plan > Phase 12: Move Search
122	✦ > Mechanical Migration Plan > Phase 13: Move Bookmarks Fully
123	✦ > Mechanical Migration Plan > Phase 14: Move Annotations Fully
124	✦ > Mechanical Migration Plan > Phase 15: Move Slides Fully
125	✦ > Mechanical Migration Plan > Phase 16: Move Documents And Document Kinds
126	✦ > Mechanical Migration Plan > Phase 17: Move Filesystem Content Source
127	✦ > Mechanical Migration Plan > Phase 18: Move Default Errors
128	✦ > Mechanical Migration Plan > Phase 19: Move Live Reload
129	✦ > Mechanical Migration Plan > Phase 20: Static Build Parity
130	✦ > Required Tests
131	✦ > Required Tests > Contract Tests
132	✦ > Required Tests > Disabled Behavior Tests
133	✦ > Required Tests > Asset Tests
134	✦ > Required Tests > Cross-Seam Tests
135	✦ > Source-Scanning Gates
136	✦ > Migration Safety Rules For A Small LLM
137	✦ > Concrete First Patch Order
138	✦ > Mermaid Example Target
139	✦ > End-State Acceptance Criteria
140	✦ > Current Biggest Risks
141	✦ > Final Target Mental Model