Skip to main content
Version: 3.0 (Next)

Non-Functional Requirements — Sole Authority

:::info Why NFRs live in one file, not one per version A coverage threshold is tightened across versions, not re-authored; the same is true of every non-functional property below. Filing NFRs per-version would recreate the exact drift this restructuring exists to fix — four copies of a small NFR set, changing independently until they disagree. v1.0-mvp.md, v2.0-shipped.md, v3.0-next.md, and v4.0-backlog.md reference REQ-NFN-* ids; none of them restate NFR text. :::

Core (v1.0)​

REQ-NFN-01​

Execution Performance

  • Status: IMPLEMENTED (rendering leg only -- see below)
  • Introduced: v1.0
  • Category: Performance
  • Evidence: engine/tests/test_performance_benchmark.py; real profiling on ude_projects/Kernel/kernel_api_cpp (~1000 classes) after DEL-B31's renderer parallelization.

The parser and renderer must process and output documentation for up to 1,000 API classes in under 5 seconds on a standard GitHub Actions runner. DEL-B31 parallelized rendering (decision #19) and measured, rather than guessed, where the remaining time actually goes:

  • Doxygen subprocess: ~41.5s
  • Python XML parse: ~27.1s
  • Python normalization: ~1.6s
  • Parallel render (Hugo, 8 workers): ~11.7s
  • Total: ~82s

Rendering itself is now genuinely parallel and scales across cores, but the Doxygen subprocess and the (deliberately still-sequential, per decision #18) Python XML parse are the dominant serial cost -- the pipeline does not meet the 5s target end-to-end. Per this file's own rule below, no new number is proposed here from this profiling pass alone.

  • History: REQ-V3-11 (concurrency, v3.0-next.md) is expected to tighten this target once multithreaded parsing/rendering is designed. Do not restate a new number here speculatively — the default per .antigravitycli/requirements_restructuring/opus_requirements_plan.md §12 decision 3 is to leave this target unchanged until REQ-V3-11 itself proposes a replacement.

REQ-NFN-02​

Modularity

  • Status: IMPLEMENTED
  • Introduced: v1.0
  • Category: Architecture
  • Evidence: engine/ude/interfaces.py (BaseParser, BaseRenderer).

The system must define rigid abstract base classes allowing independent plugins to be loaded at runtime via dynamic Python imports.

REQ-NFN-03​

Test Coverage

  • Status: IMPLEMENTED
  • Introduced: v1.0
  • Category: Quality
  • Evidence: engine/.github/workflows/ci.yml:89 and engine/pyproject.toml:47 — both verified reading --cov-fail-under=98.

The requirement is the enforced CI gate: ≥ 98% statement coverage. The last recorded measurement was 98.04% (.antigravitycli/planned.md:186, 2026-08-02).

:::danger Do not republish the 99.8% figure srs/task_compliance.md:46 (now retired) claimed "Current Overall Test Coverage (pytest-cov): 99.8%." That figure is stale and was never reconciled against the actual CI gate value or the last real measurement. The requirement is the gate (98%), not a point-in-time snapshot — snapshots go stale the moment a new commit lands; a gate does not. :::

  • History: REQ-V3-29 (v3.0-next.md) proposes tightening this to 100%, enforced by a pre-push hook on engine/.

REQ-NFN-04a​

Pydantic v2 for the Intermediate Representation

  • Status: IMPLEMENTED
  • Introduced: v1.0
  • Category: Core technology
  • Evidence: engine/ude/models.py.

The system's data-parsing, validation, and serialization for the IR must use Pydantic v2, for fast execution and robust, typed validation of deeply nested AST structures.

REQ-NFN-04b​

Pydantic v2 for Translation Caches

  • Status: UNIMPLEMENTED
  • Introduced: v4.0+
  • Category: Core technology
  • Evidence: no translation cache exists to validate (see REQ-BUS-06 in v4.0-backlog.md).

:::note Correction applied here (defect D10) srs/non_functional.md:11 (now retired) bundled this under the same REQ-NFN-04 entry as REQ-NFN-04a, tagged "v2.0+ for Translation caches." Since translation itself is v4.0+ scope (not v2.0, and not even v3.0), this half is retargeted to v4.0+ and split into its own id so it can carry an accurate Status/Introduced pair independent of the IR half, which has been IMPLEMENTED since v1.0. :::

REQ-NFN-04c​

Jinja2 Template Engine

  • Status: IMPLEMENTED
  • Introduced: v1.0
  • Category: Core technology
  • Evidence: engine/ude/templates/, engine/ude/renderers/.

The rendering/formatting engine must use Jinja2 to compile structural documentation pages and allow stakeholder/developer customization of Markdown, HTML, and XML layouts.

Operability (v2.0 — new category)​

:::info Why this category is new, and not optional The old non_functional.md held exactly four entries. Meanwhile RUNBOOK.md documents six substantial, already-engineered reliability properties that existed only as incident-response prose and were never promoted to a REQ-NFN-* id. REQ-NFN-05..REQ-NFN-10 backfill that gap from RUNBOOK.md and closed incidents. This also gives the V3.0/V4.0 security track (REQ-V3-30/REQ-V3-31, v3.0-next.md) a real foundation instead of a from-zero aspiration. :::

REQ-NFN-05​

Concurrent-Build Safety

  • Status: PARTIAL
  • Introduced: v2.0
  • Category: Operability
  • Evidence: engine/ude/doxygen_lock.py (ProjectKeyLock); RUNBOOK.md §4 "Orphaned Doxygen cache locks."

A force-killed generation job must not permanently block subsequent runs. ProjectKeyLock must self-heal stale locks: _is_stale() treats a lock as abandoned if its age exceeds stale_after_seconds or the PID recorded in it no longer corresponds to a running process (checked via ctypes/OpenProcess on Windows, os.kill(pid, 0) on POSIX) — a bare os.kill(pid, 0) must never be used on Windows, where it would call TerminateProcess instead of merely checking liveness. PARTIAL, not fully verified this pass: RUNBOOK.md documents both the time-based and PID-liveness checks as currently implemented, but this restructuring did not independently re-read doxygen_lock.py's source to confirm both branches — flagged for a follow-up spot-check before citing this as fully IMPLEMENTED.

REQ-NFN-06​

Golden-Master Fixture Protection

  • Status: IMPLEMENTED
  • Introduced: v2.0
  • Category: Operability
  • Evidence: engine/tests/test_integration_scripts.py::test_prepare_baseline_mock_suite; RUNBOOK.md §4. Fixed 2026-08-13.

A baseline generator must never silently mutate tracked golden-master fixtures. prepare_baseline.py now requires an explicit --baseline-dir redirect when invoked from the test suite (a normal pytest run uses tmp_path and never touches the tracked tree); invoked directly without --baseline-dir, it still writes straight into the real tracked baseline/ tree by design — the intentional path for deliberately regenerating the golden master, not an accidental one.

REQ-NFN-07​

CI Survives Self-Hosted Runner Faults

  • Status: IMPLEMENTED
  • Introduced: v2.0
  • Category: Operability
  • Evidence: project incident record (project_selfhosted_runner_network_incident.md, session memory — not re-verified against workflow YAML in this pass).

CI must survive self-hosted runner faults: automatic retry on mid-job communication loss / RPC failure; no orphaned VBoxHeadless processes left holding resources. Four fixes shipped through 2026-08-11 (a VBoxHeadless zombie-process fix, and an auto-retry mechanism for mid-job comms-loss/RPC failures).

REQ-NFN-08​

No Temp-Directory Leakage

  • Status: IMPLEMENTED
  • Introduced: v2.0
  • Category: Operability
  • Evidence: project incident record — a regression that leaked 4,920 directories / 26.4 GB before the fix (analysis helpers that never called cleanup()); not re-verified against current source in this pass.

Every collector/analysis helper must call cleanup() on all code paths, including error paths — the regression this closes leaked thousands of temp directories over time because cleanup was only called on the success path.

REQ-NFN-09​

Credential Hygiene

  • Status: UNIMPLEMENTED (orphan cleanup is open work; the rotation procedure itself is documented and followed)
  • Introduced: v3.0
  • Category: Operability
  • Evidence: RUNBOOK.md §2 — verified: CF_API_TOKEN, CF_ACCOUNT_ID, ENGINE_PAT, PIPELINE_GITHUB_TOKEN are named there as currently registered on the Pipeline repo and unused by any of its three workflows.

Submodule checkout uses per-repo deploy keys with a documented rotation procedure; secrets must be rotatable without downtime; no orphaned secrets should remain registered. The four named secrets above are currently registered and unused here — CF_API_TOKEN/CF_ACCOUNT_ID remain live and in use by other repositories' own deploy workflows and must not be revoked outright, but their presence on this repo specifically is dead weight; ENGINE_PAT/PIPELINE_GITHUB_TOKEN are fully dead everywhere. Per RUNBOOK.md, cleaning these up is tracked as a follow-up, not yet done.

REQ-NFN-10​

Markdown Quality Gate

  • Status: IMPLEMENTED
  • Introduced: v2.0
  • Category: Operability
  • Evidence: design-docs/.github/workflows/deploy.yml:111 — verified: npx markdownlint-cli2@0.23.0 "docs/**/*.md".

A Markdown quality gate (markdownlint-cli2, zero errors) must run across all five content repositories (Pipeline, engine, design-docs, user-docs, ude-promotion). Delivered 2026-08-03 per .antigravitycli/planned.md §7.3 tracking; this pass verified only the design-docs workflow directly.