orchestrata_ultimate.factory.dor_procedure.rulings

Reference › orchestrata_ultimate › factory › dor_procedure › rulings

rulings supplies the ruling ids for the rulings checklist of the DoR procedure (step 6.3 of the workflow-improvements plan). Ids are derived, never typed into the module: rulings_dir resolves the rulings canon directory by reusing the directory resolution of scripts.rulings_lint, including its environment override, so the two never drift, and list_ruling_ids returns the sorted RUL-NNN ids found in the git-backed markdown files there. A running wiki server is never needed. The import from scripts is lazy, confined to rulings_dir, because a module-level import would make the module unimportable when only src is on the path. validate and the design authority import it; tests include tests/factory/test_dor_validate.py.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/factory/dor_procedure/rulings.py

"""Ruling-id catalogue for the DoR procedure's rulings checklist (Step 6.3,
``plans/workflow-improvements-plan.md``).

Ruling ids are DERIVED, never hand-typed into this module: read straight off
the same filesystem canon ``scripts/rulings_lint.py`` reads — git-backed
markdown at ``~/workspace/knowledge-wiki/rulings/`` (``RUL-*.md``), never via
``wiki get`` — a live Wiki.js server is never a dependency (Phase 0 ruling).
This module reuses ``rulings_lint.py``'s directory resolution rather than
duplicating the ``RULINGS_DIR`` env-override logic, so the two paths never
drift apart.

NOTE: the ``from scripts...`` import is LAZY (confined to :func:`rulings_dir`)
for the same reason as ``factory/contracts/trace_validation.py`` and
``factory/evidence/mutation.py`` -- a module-level import would make this src
module unimportable unless the repo root happens to be on ``sys.path``, which
plain ``PYTHONPATH=<repo>/src`` does not guarantee.
"""

from __future__ import annotations

import re
from pathlib import Path

_RUL_ID_RE = re.compile(r"^(RUL-\d+)")


def rulings_dir() -> Path:
    """Resolve the rulings canon directory.

    Identical resolution to ``scripts/rulings_lint.py``'s
    ``_default_rulings_dir`` (reused directly, never duplicated): the
    ``RULINGS_DIR`` env var if set (read at call time, per RUL-003), else
    ``~/workspace/knowledge-wiki/rulings``.
    """
    from scripts.rulings_lint import _default_rulings_dir

    return _default_rulings_dir()


def list_ruling_ids(directory: Path | None = None) -> tuple[str, ...]:
    """Every ``RUL-NNN`` id declared in the canon, sorted.

    Returns an empty tuple when the canon directory does not exist — a
    machine without a ``knowledge-wiki`` clone must not go false-red here,
    the same "missing RULINGS_DIR is a SKIP, not a FAIL" honesty rule
    ``rulings_lint.py`` applies to its own gate.
    """
    target = directory if directory is not None else rulings_dir()
    if not target.exists():
        return ()
    ids: list[str] = []
    for path in sorted(target.glob("RUL-*.md")):
        m = _RUL_ID_RE.match(path.stem)
        if m:
            ids.append(m.group(1))
    return tuple(ids)