Skip to main content
Version: 3.0 (Next)

V3.0 — Next Milestone

:::info Prerequisite: v2.0 stable None of the items below are implemented. New ids REQ-V3-01..REQ-V3-35 are minted in this file; GAP-* / REQ-BUS-* aliases are preserved where an item descends from one. Sources: .antigravitycli/planned.md "UDE v3.0 Requirements" §1–7, and roadmap/future_v2.md's former "Version 3.0+ — Deferred Roadmap" section, reconciled against verified code state — several status/version claims in both source documents were corrected during this restructuring; see each entry's Evidence field. :::

A. Rendering parity & output completeness​

REQ-V3-01​

C++/C#/Java Structural Render Parity

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: GAP-28
  • Traces to: REQ-BUS-10
  • Evidence: engine/ude/renderers/static_html.py:232 (HtmlRenderer._post_render, no-op body at :240) and engine/ude/renderers/oda.py:290 (ODAHtmlRenderer._post_render, no-op body at :298) — both base-class hooks are pass. Only PyHtmlDefaultRenderer._post_render (static_html.py:928) and the Python ODA equivalent (oda.py:921) override them, each documented as rendering "one category landing page per (namespace, group) pair." Scope correction: the gap spans both renderer families (Default and ODA), not one — six non-Python concrete classes lack this hook's override, not three.

Category landing pages, namespace-level index pages, overload dispatcher pages (!!OVERLOADED_*), and member-type index pages (!!MEMBERTYPE_*) must render equivalently for C++, C#, and Java — today only Python does. Language-specific rules to implement: C++ uses :: separator + __ flat-mapping + pointer/reference substitution; C# needs interface/delegate/event entity-type handling; Java needs extends/implements relationship rendering. This item absorbs REQ-V2-10's (GAP-32) three non-Python per-language rendering residuals — they are the same underlying work, not independent gaps. Prerequisite GAP-03 (typed IR) is met.

:::caution Do not use as evidence The Docomatic content-alignment achievement (REQ-FUN-49, ≥98% match, v2.0-shipped.md) is a different property from this one and must never be cited as proof this item is done — see that file's boundary note. :::

REQ-V3-02​

Fully Static Document Generation

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: GAP-30
  • Traces to: REQ-BUS-10, REQ-BUS-11
  • Evidence: engine/ude/renderers/static_html.py:539-588 — the sidebar-item loop is flat, iterating sidebar_items at the top level only, hard-coding "children": [] on every custom-page node (:569, :584, :587). engine/ude/renderers/hugo_markdown.py:515-554 has the identical flat shape; its only other children-shaped structure (:588-602) is the unrelated namespace-nesting map. grep-confirmed: neither file contains item.get("children") or item["children"] anywhere.

Complete self-contained static site composition from composed static/inline/redirect node hierarchies with nested child nodes — today's GAP-26 delivery (REQ-V2-11) renders each of those three node types correctly but only as flat, unnested siblings. source_path in static nodes must resolve relative to the sidebar.toml file location. Prerequisites GAP-06 and GAP-26 are both met; only the nesting/composition logic itself remains unbuilt.

REQ-V3-03​

Docomatic ODA HTML Compatibility

  • Status: PARTIAL
  • Target: v3.0
  • Alias: GAP-29
  • Traces to: REQ-BUS-10
  • Evidence: engine/ude/renderers/oda.py:749,782,819,875,1864,1901,1946,2010 — all 8 concrete ODA classes exist (Cpp/Cs/Java/Py × Html/Hugo). engine/tests/test_docomatic_alignment.py:13 (imports ODAHtmlRenderer, ODAHugoMarkdownRenderer), :490-494 (parametrizes oda_html for cpp/cs/java) and :694-701 (ceiling table includes oda_html/oda_hugo_markdown for cpp, oda_html for csharp/java) — the alignment suite already gates 6 of the 8 classes.

Delivered: oda_html is alignment-gated for cpp/cs/java; oda_hugo_markdown is alignment-gated for cpp. Remaining, and permanently unachievable as originally worded: Python ODA HTML/Hugo alignment — Doc-O-Matic never produced Python documentation, so no Docomatic Python baseline exists or ever will. The requirement text must be re-scoped to the 6 achievable classes (Cpp/Cs/Java × Html/Hugo-ODA) with the Python exclusion recorded as a permanent, documented carve-out, not an open gap. Remaining real work: oda_hugo_markdown alignment gating for cs/java (currently only cpp is gated per the evidence above).

REQ-V3-04​

Python Property & Dunder-Method Edge Cases

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: GAP-32 (Python residual)
  • Traces to: REQ-BUS-01
  • Evidence: file-level only, not independently re-verified this pass.

fget/fset property rendering and dunder-method edge cases for Python. Kept separate from REQ-V3-01: Python already has a working _post_render override, so this is edge-case hardening on an existing capability, not parity work against a missing one.

REQ-V3-05​

RAG Hierarchical JSON Export

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: REQ-FUN-05
  • Traces to: REQ-BUS-04
  • Evidence: no json_rag format, RAG renderer, or equivalent module exists under engine/ude/ (file listing verified — no rag*.py in renderers/ or formatters/).

--format json_rag: a hierarchical, metadata-rich JSON export of the full code hierarchy (Module/Namespace → Class/Interface/Struct → Methods/Properties/Fields/Constants). Per-entity metadata: entity_type, fully_qualified_name, line_range, signature_hash, dependencies.

:::note Owner-confirmable placement Both source documents (planned.md:19, future_v2.md's former v3.0+ section) scope this v3.0. It has no dependency on the parity or AI tracks — it is an additional formatter over the already-typed IR. Default: V3.0. See decision 1 in .antigravitycli/requirements_restructuring/opus_requirements_plan.md §12 if the owner prefers V4.0+. :::

REQ-V3-06​

Automated Diagram Generation

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-02
  • Evidence: no diagram-generation module exists under engine/ude/.

Structural diagrams (e.g. class inheritance trees) generated natively in Mermaid and PNG formats, automatically embedded into rendered output.

REQ-V3-07​

Native Multi-Dialect Comment Support

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-01
  • Evidence: engine/ude/parsers/dialects/ currently implements plain, sphinx_rst, numpy_swig only (SWIG-Python-oriented) — no native reST, Qt-style, or extended Javadoc dialect handlers. Everything known today about which notations real sources actually use was found incidentally, while chasing unrelated recall-alignment bugs during DEL-B33 (see below) — never by a deliberate survey. Treat today's evidence as a lower bound, not a completed inventory.

Native engine support for parsing and processing additional documentation comment standards beyond today's SWIG-Python-oriented dialects — reStructuredText (reST), Qt-style, and others — as first-class, non-SWIG-specific dialects.

Expanded 2026-08-25 (owner request) to make explicit what was previously only an aspiration — support is required per language (C++, C#, Java, Python) and must explicitly include Docomatic's own notation, not just Doxygen/Javadoc/Google/NumPy/Sphinx. This has two ordered parts; the first is a prerequisite for scoping the second correctly, not paperwork:

  1. Survey, per language, what notations real sources actually contain — the mock SDK is not evidence for this (it deliberately uses sphinx_rst for Python specifically to exercise that dialect's code path, which is already confirmed to NOT match real ODA Python, so it cannot stand in for a real survey of any language). Cover at minimum: real ODA source (all 4 languages) via sdk_sources/sdk_refs, the LLVM+OpenCV reference corpus (DEL-B30), and Docomatic's own notation specifically — see below, it needs its own dedicated pass, not a byproduct of chasing something else.
  2. Docomatic's notation is currently understood only incidentally, in two fragments, both found while root-causing unrelated recall gaps — not from a real survey:
    • DOM-IGNORE-BEGIN/DOM-IGNORE-END (Doc-O-Matic's own spelling of Doxygen's \cond/\endcond) — confirmed real, handled today via dom_ignore_filter.py (REQ-FUN-13).
    • A malformed <link A::B, Text> pseudo-tag, found in 174 real ODA C# source files across Drawings/Ifc/Kernel/Exchange/Prc — looks like a broken translation of Doxygen's own \link Target Text \endlink, but confirmed (direct Doxygen test against the real vendor header, daiIterator.h) that Doxygen doesn't recognize it as a tag at all: it's escaped and rendered as literal text (&lt;link A::B, Text&gt;), so the hyperlink itself is silently lost — a real, user-visible fidelity gap, not just a harmless warning as the recall-alignment investigation that found it concluded (that investigation only cared whether parsing broke, not whether the link survived). Neither fragment was found by asking "what does Docomatic's own tag vocabulary look like" — both were side effects of debugging something else, so there is no reason to believe these two are the whole vocabulary. A real inventory needs to start from Docomatic's own documentation/behavior (or a corpus of real Docomatic-authored source, if one is identifiable), not from whatever bugs happened to surface so far.

Proposed new task for Delivery_ToDo.md: DEL-B34 (notation survey, all languages + Docomatic, prerequisite) feeding into the existing REQ-V3-07 implementation work.

B. Parsing​

REQ-V3-08​

Native Language Parsers

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: REQ-BUS-01
  • Traces to: REQ-BUS-01
  • Evidence: engine/ude/parsers/ contains only Doxygen-XML-based parsers; no libclang/tree-sitter frontend exists.

Direct source-code parsing without invoking Doxygen, using libclang/tree-sitter AST frontends, producing the same ProjectCatalog IR as the Doxygen-based pipeline (which is retained in parallel). Mandatory sub-requirements, not optional refinements: (a) the caching logic must be completely redesigned for native AST parsing — today's L1/L2 caches are keyed around Doxygen XML compound hashes; (b) parser coverage and accuracy must be no worse than the Docomatic + v2.0 Doxygen baseline (REQ-FUN-49's 39-combination alignment result is the bar to clear, not merely a reference point).

REQ-V3-09​

Path/File/Namespace Include-Exclude Scoping

  • Status: PARTIAL
  • Target: v3.0
  • Alias: REQ-BUS-14 / REQ-FUN-51
  • Traces to: REQ-BUS-14
  • Evidence: engine/ude/collectors/doxygen.py:642-657 — verified: exclude config key → Doxygen EXCLUDE (:642-643); exclude_patterns → EXCLUDE_PATTERNS (:645-649); file_patterns → FILE_PATTERNS with a leading **/ stripped so "any depth" survives Doxygen's per-directory matching (:651-657). Production usage confirmed: ude_projects/Kernel/kernel_api_cpp/ude_doc_config.json uses both file_patterns and exclude_patterns. Two distinct counts, both measured and both meaningful: 16 ude_doc_config.json files use exclude_patterns (i.e. actual path/glob exclusion — the figure cited in .antigravitycli/requirements_restructuring/opus_requirements_plan.md §4.2), and 78 use at least one of exclude/exclude_patterns/file_patterns (the wider figure includes file_patterns, which narrows the input set rather than excluding paths from it, and is present in nearly every config).

Delivered (this is the defect corrected by this restructuring — see brd/requirements.md's REQ-BUS-14 entry, fixed under defect D1): glob/path exclusion (exclude, exclude_patterns) and file-pattern narrowing (file_patterns) at the Doxyfile-generation level, driven by declared ude_doc_config.json keys — not merely the hand-authored collector.doxyfile_template escape hatch this requirement's text originally described as the only route in. Remaining: (a) a true include allowlist semantic distinct from FILE_PATTERNS-style narrowing; (b) namespace-based (not just file-path-based) scoping; (c) an implementation independent of Doxygen — today's mechanism is entirely a Doxyfile pass-through, so it evaporates the moment REQ-V3-08's native parsers replace Doxygen, making this a hard dependency of that track rather than an independent nicety; (d) documentation of the three existing keys, which currently appear in no design-doc or user-doc (user-docs/docs/exclusion-gates.md actively asserted the opposite — corrected under defect D8).

REQ-V3-10​

SWIG Wrapper-Aware Parsing

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-01
  • Evidence: no wrapper-to-origin mapping exists in engine/ude/parsers/; only the coarser exclude_swig_internals name-drop flag exists (see v1.0-mvp.md).

Identify SWIG-generated files by convention, map wrapper entities back to the originating C++ API using SWIG transformation rules, and extract the consumer-facing public API rather than SWIG scaffolding, as a selectable DoxygenXmlParser dialect. Prerequisite for REQ-V3-19(TEST-INT-12, in v4.0-backlog.md).

REQ-V3-11​

Concurrency: Multithreaded Parsing & Rendering

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-NFN-01
  • Evidence: NUM_PROC_THREADS=4 exists as an uncoordinated constant with no surrounding concurrency design (project memory record, not independently re-verified against source in this pass).

Multithreaded AST extraction for source files, and parallel/async render output generation — the IR is read-only at render time, so concurrent file generation is architecturally sound. Must also resolve the uncoordinated NUM_PROC_THREADS=4 constant into an actual coordinated design rather than a bare literal. This is expected to tighten REQ-NFN-01's "≤5s/1000 classes" target; the new target should be proposed when this item is designed, not pre-guessed here (see nfr.md).

C. Reporting, QA & quality gates​

REQ-V3-12​

Build & Execution Reporting

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: REQ-BUS-07
  • Traces to: REQ-BUS-07
  • Evidence: no performance/cost-reporting module exists under engine/ude/.

Post-compilation report: wall-clock time per pipeline stage, file counts, and L1/L2 cache hit ratios. Split from this item: LLM API token usage and estimated cost accounting is inert until translation/ enrichment ships — that sub-item moves to v4.0-backlog.md rather than deferring this entire requirement.

REQ-V3-13​

Documentation Coverage & Quality Linter

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: REQ-FUN-15 (completeness criteria), REQ-FUN-16 (automatic exclusions)
  • Traces to: REQ-BUS-08
  • Evidence: engine/ude/coverage.py:180-193 (_record, shallow docstring is not None check — no per-parameter/return-value completeness); engine/ude/coverage.py:56 (_is_excluded_from_coverage, name-pattern only — no trivial-getter/inherited-override exclusion). See v2.0-shipped.md's note on REQ-V2-08 for what v2.0 already delivers as a simpler baseline.

Warn on undocumented public APIs or low-quality repetitive stubs (fewer than 3 words, exact name-duplication); enforce presence of required @param/@return sections matching the code signature; generate a dedicated diagnostic report of undocumented/poorly-documented entities; flag signature-drift between docstring parameters and the current code signature after refactors.

REQ-V3-14​

Structural & Marker Integrity Checks

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-08

Validate paired documentation markers are properly closed (\cond/\endcond, DOM-IGNORE-BEGIN/END); flag broken internal cross-references (@see, @link).

REQ-V3-15​

Strict Compilation Mode

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-08

Halt the engine run with a FATAL ERROR if critical modules lack documentation, total coverage drops below a hard threshold, or severe markup syntax errors occur.

REQ-V3-16​

API Drift & Changelog Report

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-07

A diff report identifying added, removed, or modified public APIs relative to the previous cache state.

REQ-V3-17​

Structured JSON CI/CD Logging

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09

Standardized machine-readable log levels (DEBUG/INFO/WARN/ERROR/FATAL) for seamless CI/CD integration. Extends REQ-V2-02's unified logging infrastructure.

REQ-V3-18​

CSS Visual Regression Testing

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: TEST-INT-10
  • Traces to: REQ-BUS-10
  • Full spec: srs/integration_tests_specification.md.

Headless-browser (Playwright or Selenium) pixel-diff screenshot checks against pre-approved PNG baselines, flagging layout shifts exceeding a 0.1% threshold. Primary target: Python. Prerequisite — stable HTML template architecture — is met by v2.0's sidebar.toml refactor and custom page rendering.

REQ-V3-19​

Search Index Integrity & Anchor Verifier

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: TEST-INT-11
  • Traces to: REQ-FUN-31
  • Full spec: srs/integration_tests_specification.md.

Validates that compiled search-index JSON entries map to physical generated pages, and resolves anchor references (#ClassName) to confirm matching id/name attributes exist. No unmet prerequisite.

REQ-V3-20​

Standalone Pre-Parse Source Analyzer

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-08

A dedicated, independent tool for deep source-code analysis validating comment-format structural integrity prior to UDE execution (pre-parsing stage).

D. Deployment & infrastructure​

REQ-V3-21​

Self-Hosted Workflow Migration

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09

Migrate CI/CD pipelines and operational workflows to self-hosted infrastructure where practical, building on the runner-resilience work already shipped in v2.0 — see REQ-NFN-07 in nfr.md.

REQ-V3-22​

Minimal Curated Standalone Releases

  • Status: IMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09
  • Evidence: flude-oda-plugin/scripts/build_nuitka.sh (BUILD_PROFILE=oda / EXCLUDE_MODULES, --nofollow-import-to) compiles a binary publishing only oda_html/ oda_hugo_markdown and the 4 language collectors — not the Default-family renderers or every parser backend. Built, signed, and released as oda-v0.9.2 (flude-oda-plugin GitHub Releases) — both Linux and Windows platforms, verified via gh release view to carry both binaries and their .sig files, not just a green CI run. DEL-B37 in Pipeline's Delivery_ToDo.md has the full history.

Compiled, independent executable binaries with flexible feature customization, publishing only the parsers/renderers a given consumer needs (e.g. a tailored, minimal build for ODA).

The obsolete releases/make_release.py source-drop bundle this requirement's evidence used to point to (a different mechanism, distributing source rather than a compiled binary) has been removed entirely (DEL-B37 stage 4, 2026-09-02) — the naming overlap this section used to warn about no longer exists.

REQ-V3-23​

HTML Output Deployment

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-02

Direct web-server installation and a containerized Docker image for static HTML output.

REQ-V3-24​

Markdown/SSG Deployment

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-02

Direct server installation and a containerized Docker image for Hugo (SSG) Markdown output.

REQ-V3-25​

Integrated Search

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-10

A search engine working across both HTML and SSG/Markdown deployment variants, in both server and Docker modes.

REQ-V3-26​

Mock SDK Documentation as a CI Showcase

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09

Configure CI/CD to compile and deploy Mock SDK output as a live showcase.

E. Technical debt​

REQ-V3-27​

Schema Decoupling

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: AW-06
  • Traces to: REQ-NFN-02

Phase-1 GlobalConfig models must not carry Phase-3 schema knowledge.

REQ-V3-28​

Docstring Traceability

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: AW-08
  • Traces to: REQ-NFN-03

Uniform docstring verification enforced in the testing guidelines.

REQ-V3-29​

100% Coverage Mandate

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-NFN-03

Raise both code test coverage and documentation coverage to 100%, enforced as a strict criterion in a pre-push Git hook for engine/. Tightens REQ-NFN-03 — see nfr.md; the current CI-enforced gate is 98% (engine/.github/workflows/ci.yml:89, engine/pyproject.toml:47, both --cov-fail-under=98), last measured at 98.04%. Default per owner-stated text: keep as written; this is a real workflow-cost decision, not a documentation call (see .antigravitycli/requirements_restructuring/opus_requirements_plan.md §12 decision 4).

F. Security — only what is actionable without a server​

:::info Scope boundary The current product is CLI-only, executed locally or in CI, with no network-facing surface. Sandboxing, rate limiting, upload validation, TLS/encrypted storage, OAuth2/JWT + RBAC, and audit logging all presuppose a server-side execution mode that does not exist today — those items are not V3.0 scope; they move to v4.0-backlog.md, marked contingent on that mode ever being built. Only the two items below are actionable against today's product shape. :::

REQ-V3-30​

Continuous Vulnerability Scanning (SAST)

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-NFN-09

Continuous static-analysis vulnerability scanning of the engine's own source, plus strict dependency management.

REQ-V3-31​

Strict Code Publication Prohibition

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09

Security gates preventing proprietary ODA source code or snippets from reaching published output. Real and relevant today — the pipeline already processes proprietary SDK sources.

G. Documentation & process​

REQ-V3-32​

Formal V3.0 Roadmap & Task-Stream Bifurcation

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09

Formally define v3.0 strategic plans and milestones; strictly separate ODA-specific requirements from general UDE engine feature work; develop a cohesive, conflict-free plan respecting that separation.

REQ-V3-33​

design-docs Brought in Step with V3.0

  • Status: PARTIAL — this restructuring is the first instalment
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09

Bring design-docs fully up to date with v3.0 plans. This requirements-catalog restructuring (.antigravitycli/requirements_restructuring/opus_requirements_plan.md, executed 2026-08-14) is the first delivered piece of this item, not its completion — the actual v3.0 architecture/design docs still need writing once V3.0 work begins.

REQ-V3-34​

user-docs Updated for V3.0

  • Status: PARTIAL — the D8 exclusion-gates correction is delivered as part of this restructuring
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09

Comprehensively update user-docs for v3.0 capabilities and structural changes. user-docs/docs/exclusion-gates.md's correction (documenting the exclude/exclude_patterns/file_patterns keys the old text claimed did not exist) is delivered now as defect D8; the rest of this item awaits actual V3.0 feature delivery.

REQ-V3-35​

ude-promotion Kept in Step

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09

The third content repository alongside design-docs and user-docs. Tracked open items (per .antigravitycli/planned.md §7): RSS distribution channel gaps, cross-post idempotency defects (a formatting-only edit currently re-posts as new rather than editing), and five-copy .markdownlint-cli2.jsonc lint-config drift across the five content repositories.

H. Delivery: plugin architecture, binary packaging & CI integration​

:::info Why these sit in their own section REQ-V3-36..REQ-V3-42 were minted 2026-08-14 from .antigravitycli/roadmap_v3_delivery.md, which worked out what shipping Flude to a client and to a public CI marketplace actually requires. Ids in this file are stable once minted and sections A–G are numbered in file order (A=01–07 … G=32–35), so distributing these seven across the existing sections would either break that monotonicity or force a renumber. They are grouped here instead, and each entry names the section it would otherwise belong to. :::

REQ-V3-36​

Renderer & Component Registry

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-NFN-02
  • Topically: section E (technical debt)
  • Evidence: engine/ude/orchestrator.py:692-711 — renderer selection is a hard-coded if/elif chain with function-local imports (from ude.renderers.oda import ODAHtmlRenderer inside a branch). The list of valid format tokens is hard-coded three times independently: the factory (:692-711), a nine-token validator (:788-798), and choices= in the CLI at engine/ude/cli.py:351, :389, :435 (two tokens each). A working registry pattern already exists in the codebase for docstring dialects — engine/ude/parsers/dialects/__init__.py:18 (_REGISTRY), :39 (register), :93 (resolution with an explanatory error).

A single registry must become the only source of truth for which renderers/formats exist. The factory, the validator, and the CLI's --format choices all derive from it rather than restating it. Hard dependency of REQ-V3-37 and of ENG-02's fix: once client-specific renderers move to an external plugin (Clean Room, .antigravitycli/roadmap_v3_delivery.md track A), a static choices= list cannot enumerate them by construction — so ENG-02 must be resolved through this registry, not by copying the nine tokens into argparse.

REQ-V3-37​

Plugin↔Core Compatibility Contract & Build-Time Composition

  • Status: IMPLEMENTED (2026-08-26)
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-NFN-02
  • Topically: section D (deployment & infrastructure)
  • Evidence: no plugin mechanism of any kind exists in engine/ude/; engine/pyproject.toml:9-10 declares a single entry point (ude = "ude.cli:main") and no plugin group.

Client-specific and premium components are composed into a build as build-time inputs, not discovered at runtime — an owner decision recorded 2026-08-14, because a runtime-loaded plugin would sit on the client's disk in readable form and defeat the purpose of REQ-V3-40's binary compilation. Requires a declared plugin-API version checked at composition time, so a core refactor fails the build loudly instead of breaking a shipped client artefact silently. Depends on REQ-V3-36.

Both halves confirmed real, independently, not by report. Version contract: engine/ude/plugin_api.py's PLUGIN_API_VERSION (full semver) and check_plugin_compatibility() on a real packaging.specifiers.SpecifierSet, called at plugin import time by flude-oda-plugin/src/flude_oda_plugin/__init__.py (REQUIRED_ENGINE_API_VERSION = ">=1.0.0,<2.0.0") — an incompatible pairing raises PluginCompatibilityError on import, which fails Nuitka's own build-time trace of build_entry.py's import graph, not merely a runtime check. Build-time composition itself is --nofollow-import-to on Nuitka (EXCLUDE_MODULES env var in both repos' build_nuitka.sh/.ps1) — proven in real CI runs to produce a binary the excluded component is genuinely absent from rather than merely hidden (base/full/curated-ODA binaries differ in byte size and in what actually executes).

REQ-V3-38​

SARIF & Code Quality Report Output

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09
  • Topically: section C (reporting, QA & quality gates)

Structured JSON logging (REQ-V3-17) is necessary but not sufficient for CI integration: the host platforms consume specific formats, not arbitrary JSON. GitHub renders at most 10 error and 10 warning annotations per step (50 per job) from ::error file=... workflow commands — a linter reporting hundreds of findings on an SDK-scale codebase is unusable through that path. SARIF uploaded to Code Scanning carries no such ceiling and produces inline PR comments natively; $GITHUB_STEP_SUMMARY carries the full report. GitLab consumes a Code Quality report artifact (CodeClimate JSON) for its merge-request diff widget. Therefore SARIF and Code Quality must be first-class engine output formats derived from one intermediate representation, not a transformation performed by a wrapper script. Consumers: REQ-V3-13, REQ-V3-14, REQ-V3-16.

REQ-V3-39​

CI Cache & Baseline Persistence

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-07
  • Topically: section C (reporting, QA & quality gates)

Two distinct consequences of running on ephemeral CI runners, both currently unaddressed:

  1. Performance — the L1/L2 caches start empty on every run, so each pull request re-parses the entire SDK through Doxygen. Requires host cache integration (e.g. actions/cache), a documented cache-key design, and a changed-files-only parse mode.
  2. Functionality — REQ-V3-16 is defined as a diff against "the previous cache state", which does not exist on an ephemeral runner. Without baseline persistence between runs (cache or stored artefact), REQ-V3-16 cannot function in CI at all. This makes the present item a hard prerequisite of REQ-V3-16, not an optimisation of it.

REQ-V3-40​

Nuitka Binary Build Pipeline

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09
  • Topically: section D (deployment & infrastructure)
  • Evidence: nuitka and pyinstaller appear nowhere in the project's own sources, configuration, or CI — the only matches in the tree are inside third-party packages under engine/.venv/ and in strategy prose (ude_promotion/strategy/monetization.md, positioning.md). No build script, packaging config, or CI job exists to extend.

Compilation of the engine to native executables, with modular composition so a given build contains only the parsers and renderers a consumer is entitled to. Supplies the artefact REQ-V3-22 distributes and REQ-V3-41 packages. Depends on REQ-V3-37.

REQ-V3-41​

Container Image & GitHub Action Package

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09
  • Topically: section D (deployment & infrastructure)
  • Evidence: engine/ude/collectors/doxygen.py:80, :427 (shutil.which("doxygen")) and :190 (subprocess.run) — the engine invokes Doxygen as an external native binary, which any image must therefore also ship.

A container image plus a GitHub Action manifest published from a dedicated public repository (Marketplace requires action.yml at a repository root; it cannot be published from a monorepo with submodules). Two constraints are decisions, not defaults, both recorded 2026-08-14:

  • The action is packaged as a Docker container action, which GitHub runs on Linux runners only — Windows and macOS runners are unsupported and must be documented as such in the manifest and README.
  • The base image is Debian-slim rather than distroless or Alpine, because Doxygen and its runtime dependencies must be present. Doxygen is GPL-2.0 and must appear in the distributed NOTICE. A genuinely minimal image is unreachable until REQ-V3-08 replaces Doxygen with native parsers — a stated dependency, not an aspiration.

REQ-V3-42​

GitLab CI Template

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-09
  • Topically: section D (deployment & infrastructure)

A ready-to-include .gitlab-ci.yml template for consumer pipelines, emitting the Code Quality report artefact from REQ-V3-38 so findings surface in the merge-request diff widget.

REQ-V3-43​

Source Location Tracking in the IR

  • Status: IMPLEMENTED (2026-08-19)
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-V3-38
  • Topically: section B (parsing)
  • Evidence: engine/ude/models.py — none of ClassModel, MethodModel, VariableModel, ConstantModel, EnumModel, TypeAliasModel carries a source file path or line number; the IR is a pure documentation-content model. Doxygen's own XML already carries this per entity (confirmed: <location file="..." line="..." .../> on every <compounddef>/<memberdef>), and the parser already knows how to read one instance of it for an unrelated purpose (engine/ude/parsers/doxygen_base.py:556-557, filtering location.get("file") == "[generated]" compounds) — it is simply never persisted into the IR.

Minted 2026-08-19 as a discovered prerequisite of REQ-V3-38, not part of the original seven REQ-V3-36 .. REQ-V3-42 batch: SARIF's and GitLab Code Quality's entire value proposition for CI consumers is inline, per-line annotation in a PR diff, which is impossible without a file/line on each finding. Populating the source location on the IR's own entities is the natural, single place to source that data for every consumer (REQ-V3-38's findings today, REQ-V3-13/REQ-V3-16's linters later) — duplicating location-extraction logic per consumer instead would be the same "one fact repeated N times" problem this file's registry-style fixes (REQ-V3-36) exist to avoid.

Scope: add file: Optional[str] = None and line: Optional[int] = None to the IR models listed above; populate them from each entity's own <location> element at parse time; extend engine/ude/coverage.py's EntityCoverage/compute_coverage() to carry the same two fields through, since that is the first real consumer this unblocks. Explicitly not in scope: rendering file/line anywhere in HTML/Hugo output — renderers are untouched, so golden-master byte-parity is unaffected.

Delivered: exactly as scoped above, verified independently against the real diff (not the executor's report) — full engine suite green (777 tests, 98.17% coverage), black/mypy clean, backward compatibility of pre-existing serialized IR (missing file/line keys) confirmed by direct deserialization, and the four regenerated engine/tests/assets/golden_master/ir/*.json fixtures spot-checked for real, per-language, non-null file/line values rather than blanket null. tests/integration/regression/ baseline/ir/mock_api_*.json.gz (Pipeline superproject, not engine) also regenerated in the same session — the L1 "Models are identical" regression check compares a fresh parse against that checked-in baseline, and adding real file/line values would otherwise have broken it on every mock-SDK combination.

REQ-V3-44​

Open-Source Reference Corpus for Core Engine Validation

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: REQ-BUS-01, REQ-V3-08
  • Topically: section C (reporting, QA & quality gates) — also touches section B (parsing)
  • Evidence: DEL-A09 (closed 2026-08-16) independently reproduced two general, non-ODA-specific parser bugs (sfinae_filter.py, dom_ignore_filter.py) on the open Qt/LLVM corpus, as a one-off retrospective legal-provenance exercise (legal-risks.md risk #1, question B). Separately, engine is already structurally decoupled from ODA content post-DEL-A04 (Clean Room): oda.py and test_docomatic_alignment.py both moved to flude-oda-plugin, and REQ-FUN-49's own alignment evidence now lives entirely in that separate repository (see the post-freeze correction on REQ-FUN-49 in v2.0-shipped.md) — engine can no longer even run that recall methodology itself, by design. Corpus choice (2026-08-21, owner decision): LLVM and OpenCV, not Qt — both verified live and Doxygen-based (llvm.org/doxygen/, docs.opencv.org), both Apache-2.0 (permissive, lighter attribution than Qt's LGPL), both publish their own Doxyfile config (llvm/docs/doxygen.cfg.in; OpenCV's is in-tree per module) for matching invocation conventions. Verified: neither language-native docs site for C#/Java/Python at this scale/quality exists in the open-source ecosystem (Java: nothing beyond toy projects; C#: nothing found; Python: the ecosystem uses Sphinx, not Doxygen, almost universally) — see the SWIG approach below for covering those three languages from the same two C++ corpora instead of hunting for unrelated per-language open-source projects.

Minted 2026-08-21 to generalize DEL-A09's one-off exercise into a standing practice: LLVM and OpenCV (public, large-scale, template/macro-heavy real-world C++, each with published Doxygen-generated reference documentation) become the permanent reference corpus for developing, testing, and validating the core, non-ODA engine — explicitly replacing any use of ODA's own proprietary sdk_sources/sdk_refs for that purpose, not just retroactively justifying past use of them. Applies only to engine; does not touch flude-oda-plugin's own recall/alignment methodology against real ODA/Doc-O-Matic output, which remains legitimate, unchanged, and is that plugin's entire reason to exist.

Three distinct QA concerns, not to be conflated:

  1. Parser robustness/regression (C++, direct). Run the Doxygen-based parser (and, later, REQ-V3-08's native libclang/tree-sitter frontends — an ideal stress target given LLVM/OpenCV's heavy template and macro use) directly against real LLVM/OpenCV C++ source, watching for crashes and unexpected output-shape drift. LLVM and OpenCV's own published Doxygen sites are real, independently generated reference output from the same tool family this engine already builds on — useful for spot-checking rendering/extraction fidelity against a known-good public example, though this is a weaker signal than REQ-FUN-49's Docomatic-vs-Doxygen cross-tool alignment (both sides here ultimately derive from Doxygen), so this remains primarily a stability/regression gate (diff against a deliberately-updated checked-in baseline snapshot), not a true independent recall measurement. It does not replace REQ-FUN-49's bar for REQ-V3-08's own acceptance criterion, which is structurally tied to flude-oda-plugin's content and stays there; it is a complementary, engine-side gate.
  2. Parser robustness/regression (C#/Java/Python, via SWIG). No open-source corpus of comparable scale/quality exists natively in these three languages (see Evidence above). Instead, generate SWIG bindings from a deliberately hand-picked, SWIG-tractable subset of LLVM/OpenCV's C++ API (neither project uses SWIG for its own official bindings — OpenCV's Python bindings come from its own modules/python/src2/gen2.py generator, LLVM's from the plain llvm-c API — so new .i interface files must be authored in-house, not reused from upstream) and run the engine's existing SWIG-aware parsing path (exclude_swig_internals, the numpy_swig dialect) against the generated C#/Java/Python wrapper code. This directly extends the already-known SWIG-macro-leak class of bug (see the project's own prior finding of leaked internal macros in generated Kernel Python bindings) to a larger, public corpus, using the same two licensed-and-cleared source projects instead of introducing a third and fourth unrelated open-source dependency per language. This is robustness testing only — SWIG-generated docstrings are mechanically derived from the same C++ signatures already being parsed on the C++ side, not an independent reference, so no recall/precision claim attaches to this path either way.
  3. Standing developer practice. Whenever engineering work on the core parser needs a large, real, complex codebase (in any of the four target languages) to explore or debug against, LLVM/OpenCV (and their derived SWIG bindings) is the material to reach for — sdk_sources/sdk_refs are not, going forward, even informally. DEL-A09 was the first, retroactive instance of this; this requirement makes it the permanent default.

Open decisions, not to be implemented ahead of an owner call (see DEL-B30): what scope (a full checkout of either project is almost certainly too large for a reasonable CI cadence — a pinned subset of modules/headers is the realistic shape, and the same subset should drive the SWIG .i files so the C++ and cross-language paths stay consistent); which specific classes/headers are SWIG-tractable enough to be worth the authoring effort; and whether any corpus source (C++ headers or generated SWIG bindings) gets vendored into engine's own fixtures at all (if so, coordinate with DEL-A11's NOTICE file work — that triggers real attribution obligations the CI-only, nothing-checked-in case does not).

REQ-V3-45​

Developer Guide / Narrative Content Integration

  • Status: UNIMPLEMENTED
  • Target: v3.0
  • Alias: —
  • Traces to: —
  • Topically: section A (rendering parity & output completeness) — content-source side touches section H (plugin architecture) for the ODA-specific case
  • Evidence: workspace/dev_guides/ (gitignored local vendor material, confirmed 2026-08-21) holds ODA's own hand-authored developer-guide content across ~15 product modules (Kernel, Drawings, BimNv, Civil, IFC, Mechanical, etc.) — roughly 3,300 HTML pages plus ~2,500 image/video/SVG assets. This is narrative, hand-written content (tutorials, "Getting Started," per-module architecture guides), not anything derived from parsing client source code — today's pipeline (Collect → Parse/IR → Render) has no concept of a content type that isn't IR-derived. A minority of modules (e.g. DrawingsInWeb) already carry ODA-authored Markdown alongside the HTML; most modules are HTML-only.

Minted 2026-08-21 by explicit owner request to bring developer-guide/narrative content into delivery scope, alongside the existing auto-generated API reference:

  1. ODA HTML output: the existing ODA HTML dev-guide pages are used as-is (no reformatting) and integrated into the generated oda_html site's navigation, next to the auto-generated API reference.
  2. ODA Hugo Markdown output: the existing ODA HTML dev guides are converted to Markdown for modules that don't already have one (most of them), then integrated into the oda_hugo_markdown site the same way.
  3. Flude Core (non-ODA): new, originally-authored Markdown developer-guide content is written for the mock SDK fixture (and possibly for Flude itself) — not derived from or containing any ODA content, per the same Clean Room boundary as everything else client-specific.
  4. HTML output for Flude Core is deprioritized (owner decision, 2026-08-21): treated as a legacy carry-over from the project's ODA-oriented origins, not a target for further investment. Future Core-facing developer-guide work targets Markdown only. This does not remove existing html/ static_html support (DEL-B02, DEL-B15) — it only means new narrative-content work doesn't extend to that format for the non-ODA product line.

Clean Room split (owner decision, 2026-08-21): the generic mechanism — ingesting a narrative content tree and integrating it into a rendered site's navigation alongside the IR-derived API reference, for both HTML and Hugo Markdown — is engineered inside engine, format-agnostic and not ODA-specific. The actual ODA dev-guide content (source HTML pages, and their converted Markdown) lives entirely in flude-oda-plugin, exactly like oda.py and the recall/alignment methodology (DEL-A04/ DEL-A05). engine never contains ODA-specific narrative content, only the capability to render a content tree that some other repository supplies.

Piloted on one module first (owner decision, 2026-08-21): BimNv — deliberately not one of the modules that already ships ODA-authored Markdown (e.g. not DrawingsInWeb), so the pilot proves the harder, more representative case (HTML-only source, real conversion required) rather than the easy case. Full ~15-module rollout follows only after the pilot's approach is validated, not before.

Proof: oda_html and oda_hugo_markdown builds for the BimNv pilot module both include the dev-guide content, discoverable from the generated site's navigation, with working internal links and correctly resolved image/asset paths; the Markdown conversion is readable and structurally faithful to the source HTML (not a mechanical dump); a mock SDK build (Flude Core) includes original, non-ODA narrative content in Markdown output only.