raise-cli 3.0.0a6__tar.gz → 3.1.0a3__tar.gz

{raise_cli-3.0.0a6 → raise_cli-3.1.0a3}/.gitignore

@@ -1,3 +1,6 @@
+# Node.js
+node_modules/
+
 # IDE / editor directories
 .specstory/
 .cursor/
@@ -62,6 +65,7 @@ dev/output/
 
 # RaiSE global SQLite DB (per-machine, not shared)
 .raise/rai/raise.db
+.raise/raise.db
 
 # RaiSE mission migration artifacts
 .raise/rai/missions/*.migrated
@@ -99,8 +103,8 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
+/lib/
+/lib64/
 parts/
 sdist/
 var/
@@ -149,6 +153,7 @@ dmypy.json
 .env
 .env.*
 !.env.example
+!.env.production
 *.pem
 *.key
 .pypirc
@@ -194,3 +199,16 @@ dev/transcripts/
 .worktrees/
 .venv
 .venv
+work/debug/
+
+# Playwright E2E auth state (contains session cookies)
+packages/raise-admin/e2e/.auth/
+# Playwright test results
+packages/raise-admin/test-results/
+packages/raise-admin/playwright-report/
+
+# Forge raise-jira app — generated files
+forge/raise-jira/static/raise-app/package-lock.json
+forge/raise-jira/static/raise-app/pnpm-workspace.yaml
+packages/raise-cli/.raise/sync/backlog-dead-letter.jsonl
+package-lock.json

{raise_cli-3.0.0a6 → raise_cli-3.1.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: raise-cli
-Version: 3.0.0a6
+Version: 3.1.0a3
 Summary: RaiSE CLI - Reliable AI Software Engineering governance framework
 Project-URL: Homepage, https://raiseframework.ai
 Project-URL: Documentation, https://docs.raiseframework.ai
@@ -20,6 +20,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.12
 Requires-Dist: atlassian-python-api>=3.41.0
 Requires-Dist: httpx<1.0,>=0.27.0
+Requires-Dist: kuzu>=0.11.0
 Requires-Dist: logfire-api>=4.0
 Requires-Dist: markdown>=3.6
 Requires-Dist: mcp<2,>=1.26
@@ -28,7 +29,7 @@ Requires-Dist: pydantic-settings>=2.2.0
 Requires-Dist: pydantic>=2.6.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pyyaml>=6.0.1
-Requires-Dist: raise-core>=3.0.0a3
+Requires-Dist: raise-core>=3.0.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: tree-sitter-javascript>=0.25.0
 Requires-Dist: tree-sitter-language-pack>=0.13.0
@@ -41,6 +42,9 @@ Provides-Extra: atlassian
 Provides-Extra: confluence
 Provides-Extra: csharp
 Requires-Dist: tree-sitter-c-sharp>=0.23.1; extra == 'csharp'
+Provides-Extra: eval
+Requires-Dist: ranx<0.4,>=0.3.20; extra == 'eval'
+Requires-Dist: scipy>=1.10; extra == 'eval'
 Provides-Extra: go
 Requires-Dist: tree-sitter-go>=0.25.0; extra == 'go'
 Provides-Extra: hud
@@ -99,7 +103,7 @@ Windows (PowerShell):
 
 ```powershell
 cd your-project
-irm https://docs.raiseframework.ai/install.ps1 | iex
+powershell -ExecutionPolicy ByPass -c "irm https://docs.raiseframework.ai/install.ps1 | iex"
 ```
 
 ### Manual install

{raise_cli-3.0.0a6 → raise_cli-3.1.0a3}/README.md

@@ -43,7 +43,7 @@ Windows (PowerShell):
 
 ```powershell
 cd your-project
-irm https://docs.raiseframework.ai/install.ps1 | iex
+powershell -ExecutionPolicy ByPass -c "irm https://docs.raiseframework.ai/install.ps1 | iex"
 ```
 
 ### Manual install

{raise_cli-3.0.0a6 → raise_cli-3.1.0a3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "raise-cli"
-version = "3.0.0a6"
+version = "3.1.0a3"
 description = "RaiSE CLI - Reliable AI Software Engineering governance framework"
 authors = [
     {name = "Emilio Osorio", email = "emilio@humansys.ai"}
@@ -21,7 +21,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "raise-core>=3.0.0a3",
+    "raise-core>=3.0.0",
     "typer>=0.12.0",
     "rich>=13.7.0",
     "pydantic>=2.6.0",
@@ -40,6 +40,7 @@ dependencies = [
     "mcp>=1.26,<2",
     "markdown>=3.6",
     "atlassian-python-api>=3.41.0",
+    "kuzu>=0.11.0",
 ]
 
 [project.optional-dependencies]
@@ -60,6 +61,10 @@ go = [
 hud = [
     "textual>=0.86,<1.0",
 ]
+eval = [
+    "ranx>=0.3.20,<0.4",
+    "scipy>=1.10",
+]
 # Backwards-compat aliases — atlassian-python-api is now installed by default (RAISE-1912).
 atlassian = []
 confluence = []
@@ -89,7 +94,7 @@ glossary = "raise_cli.governance.parsers.glossary:GlossaryParser"
 [project.entry-points."rai.hooks"]
 telemetry = "raise_cli.hooks.builtin.telemetry:TelemetryHook"
 gate-bridge = "raise_cli.hooks.builtin.gate_bridge:GateBridgeHook"
-work-events = "raise_cli.work_events.emitter:ServerEmitHook"
+graph-auto-update = "raise_cli.hooks.builtin.graph_update:GraphAutoUpdateHook"
 
 [project.entry-points."rai.gates"]
 tests = "raise_cli.gates.builtin.tests:TestGate"
@@ -107,6 +112,7 @@ drift-auth-fan-out = "raise_cli.gates.drift.auth_fan_out:AuthorizationFanOutGate
 ar-story = "raise_cli.gates.ar.story_gate:ArchitectureReviewGate"
 ar-bugfix = "raise_cli.gates.ar.bugfix_gate:BugfixArchitectureReviewGate"
 epic-close-drift = "raise_cli.gates.drift.epic_close:EpicCloseGate"
+eval = "raise_cli.eval.gate:EvalGate"
 
 [project.entry-points."rai.doctor.checks"]
 environment = "raise_cli.doctor.checks.environment:EnvironmentCheck"
@@ -114,6 +120,7 @@ project = "raise_cli.doctor.checks.project:ProjectCheck"
 developer = "raise_cli.doctor.checks.developer:DeveloperCheck"
 adapters = "raise_cli.doctor.checks.adapters:AdapterDoctorCheck"
 runtimes = "raise_cli.doctor.checks.runtimes:RuntimesCheck"
+skills = "raise_cli.doctor.checks.skills:SkillCommandReferenceCheck"
 
 [project.entry-points."rai.adapters.pm"]
 filesystem = "raise_cli.adapters.filesystem:FilesystemPMAdapter"

{raise_cli-3.0.0a6 → raise_cli-3.1.0a3}/src/raise_cli/_agent_session.py

@@ -3,6 +3,7 @@
 Resolution order:
 1. RAISE_AGENT_SESSION_ID (explicit, set by any runtime adapter)
 2. RAISE_CC_SESSION_ID (Claude Code backward compat)
+2.5. CLAUDE_CODE_SESSION_ID (CC-native; always injected into Bash tool env)
 3. CC port discovery (CLAUDE_CODE_SSE_PORT → cc.port, unambiguous match only)
 4. Terminal bindings (PPID ancestry → _terminal_bindings.json)
 """
@@ -14,6 +15,7 @@ import os
 from pathlib import Path
 
 _SESSIONS_DIR = Path(".raise") / "rai" / "sessions"
+_CLAUDE_WORKTREES_DIR = Path(".claude") / "worktrees"
 
 
 def discover_agent_session_id() -> str | None:
@@ -30,6 +32,10 @@ def discover_agent_session_id() -> str | None:
     if cc_sid:
         return cc_sid
 
+    native_sid = os.environ.get("CLAUDE_CODE_SESSION_ID", "").strip()
+    if native_sid:
+        return native_sid
+
     port_sid = _discover_via_cc_port()
     if port_sid:
         return port_sid
@@ -65,6 +71,9 @@ def discover_agent_runtime() -> str:
     if os.environ.get("RAISE_CC_SESSION_ID", "").strip():
         return "claude_code"
 
+    if os.environ.get("CLAUDE_CODE_SESSION_ID", "").strip():
+        return "claude_code"
+
     if _discover_via_cc_port():
         return "claude_code"
 
@@ -86,19 +95,34 @@ def _discover_via_cc_port() -> str | None:
     port = os.environ.get("CLAUDE_CODE_SSE_PORT", "").strip()
     if not port:
         return None
-    sessions_dir = Path.cwd() / _SESSIONS_DIR
-    if not sessions_dir.exists():
-        return None
     matches: list[str] = []
-    for sess_dir in sessions_dir.iterdir():
-        if not sess_dir.is_dir():
-            continue
-        port_file = sess_dir / "cc.port"
-        if port_file.exists() and port_file.read_text().strip() == port:
-            matches.append(sess_dir.name)
+    for sessions_dir in _candidate_session_dirs(Path.cwd()):
+        for sess_dir in sessions_dir.iterdir():
+            if not sess_dir.is_dir():
+                continue
+            port_file = sess_dir / "cc.port"
+            if port_file.exists() and port_file.read_text().strip() == port:
+                matches.append(sess_dir.name)
     return matches[0] if len(matches) == 1 else None
 
 
+def _candidate_session_dirs(root: Path) -> list[Path]:
+    """Return session directories relevant from an MCP server CWD."""
+    candidates: list[Path] = []
+    local_sessions = root / _SESSIONS_DIR
+    if local_sessions.exists():
+        candidates.append(local_sessions)
+
+    worktrees_root = root / _CLAUDE_WORKTREES_DIR
+    if worktrees_root.exists():
+        for worktree in sorted(worktrees_root.iterdir()):
+            sessions_dir = worktree / _SESSIONS_DIR
+            if sessions_dir.exists():
+                candidates.append(sessions_dir)
+
+    return candidates
+
+
 def _get_parent_pid(pid: int) -> int | None:
     """Return the parent PID of *pid* via /proc (Linux only)."""
     try:

{raise_cli-3.0.0a6 → raise_cli-3.1.0a3}/src/raise_cli/adapters/composite_docs.py

@@ -12,9 +12,10 @@ S1700.6 — Retrofit with PendingOpsLog:
 - Before each publish, attempt best-effort flush of existing pending ops.
 - `pending_ops=None` preserves pre-S1700.6 behavior (backward compat).
 
-S20.2 — Sync manifest:
-- After each successful remote publish, update .raise/sync/docs-manifest.yaml.
-- `project_root=None` skips manifest write (backward compat).
+RAISE-5618 — Docs sync state in SQLite:
+- After each successful remote publish, persist local_path → remote_id/url/updated_at in SQLite.
+- Lazy migration imports existing .raise/sync/docs-manifest.yaml entries on first write.
+- `project_root=None` skips sync state write (backward compat).
 
 RAISE-1051 (S1051.7) | RAISE-1795 (S1700.6) | RAISE-3414 (S20.2)
 """
@@ -40,6 +41,54 @@ from raise_cli.adapters.pending_ops import PendingOpsLog
 logger = logging.getLogger(__name__)
 
 
+def migrate_docs_yaml_to_sqlite(project_root: Path) -> None:
+    """Lazy one-time migration: import valid YAML entries to SQLite, skip stale paths.
+
+    No-op when the YAML manifest does not exist or SQLite already has entries.
+    """
+    manifest_path = project_root / ".raise" / "sync" / "docs-manifest.yaml"
+    if not manifest_path.exists():
+        return
+    from raise_cli.storage.connection import get_project_db, get_project_id
+    from raise_cli.storage.schema import create_all
+
+    db = get_project_db(project_root)
+    create_all(db)
+    pid = get_project_id(project_root)
+    count = db.execute(
+        "SELECT COUNT(*) FROM docs_sync WHERE project_id = ?", (pid,)
+    ).fetchone()[0]
+    if count > 0:
+        db.close()
+        return
+    try:
+        data: dict[str, Any] = (
+            yaml.safe_load(manifest_path.read_text(encoding="utf-8")) or {}
+        )
+    except Exception:
+        db.close()
+        return
+    for key, meta in data.items():
+        if not isinstance(meta, dict):
+            continue
+        if not Path(key).exists():
+            continue
+        db.execute(
+            "INSERT OR IGNORE INTO docs_sync"
+            " (local_path, remote_id, url, updated_at, project_id)"
+            " VALUES (?, ?, ?, ?, ?)",
+            (
+                key,
+                str(meta.get("remote_id", "")),
+                str(meta.get("url", "")),
+                str(meta.get("updated_at", "")),
+                pid,
+            ),
+        )
+    db.commit()
+    db.close()
+
+
 class CompositeDocTarget:
     """Delegates to multiple DocumentationTargets.
 
@@ -82,19 +131,26 @@ class CompositeDocTarget:
         # S1700.6: best-effort flush of pending ops (non-blocking)
         self._flush_pending()
 
+        # RAISE-5894: inject remote_id from docs_sync so remote adapter can PUT by ID
+        local_path = metadata.get("path")
+        if local_path:
+            stored_id = self._load_remote_id(str(local_path))
+            if stored_id:
+                metadata = {**metadata, "remote_id": stored_id}
+
         results, failures, fs_result, remote_failed = self._publish_to_targets(
             doc_type, content, metadata
         )
 
-        # S20.2: update sync manifest when remote publish succeeded
+        # RAISE-5618: persist sync state to SQLite when remote publish succeeded
         if not remote_failed and results:
             remote_result = results[-1]
             local_path = metadata.get("path")
             if remote_result.success and local_path:
                 try:
-                    self._update_sync_manifest(str(local_path), remote_result)
+                    self._save_docs_sync(str(local_path), remote_result)
                 except Exception:
-                    logger.warning("Failed to update sync manifest", exc_info=True)
+                    logger.warning("Failed to save docs sync state", exc_info=True)
 
         # S1700.6: queue pending op when filesystem (canonical) succeeded but remote failed
         if (
@@ -169,25 +225,56 @@ class CompositeDocTarget:
             )
         return best
 
-    def _update_sync_manifest(
-        self, local_path: str, remote_result: PublishResult
-    ) -> None:
-        """Write .raise/sync/docs-manifest.yaml after a successful remote publish."""
+    def _load_remote_id(self, local_path: str) -> str | None:
+        """Return remote_id from docs_sync for local_path, or None if not found."""
+        if self._project_root is None:
+            return None
+        from raise_cli.storage.connection import get_project_db, get_project_id
+        from raise_cli.storage.schema import create_all
+
+        db = get_project_db(self._project_root)
+        create_all(db)
+        pid = get_project_id(self._project_root)
+        row = db.execute(
+            "SELECT remote_id FROM docs_sync WHERE local_path = ? AND project_id = ?",
+            (local_path, pid),
+        ).fetchone()
+        db.close()
+        return row[0] if row and row[0] else None
+
+    def _save_docs_sync(self, local_path: str, remote_result: PublishResult) -> None:
+        """Persist docs sync state to SQLite after a successful remote publish."""
         if self._project_root is None:
             return
-        manifest_path = self._project_root / ".raise" / "sync" / "docs-manifest.yaml"
-        manifest_path.parent.mkdir(parents=True, exist_ok=True)
-        data: dict[str, Any] = {}
-        if manifest_path.exists():
-            data = yaml.safe_load(manifest_path.read_text(encoding="utf-8")) or {}
-        data[local_path] = {
-            "remote_id": remote_result.remote_id,
-            "url": remote_result.url,
-            "updated_at": datetime.now(UTC).replace(microsecond=0).isoformat(),
-        }
-        with open(manifest_path, "w", encoding="utf-8") as f:
-            f.write("# Auto-managed by rai docs — do not edit manually\n")
-            yaml.dump(data, f, default_flow_style=False, sort_keys=True)
+        from raise_cli.storage.connection import get_project_db, get_project_id
+        from raise_cli.storage.schema import create_all
+
+        self._migrate_yaml_to_sqlite()
+        db = get_project_db(self._project_root)
+        create_all(db)
+        pid = get_project_id(self._project_root)
+        db.execute(
+            "INSERT INTO docs_sync (local_path, remote_id, url, updated_at, project_id)"
+            " VALUES (?, ?, ?, ?, ?)"
+            " ON CONFLICT(local_path, project_id) DO UPDATE SET"
+            "   remote_id = excluded.remote_id,"
+            "   url = excluded.url,"
+            "   updated_at = excluded.updated_at",
+            (
+                local_path,
+                remote_result.remote_id or "",
+                remote_result.url or "",
+                datetime.now(UTC).replace(microsecond=0).isoformat(),
+                pid,
+            ),
+        )
+        db.commit()
+        db.close()
+
+    def _migrate_yaml_to_sqlite(self) -> None:
+        """Lazy one-time migration: import valid YAML entries to SQLite, skip stale paths."""
+        if self._project_root is not None:
+            migrate_docs_yaml_to_sqlite(self._project_root)
 
     def _flush_pending(self) -> None:
         """Attempt to replay pending ops against remote. Best-effort, never raises."""

{raise_cli-3.0.0a6 → raise_cli-3.1.0a3}/src/raise_cli/adapters/composite_pm.py

@@ -12,18 +12,23 @@ Design decision D1: read-local (inverse of CompositeDocTarget which reads remote
 
 from __future__ import annotations
 
+import contextlib
 import logging
 from collections.abc import Callable
 from datetime import UTC, datetime
+from pathlib import Path
 from typing import Any
 from uuid import uuid4
 
 from raise_cli.adapters.filesystem_models import BacklogItem
 from raise_cli.adapters.models import (
     AdapterHealth,
+    AttachmentDetail,
+    AttachmentRef,
     BatchResult,
     Comment,
     CommentRef,
+    FailureDetail,
     FieldDefinition,
     IssueDetail,
     IssueRef,
@@ -64,6 +69,11 @@ class CompositeBacklogAdapter:
         self._ledger = ledger
         self._pending = pending
 
+    @property
+    def remotes(self) -> list[Any]:
+        """Remote adapters in write order."""
+        return list(self._remotes)
+
     # -------------------------------------------------------------------
     # Locality probe (RAISE-1877)
     # -------------------------------------------------------------------
@@ -232,20 +242,44 @@ class CompositeBacklogAdapter:
         return local_ref
 
     def transition_issue(self, key: str, status: str) -> IssueRef:
-        """Transition locally (when local-canonical), then best-effort on remotes."""
+        """Transition locally (when local-canonical), then propagate on remotes.
+
+        Remote-native keys (no local artifact, e.g. RAISE-xxx) call the remote
+        directly and propagate errors — queuing a failed transition for replay
+        makes no sense because transitions are context-dependent (RAISE-4140).
+
+        Local-canonical keys also propagate remote errors (RAISE-4186): if Jira
+        rejects the transition, the local state is rolled back (best-effort) and
+        the exception is re-raised so the caller sees a real failure instead of
+        a false-positive success.
+        """
         self._flush_pending()
         if self._local_has_key(key):
+            prev_status = self._local.get_issue(key).status
             local_ref: IssueRef = self._local.transition_issue(key, status)
-        else:
-            local_ref = IssueRef(key=key)  # remote-native
 
-        def _do_transition(remote: Any, rk: str) -> None:
-            remote.transition_issue(rk, status)
+            def _do_transition(remote: Any, rk: str) -> None:
+                remote.transition_issue(rk, status)
 
-        self._write_to_remotes_keyed(
-            "transition_issue", key, {"status": status}, _do_transition
-        )
-        return local_ref
+            try:
+                self._write_to_remotes_keyed(
+                    "transition_issue",
+                    key,
+                    {"status": status},
+                    _do_transition,
+                    propagate_errors=True,
+                )
+            except Exception:
+                with contextlib.suppress(Exception):
+                    self._local.transition_issue(key, prev_status)
+                raise
+            return local_ref
+
+        # Remote-native: call directly so errors propagate to the caller.
+        remote_key = self._ledger.get(key) or key
+        for remote in self._remotes:
+            remote.transition_issue(remote_key, status)
+        return IssueRef(key=key)
 
     def batch_transition(self, keys: list[str], status: str) -> BatchResult:
         """Batch transition: local-canonical via filesystem, remote-native direct to remote."""
@@ -292,6 +326,24 @@ class CompositeBacklogAdapter:
                 logger.warning("Remote batch_transition failed: %s", exc)
         return merged
 
+    def batch_create(self, issues: list[IssueSpec]) -> BatchResult:
+        """Create multiple issues with per-item fault isolation."""
+        succeeded: list[IssueRef] = []
+        failed: list[FailureDetail] = []
+        for spec in issues:
+            try:
+                ref = self.create_issue(spec.project, spec)
+                succeeded.append(ref)
+            except Exception as exc:
+                logger.warning("batch_create failed for %r: %s", spec.summary, exc)
+                failed.append(FailureDetail(key=spec.summary, error=str(exc)))
+        return BatchResult(succeeded=succeeded, failed=failed)
+
+    def remove_link(self, link_id: str) -> None:
+        """Remove an issue link by ID — delegates to remote only (IDs are remote-native)."""
+        for remote in self._remotes:
+            remote.remove_link(link_id)
+
     def link_to_parent(self, child_key: str, parent_key: str) -> None:
         """Link locally (when local-canonical), then best-effort on remotes."""
         self._flush_pending()
@@ -322,8 +374,12 @@ class CompositeBacklogAdapter:
                 "link_to_parent", child_key, {"parent_key": parent_key}
             )
 
-    def link_issues(self, source: str, target: str, link_type: str) -> None:
-        """Link locally (when local-canonical), then best-effort on remotes."""
+    def link_issues(self, source: str, target: str, link_type: str) -> bool:
+        """Link locally (when local-canonical), then best-effort on remotes.
+
+        Returns True if the link was created on all remotes, False if any
+        remote failed and the operation was queued for later replay.
+        """
         self._flush_pending()
         if self._local_has_key(source) and self._local_has_key(target):
             self._local.link_issues(source, target, link_type)
@@ -334,6 +390,7 @@ class CompositeBacklogAdapter:
             target if not self._local_has_key(target) else None
         )
         if remote_source and remote_target:
+            queued = False
             for remote in self._remotes:
                 try:
                     remote.link_issues(remote_source, remote_target, link_type)
@@ -344,12 +401,14 @@ class CompositeBacklogAdapter:
                         {"target": target, "link_type": link_type},
                     )
                     logger.warning("Remote link_issues failed: %s", exc)
-        else:
-            self._pending.append(
-                "link_issues",
-                source,
-                {"target": target, "link_type": link_type},
-            )
+                    queued = True
+            return not queued
+        self._pending.append(
+            "link_issues",
+            source,
+            {"target": target, "link_type": link_type},
+        )
+        return False
 
     def add_comment(self, key: str, body: str) -> CommentRef:
         """Comment locally (when local-canonical), then best-effort on remotes."""
@@ -372,7 +431,7 @@ class CompositeBacklogAdapter:
     def get_issue(self, key: str) -> IssueDetail:
         """Read from local; fallback to remote for remote-native keys."""
         try:
-            return self._local.get_issue(key)  # type: ignore[no-any-return]
+            detail: IssueDetail = self._local.get_issue(key)
         except (KeyError, FileNotFoundError):
             if self._remotes:
                 logger.debug(
@@ -380,6 +439,11 @@ class CompositeBacklogAdapter:
                 )
                 return self._remotes[0].get_issue(key)  # type: ignore[no-any-return]
             raise
+        if detail.status == "pending" and self._remotes:
+            with contextlib.suppress(Exception):
+                remote: IssueDetail = self._remotes[0].get_issue(key)
+                return detail.model_copy(update={"status": remote.status})
+        return detail
 
     def get_comments(
         self, key: str, limit: int = 10, offset: int = 0, fetch_all: bool = False
@@ -452,6 +516,42 @@ class CompositeBacklogAdapter:
             names=names, issue_type=issue_type
         )  # type: ignore[no-any-return]
 
+    # ── Attachments (S2503.7) ────────────────────────────────────────
+
+    def attach(
+        self, key: str, path: Path, mime_type: str | None = None
+    ) -> AttachmentRef:
+        """Delegate to primary remote; raise if no remotes."""
+        if not self._remotes:
+            raise RuntimeError("No remote adapters available for attach()")
+        return self._remotes[0].attach(key, path, mime_type)  # type: ignore[no-any-return]
+
+    def get_attachments(self, key: str) -> list[AttachmentDetail]:
+        """Delegate to primary remote; return [] if no remotes."""
+        if not self._remotes:
+            return []
+        return self._remotes[0].get_attachments(key)  # type: ignore[no-any-return]
+
+    # ── Sprint (Jira-specific) — delegate to primary remote ──────────
+
+    def get_sprints(self, project_key: str, state: str | None = None) -> list[Any]:
+        """Delegate to primary remote; raise if no remotes."""
+        if not self._remotes:
+            raise RuntimeError("No remote adapters available for get_sprints()")
+        return self._remotes[0].get_sprints(project_key, state=state)  # type: ignore[no-any-return]
+
+    def assign_to_sprint(self, issue_key: str, sprint_id: int) -> None:
+        """Delegate to primary remote; raise if no remotes."""
+        if not self._remotes:
+            raise RuntimeError("No remote adapters available for assign_to_sprint()")
+        self._remotes[0].assign_to_sprint(issue_key, sprint_id)  # type: ignore[no-any-return]
+
+    def download_attachment(self, attachment_id: str) -> bytes:
+        """Delegate to primary remote; raise if no remotes."""
+        if not self._remotes:
+            raise RuntimeError("No remote adapters available for download_attachment()")
+        return self._remotes[0].download_attachment(attachment_id)  # type: ignore[no-any-return]
+
     # -------------------------------------------------------------------
     # Drain — replay queued pending ops (S1700.7.1)
     # -------------------------------------------------------------------
@@ -723,6 +823,8 @@ class CompositeBacklogAdapter:
         local_key: str,
         args: dict[str, Any],
         action: _RemoteAction,
+        *,
+        propagate_errors: bool = False,
     ) -> None:
         """Execute a keyed write op on all remotes using ledger for key translation.
 
@@ -762,11 +864,13 @@ class CompositeBacklogAdapter:
                 action(remote, remote_key)
                 completed.append(i)
             except Exception as exc:
+                logger.warning("Remote %s failed: %s", op_name, exc)
+                if propagate_errors:
+                    raise
                 self._pending.append(
                     op_name,
                     local_key,
                     args,
                     completed_remotes=completed,
                 )
-                logger.warning("Remote %s failed: %s", op_name, exc)
                 break