@ahmed-g-gad/apothem 0.1.1

package/src/apothem/lib/plan_tiers.py

@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: MIT
+
+"""Three-tier scalability classification for the ``/plan-<stage>`` pipeline.
+
+Implements the small / medium / large tier framework that governs a plan
+suite's validation cadence, indexing, and decomposition as it scales from a
+few dozen phases to thousands of tasks. The classifier is the executable basis
+the planning-pipeline commands consult at every stage; the prose framework it
+mirrors lives at ``rules/canonical-layout-reporting-tiers.md`` §7.
+
+The module is intentionally pure — classification and required-infrastructure
+enumeration take counts and return values, with no filesystem side effects — so
+the tier-transition behavior is deterministic and directly testable (the
+500-phase medium→large smoke test exercises these functions).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Tier(str, Enum):
+    """A plan suite's scalability tier.
+
+    The string values are the canonical tier names used in suite metadata and
+    in the ``/plan`` command's tier-classification reporting.
+    """
+
+    SMALL = "small"
+    MEDIUM = "medium"
+    LARGE = "large"
+
+
+# Boundary thresholds per ``rules/canonical-layout-reporting-tiers.md`` §7.1.
+# A suite is medium at or above the lower boundary and large at or above the
+# upper boundary, evaluated independently on the phase-count and spec-count
+# dimensions; the more demanding dimension governs the suite's tier.
+SMALL_MEDIUM_PHASE_BOUNDARY = 50
+MEDIUM_LARGE_PHASE_BOUNDARY = 500
+SMALL_MEDIUM_SPEC_BOUNDARY = 100
+MEDIUM_LARGE_SPEC_BOUNDARY = 1000
+
+# A count within this fraction of a boundary is borderline and routes the
+# tier classification through structured inquiry rather than a silent pick.
+BORDERLINE_FRACTION = 0.10
+
+# Ordinal rank for tier comparison — the governing tier is the higher rank.
+_TIER_RANK: dict[Tier, int] = {Tier.SMALL: 0, Tier.MEDIUM: 1, Tier.LARGE: 2}
+
+
+def _dimension_tier(count: int, lower: int, upper: int) -> Tier:
+    """Classify a single dimension (phases or specs) against its boundaries.
+
+    Args:
+        count: The dimension's count (must be non-negative).
+        lower: The small→medium boundary for this dimension.
+        upper: The medium→large boundary for this dimension.
+
+    Returns:
+        ``Tier.SMALL`` below ``lower``, ``Tier.MEDIUM`` in ``[lower, upper)``,
+        ``Tier.LARGE`` at or above ``upper``.
+
+    Raises:
+        ValueError: If ``count`` is negative.
+    """
+    if count < 0:
+        raise ValueError(f"count must be non-negative, got {count}")
+    if count >= upper:
+        return Tier.LARGE
+    if count >= lower:
+        return Tier.MEDIUM
+    return Tier.SMALL
+
+
+def classify_tier(phase_count: int, spec_count: int) -> Tier:
+    """Classify a plan suite's scalability tier from its phase and spec counts.
+
+    The governing tier is the higher of the phase-dimension tier and the
+    spec-dimension tier: a suite with 40 phases but 1200 spec requirements is
+    ``large`` because its spec dimension demands large-tier infrastructure even
+    though its phase dimension alone would read ``small``.
+
+    Args:
+        phase_count: The number of phases in the suite (non-negative).
+        spec_count: The number of spec requirements in the suite (non-negative).
+
+    Returns:
+        The governing :class:`Tier`.
+
+    Raises:
+        ValueError: If either count is negative.
+    """
+    phase_tier = _dimension_tier(
+        phase_count, SMALL_MEDIUM_PHASE_BOUNDARY, MEDIUM_LARGE_PHASE_BOUNDARY
+    )
+    spec_tier = _dimension_tier(
+        spec_count, SMALL_MEDIUM_SPEC_BOUNDARY, MEDIUM_LARGE_SPEC_BOUNDARY
+    )
+    return phase_tier if _TIER_RANK[phase_tier] >= _TIER_RANK[spec_tier] else spec_tier
+
+
+def _within_borderline(count: int, boundary: int) -> bool:
+    """Return ``True`` when ``count`` is within ``BORDERLINE_FRACTION`` of ``boundary``."""
+    margin = boundary * BORDERLINE_FRACTION
+    return boundary - margin <= count <= boundary + margin
+
+
+def is_borderline(phase_count: int, spec_count: int) -> bool:
+    """Report whether a suite sits within ±10% of any tier boundary.
+
+    A borderline suite's tier is underdetermined by the counts alone; the
+    ``/plan`` command routes such a suite through a tier-classification
+    structured inquiry rather than silently picking a tier.
+
+    Args:
+        phase_count: The number of phases in the suite (non-negative).
+        spec_count: The number of spec requirements in the suite (non-negative).
+
+    Returns:
+        ``True`` when either count is within ±10% of either of its dimension's
+        two boundaries.
+    """
+    return any(
+        (
+            _within_borderline(phase_count, SMALL_MEDIUM_PHASE_BOUNDARY),
+            _within_borderline(phase_count, MEDIUM_LARGE_PHASE_BOUNDARY),
+            _within_borderline(spec_count, SMALL_MEDIUM_SPEC_BOUNDARY),
+            _within_borderline(spec_count, MEDIUM_LARGE_SPEC_BOUNDARY),
+        )
+    )
+
+
+# Drift-prevention infrastructure each tier requires, per §7.2. Each higher
+# tier is a strict superset of the tier below it, so a transition's delta is the
+# set difference between the new and old tiers' infrastructure.
+_TIER_INFRASTRUCTURE: dict[Tier, frozenset[str]] = {
+    Tier.SMALL: frozenset(
+        {
+            "trace-matrix-narrative",  # narrative trace table in PLAN-NOTES.md
+            "per-phase-report",  # REPORT.md per phase
+        }
+    ),
+    Tier.MEDIUM: frozenset(
+        {
+            "trace-matrix-narrative",
+            "per-phase-report",
+            "master-index",  # MASTER-INDEX.md suite-root index
+            "stable-ids",  # R-NNNN requirement / P-NN phase IDs
+            "trace-matrix-file",  # materialized TRACE-MATRIX.md
+            "phase-rollup-report",  # rollup per 5-20 phase group
+        }
+    ),
+    Tier.LARGE: frozenset(
+        {
+            "trace-matrix-narrative",
+            "per-phase-report",
+            "master-index",
+            "stable-ids",
+            "trace-matrix-file",
+            "phase-rollup-report",
+            "sub-suite-federation",  # parent + child suite decomposition
+            "suite-rollup-report",  # federation aggregates child rollups
+        }
+    ),
+}
+
+
+def tier_infrastructure(tier: Tier) -> frozenset[str]:
+    """Return the drift-prevention infrastructure a tier requires.
+
+    Args:
+        tier: The suite's tier.
+
+    Returns:
+        The frozen set of infrastructure-mechanism identifiers governing the
+        tier per ``rules/canonical-layout-reporting-tiers.md`` §7.2.
+    """
+    return _TIER_INFRASTRUCTURE[tier]
+
+
+def tier_transition_infrastructure(old: Tier, new: Tier) -> frozenset[str]:
+    """Enumerate the infrastructure a tier transition must materialize.
+
+    When a suite crosses a tier boundary (e.g. its 500th phase pushes it from
+    ``medium`` to ``large``), the ``/plan`` command materializes the new tier's
+    additional infrastructure in the same change-set so a 501-phase suite never
+    exists without its large-tier surfaces. The delta is the infrastructure
+    present in ``new`` but absent from ``old``.
+
+    Args:
+        old: The suite's tier before the transition.
+        new: The suite's tier after the transition.
+
+    Returns:
+        The set of infrastructure-mechanism identifiers the transition must
+        newly materialize. Empty when ``new`` does not exceed ``old``.
+    """
+    if _TIER_RANK[new] <= _TIER_RANK[old]:
+        return frozenset()
+    return _TIER_INFRASTRUCTURE[new] - _TIER_INFRASTRUCTURE[old]

package/src/apothem/lib/plugin_bootstrap.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: MIT
+
+"""Self-contained engine-import bootstrap for the bundled plugin tree.
+
+Why this module exists. The plugin-first distribution ships the apothem
+engine as a bundled copy under ``<plugin_root>/lib/apothem``: the bundled
+plugin tree imports the engine and its vendored dependencies directly
+from the tree, and no package installation occurs at any point. A harness
+that loads the plugin needs ``import apothem`` (and the alias ``import
+apothem_lib``) plus every vendored third-party dependency to resolve from
+the plugin tree. This module mutates ``sys.path`` so those imports
+succeed, and does so idempotently — calling it once per session boundary,
+or twice by accident, leaves ``sys.path`` in the same correct state.
+
+The self-containment invariant. Vendored dependencies under
+``lib/apothem/_vendor`` take precedence over any system-installed copy.
+``bootstrap_syspath`` prepends the vendor directory ahead of ``sys.path``
+so the bundled versions win the import resolution race.
+
+Public API. ``bootstrap_syspath`` performs the idempotent mutation;
+``bootstrapped_root`` returns the last root bootstrapped for diagnostics;
+``PluginBootstrapError`` is raised on a malformed plugin tree (missing
+``plugin_root`` or missing ``lib/``) — failing loud rather than silently
+importing a stale system copy.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+__all__ = [
+    "PluginBootstrapError",
+    "bootstrap_syspath",
+    "bootstrapped_root",
+]
+
+
+class PluginBootstrapError(RuntimeError):
+    """Raised when the plugin tree is malformed and cannot be bootstrapped.
+
+    The error message names the missing path so the operator can diagnose
+    a malformed plugin without inspecting the bootstrap logic.
+    """
+
+
+# Module-level registry of already-bootstrapped roots. Membership here
+# guards against duplicate sys.path entries on repeated calls; the
+# resolved (absolute) path is the canonical key so two spellings of the
+# same root collapse to one entry.
+_BOOTSTRAPPED_ROOTS: set[Path] = set()
+
+# Diagnostics handle: the last root passed to bootstrap_syspath.
+_LAST_BOOTSTRAPPED_ROOT: Path | None = None
+
+
+def bootstrap_syspath(plugin_root: Path) -> None:
+    """Idempotently prepend the bundled engine to ``sys.path``.
+
+    After this call, ``import apothem`` and ``import apothem_lib`` resolve
+    from ``<plugin_root>/lib`` and any vendored third-party dependency
+    resolves from ``<plugin_root>/lib/apothem/_vendor`` ahead of a
+    system-installed copy — the plugin tree is self-contained.
+
+    Pre-conditions:
+        ``plugin_root`` exists and contains a ``lib/`` directory.
+
+    Post-conditions:
+        ``str(lib_dir)`` is present at ``sys.path[0]``. When the vendor
+        directory exists, ``str(vendor_dir)`` is present at ``sys.path[0]``
+        ahead of ``lib_dir`` (vendor precedence). Repeated calls add no
+        duplicate entries.
+
+    Args:
+        plugin_root: The plugin tree root containing ``.claude-plugin/``
+            and ``lib/``.
+
+    Raises:
+        PluginBootstrapError: If ``plugin_root`` does not exist, or if it
+            has no ``lib/`` directory. The message names the missing path.
+    """
+    global _LAST_BOOTSTRAPPED_ROOT
+
+    resolved_root = plugin_root.resolve()
+
+    if not resolved_root.exists():
+        raise PluginBootstrapError(f"plugin_root does not exist: {resolved_root}")
+
+    lib_dir = resolved_root / "lib"
+    if not lib_dir.is_dir():
+        raise PluginBootstrapError(f"plugin_root has no lib/ directory: {lib_dir}")
+
+    _LAST_BOOTSTRAPPED_ROOT = resolved_root
+
+    # Idempotency short-circuit: a root already bootstrapped needs no
+    # further sys.path mutation. The path-membership checks below are a
+    # second line of defense against duplicates introduced out-of-band.
+    if resolved_root in _BOOTSTRAPPED_ROOTS:
+        return
+
+    vendor_dir = lib_dir / "apothem" / "_vendor"
+
+    # Prepend lib_dir first so it lands at sys.path[0]; the vendor
+    # prepend below then displaces it to sys.path[1], yielding the
+    # vendor-before-lib ordering the self-containment invariant requires.
+    _prepend_unique(str(lib_dir))
+
+    if vendor_dir.is_dir():
+        _prepend_unique(str(vendor_dir))
+
+    _BOOTSTRAPPED_ROOTS.add(resolved_root)
+
+
+def bootstrapped_root() -> Path | None:
+    """Return the last root passed to ``bootstrap_syspath``.
+
+    Returns:
+        The resolved path of the most recently bootstrapped plugin root,
+        or ``None`` if ``bootstrap_syspath`` has not yet succeeded past
+        its validation gate.
+    """
+    return _LAST_BOOTSTRAPPED_ROOT
+
+
+def _prepend_unique(entry: str) -> None:
+    """Prepend ``entry`` to ``sys.path[0]`` only if not already present.
+
+    Args:
+        entry: The ``sys.path`` entry to prepend.
+    """
+    if entry not in sys.path:
+        sys.path.insert(0, entry)