refactor(help): shim manifest/staleness/freshness; add rag adapter

CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to `attune-help` are documented here.
 
+## 0.11.0 — 2026-05-08
+
+### Changed (deprecation)
+
+- **`attune_help.manifest`, `attune_help.staleness`, and
+  `attune_help.freshness` (+ `attune_help.freshness.symbols`) moved to
+  `attune_author.*`.** The original modules now ship as thin re-export
+  shims that emit `DeprecationWarning` on import. Update your imports:
+
+      # before
+      from attune_help.manifest import Feature, FeatureManifest
+
+      # after
+      from attune_author.manifest import Feature, FeatureManifest
+
+  The shims will be **removed in the next minor release of
+  attune-help (target: 2026-07-07)**. After that release, importing
+  from the old paths raises `ImportError`.
+
+- The package no longer re-exports manifest / staleness symbols from
+  its top-level (`attune_help.Feature`, `attune_help.StalenessReport`,
+  …). Import them from `attune_author` directly. A plain
+  `import attune_help` is now warning-free during the deprecation
+  window.
+
+### Added
+
+- **`attune_help.adapters.rag.AttuneHelpAdapter`** — implements
+  `attune_rag.corpus.help_adapter.HelpCorpusAdapter` so attune-rag's
+  `AttuneHelpCorpus` can be built without a dynamic import of
+  attune-help. Pairs with `attune-rag` 0.1.10's typed adapter
+  protocol. Closes finding **#1** (ADR-002 violation) of the
+  2026-05-07 architecture review.
+
+### Dependencies
+
+- New required: `attune-author>=0.7.0`. Transitional — required only
+  while the deprecated shims live. Removed together with the shims
+  on 2026-07-07.
+
 ## 0.10.0 — 2026-04-30
 
 ### Added

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "attune-help"
-version = "0.10.2"
+version = "0.11.0"
 description = "Lightweight help runtime with progressive depth and audience adaptation."
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.10"
@@ -27,6 +27,13 @@ classifiers = [
 ]
 dependencies = [
     "python-frontmatter>=1.0.0",
+    # Transitional: manifest/staleness/freshness moved to attune-author
+    # in 0.11.0. ``attune_help.manifest``/``staleness``/``freshness``
+    # are deprecated shims that re-export from attune-author. Required
+    # so existing imports keep working through the deprecation window.
+    # Drop this dep when the shims are removed (target 2026-07-07) and
+    # restore tech.md's zero-required-deps constraint.
+    "attune-author>=0.7.0",
 ]
 
 [project.optional-dependencies]

src/attune_help/__init__.py

@@ -14,28 +14,7 @@
     PopulatedTemplate,
     TemplateContext,
 )
-from attune_help.manifest import (
-    Feature,
-    FeatureManifest,
-    Manifest,
-    is_safe_feature_name,
-    load_manifest,
-    match_files_to_features,
-    resolve_topic,
-    save_manifest,
-    slugify,
-)
 from attune_help.preamble import get_preamble  # noqa: F401
-from attune_help.staleness import (
-    DocStaleness,
-    FeatureStaleness,
-    StalenessReport,
-    build_doc_footer,
-    check_staleness,
-    compute_semantic_hash,
-    compute_source_hash,
-    parse_doc_footer,
-)
 from attune_help.storage import LocalFileStorage, SessionStorage
 
 __all__ = [
@@ -48,27 +27,15 @@
     "TemplateContext",
     "get_demo_path",
     "get_preamble",
-    # Manifest
-    "Feature",
-    "FeatureManifest",
-    "Manifest",
-    "is_safe_feature_name",
-    "load_manifest",
-    "match_files_to_features",
-    "resolve_topic",
-    "save_manifest",
-    "slugify",
-    # Staleness
-    "DocStaleness",
-    "FeatureStaleness",
-    "StalenessReport",
-    "build_doc_footer",
-    "check_staleness",
-    "compute_semantic_hash",
-    "compute_source_hash",
-    "parse_doc_footer",
 ]
 
+# Manifest, staleness, and freshness moved to attune-author. Importing
+# them through ``attune_help.*`` still works via the deprecated shims
+# in this package (they emit ``DeprecationWarning`` on first import).
+# The shims are not eagerly imported here so that a plain
+# ``import attune_help`` stays warning-free during the deprecation
+# window.
+
 try:
     from importlib.metadata import version
 

src/attune_help/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Adapters that expose attune-help's bundled corpus to other packages.
+
+The :mod:`attune_help.adapters.rag` module implements
+:class:`attune_rag.corpus.help_adapter.HelpCorpusAdapter` so attune-rag
+can build an :class:`attune_rag.corpus.attune_help.AttuneHelpCorpus`
+without ever importing attune-help directly.
+"""

src/attune_help/adapters/rag.py

@@ -0,0 +1,39 @@
+"""Adapter exposing attune-help's bundled corpus to attune-rag.
+
+attune-rag declares a small structural ``HelpCorpusAdapter`` protocol
+(``templates_root: Path``, ``version: str``). This module ships an
+implementation so attune-rag's corpus factory can build the
+``AttuneHelpCorpus`` without dynamically importing attune-help. The
+direction of the dependency edge inverts: attune-rag knows nothing of
+attune-help; attune-help imports rag's protocol and conforms to it.
+
+Usage::
+
+    from attune_help.adapters.rag import AttuneHelpAdapter
+    from attune_rag.corpus.attune_help import AttuneHelpCorpus
+
+    corpus = AttuneHelpCorpus(adapter=AttuneHelpAdapter())
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from attune_help import __version__ as _help_version
+
+_BUNDLED_TEMPLATES = Path(__file__).resolve().parent.parent / "templates"
+
+
+@dataclass(frozen=True)
+class AttuneHelpAdapter:
+    """attune-help's default :class:`HelpCorpusAdapter` implementation.
+
+    By default points at the bundled templates directory and reports
+    the installed package version. Both fields are overridable so
+    tests and downstream callers can supply their own corpus root or
+    version string without subclassing.
+    """
+
+    templates_root: Path = field(default=_BUNDLED_TEMPLATES)
+    version: str = field(default=_help_version)

src/attune_help/freshness/__init__.py

@@ -1,14 +1,28 @@
-"""Symbol extraction for semantic-freshness staleness detection (Phase 1).
-
-Known limitation — re-export shims:
-    Pure re-export modules (``from pkg import *`` with no definitions) produce
-    zero symbols. If a feature's ``files:`` list includes only shim files,
-    ``compute_semantic_hash`` will return SHA-256("") for that feature.
-    Mitigation: list the upstream implementation file alongside the shim in
-    ``features.yaml``, or use Option B (per-symbol frontmatter) in a future
-    release. Tracked for Phase 2 evaluation.
+"""DEPRECATED: moved to :mod:`attune_author.freshness`.
+
+Re-exported here for one minor release of attune-help so existing
+imports keep working while consumers migrate. The shim emits
+:class:`DeprecationWarning` on import.
+
+Update your imports::
+
+    from attune_author.freshness import SymbolExtractor, SymbolRecord
+
+This shim will be removed in the next minor release of attune-help
+(target: 2026-07-07 — see CHANGELOG).
 """
 
-from attune_help.freshness.symbols import SymbolExtractor, SymbolRecord
+from __future__ import annotations
+
+import warnings
+
+from attune_author.freshness import SymbolExtractor, SymbolRecord
 
 __all__ = ["SymbolExtractor", "SymbolRecord"]
+
+warnings.warn(
+    "attune_help.freshness is deprecated; import from attune_author.freshness. "
+    "This shim will be removed in the next minor release of attune-help.",
+    DeprecationWarning,
+    stacklevel=2,
+)