-
REQ-FUN-06 (AI Translation Lifecycle & States):
- Target Release: Future Phase (v2.0+)
- Translation Lifecycle Statuses: Each translation entry in the cache database must support a state metadata flag:
draft (default for AI-generated translations) or verified (marked after Translation Manager manual review/override or XLIFF import).
- Translation Pipeline Triggers: The translation generator module must execute strictly upon commits or merges into the primary production branch (
master). Standard feature-branch builds are restricted from making live translation API calls and must execute in secure Read-Only mode.
- Traces to:
REQ-BUS-06
-
REQ-FUN-18 (Asynchronous Non-Blocking Translation CLI):
- Target Release: Future Phase (v2.0+)
- Decoupled Non-Blocking Workflow: The translation review cycle must be decoupled from code integration. Standard development builds must render
draft translations (optionally displaying a configurable "AI-translated draft" warning banner) or fall back to the source English language, ensuring developer velocity is not impacted by manual localization checks.
- Access Control Modes: The CLI must support a
--read-only-cache flag (active by default for general CI/CD builds) to parse and render using existing translation files without making writes, and a --write-cache flag (restricted to authorized Translation Manager sessions in CI/CD) to safely commit updates and state promotion (from draft to verified) to the translation database.
- Traces to:
REQ-BUS-06
-
REQ-FUN-08 (Server-Side Push-Gate Enforcement Modes):
- Target Release: Future Phase (v2.0+)
- Server-Side Modes: Under
--push-gate-mode, the gate enforces policies (reject, allow, auto-document, verify-document).
- Traces to:
REQ-BUS-08
-
REQ-FUN-15 (Quality Gate Scope & Completeness Criteria):
- Target Release: Future Phase (v2.0+)
- Quality Gate Scope: The Quality Gate calculates documentation coverage over all public (
public) and protected (protected) API entities (including classes, interfaces, methods, functions, properties, fields, enums, structs, constants, constructors, etc.) within the scope of code ingestion.
- Documentation Completeness Criteria: An entity is classified as fully "documented" if and only if:
- It has a non-empty, meaningful prose description in its docstring.
- If the entity is a method or function containing parameters or a return value, every single parameter and the return value must also have non-empty, associated descriptions in the docstring schema.
- Traces to:
REQ-BUS-08
-
REQ-FUN-16 (Quality Gate Automatic Exclusions):
- Target Release: Future Phase (v2.0+)
- Automatic Exclusions: The following elements are automatically excluded from the Quality Gate denominator:
- Overridden methods that are explicitly inherited without structural changes from base classes or external system libraries (e.g.,
Equals, GetHashCode, ToString in Java/C#, or __str__, __repr__ in Python).
- Trivial property getters and setters (e.g., automatic properties
get; set; in C#) containing no custom user logic.
- Traces to:
REQ-BUS-05, REQ-BUS-08
-
REQ-FUN-17 (Offline Local Gate Fallbacks):
- Target Release: Future Phase (v2.0+)
- Offline Local Execution: When executed outside a CI/CD environment (detected via environment variables or explicitly passed CLI flags), UDE must enforce an offline-by-default execution policy, utilizing local cache databases or mock placeholders instead of billing live LLM APIs.
- Traces to:
REQ-BUS-05
-
REQ-FUN-12 (Standalone Coverage Reporting Command):
- Target Release: Future Phase (v2.0+)
- Independent CLI Execution: The UDE CLI must support a dedicated, standalone subcommand (e.g.,
ude coverage) to audit documentation coverage and output reports. This command must be fully executable independently of the main documentation compilation and rendering workflow.
- Reporting Formats: The coverage command must generate structural reports detailing:
- Total audited entities, total documented entities, and the aggregate coverage percentage.
- A comprehensive list of specific undocumented or partially documented entities (with file names and line numbers).
- Outputs in multiple formats, including human-readable CLI terminal prints, detailed Markdown summaries, and structured JSON for integration with external dashboards.
- Traces to:
REQ-BUS-08
-
REQ-FUN-13 (Ignore Tags & Range Boundaries):
- Structural Exclusions: The parser, quality gate, and coverage modules must completely ignore any code blocks or entities demarcated by the following tags:
- Block Range Exclusions: All code and entities situated between
DOM-IGNORE-BEGIN and DOM-IGNORE-END comments.
- Conditional Block Exclusions: All code and entities situated between
\cond (or @cond) and \endcond (or @endcond) directives.
- Internal Tag Exclusions: Any entity containing or marked with the
\internal (or @internal) tag.
- Traces to:
REQ-BUS-05, REQ-BUS-08
-
REQ-FUN-09 (Context-Rich Source Ingestion & Decoupled Tooling): The ude-enrich module/script must extract both the declaration (signature) and the definition (implementation body/block) for any undocumented code entity. When sending a prompt to the LLM for English docstring generation, this tool must construct a composite payload containing both the declaration and the full implementation body as context, ensuring that the generated docstrings accurately reflect the internal logic, thrown exceptions, and side-effects of the code. The tool must write back only the resulting docstrings to the source code or output documentation without altering any functional logic.
- Target Release: Future Phase (v2.0+)
- Traces to:
REQ-BUS-05
-
REQ-FUN-10 (XLIFF Export and Import CLI Commands): The UDE CLI must support standard subcommands for exporting and importing localization files in XML Localisation Interchange File Format (XLIFF, .xlf format, version 1.2 or 2.0) to enable integration with professional translators:
- Target Release: Future Phase (v2.0+)
- Export Command (
ude translation export <lang> --output <file.xlf>): Extract all source English docstrings and prose blocks alongside their corresponding AI-proposed translation segments with a status of draft, formatting them into a standard XLIFF translation unit (<trans-unit>) containing <source> and <target> nodes.
- Import Command (
ude translation import <file.xlf>): Ingest a translated .xlf file back into the local translation cache, updating translation strings and automatically promoting their lifecycle status from draft to verified.
- Traces to:
REQ-BUS-06
-
REQ-FUN-07 (Non-Interactive CLI Automation): The CLI engine must support execution in completely non-interactive mode with standard exit codes, configurable via command-line arguments and environment variables, for hands-free automation in CI/CD pipelines.
-
REQ-FUN-11 (Transparent Compression of JSON Artifacts): The engine must store and manage all persistent JSON artifacts—specifically the Intermediate Representation (IR) files and the Translation Cache database—in a compressed format using the standard Gzip algorithm (with file extension .json.gz). The CLI orchestrator and modular subcommands must transparently decompress these files into memory upon startup or ingestion, and compress them back to disk upon execution completion or export, ensuring zero uncompressed JSON pollution in repository storage.
- Baseline (MVP v1.0): Intermediate Representation compression.
- Future Phase (v2.0+): Translation Cache compression.
- Traces to:
REQ-BUS-03