[4cfd99c2] Backend: docs-divergence engine, feature flag, release seam, and compose wiring (#507) (#513)

* [fe5c049b] Register docs-sync feature flag and compose wiring (#505) * [fe5c049b] Register docs-sync feature flag and compose wiring * [fe5c049b] feat(config): wire ROBOCO_DOCS_SYNC_ENABLED flag and compose defaults * [fe5c049b] docs(config): document ROBOCO_DOCS_SYNC_ENABLED flag and compose defaults --------- * [687574d2] Implement docs-sync engine and release-proposal seam (#506) * [687574d2] Add docs-sync engine and release-proposal publish seam * [687574d2] Restore task.py safeguards deleted by docs-sync engine commit and filter docs_sync version in SQL * [687574d2] docs(map): add engine-docs-sync architecture map and cross-references * [687574d2] docs(config): update docs-sync flag, cap settings, and changelog entry --------- * [3e7cd5a8] Fix task.py regressions from docs-sync PR (#509) * [3e7cd5a8] fix(task): restore deleted auditor alerts and revert descendant cast form in task.py * [3e7cd5a8] docs(task-service): restore auditor alerts and cast notes in map and changelog --------- * [e6e23c1f] Enforce docs_sync_max_per_cycle cap in docs_sync_engine.py (#510) * [e6e23c1f] Enforce docs_sync_max_per_cycle cap in DocsSyncEngine * [e6e23c1f] docs(docs-sync): document docs_sync_max_per_cycle enforcement in engine map, README, and docstring --------- * [e4b7dd0f] Revert task.py cast regressions from docs-sync PR (#511) * [e4b7dd0f] fix(task): revert cast regressions in supersede and descendants * [e4b7dd0f] docs(map): correct PR #511 cast regression entry in task-service slice map * [e4b7dd0f] docs(backend): add SQLAlchemy UUID cast pattern note and inline comments in task.py --------- * [1fdfe711] Fix Python quality gate on docs-sync PR (#512) * [1fdfe711] Fix ruff formatting in task.py and add coverage tests for docs-sync surface * [1fdfe711] fix(task): use generic JSON .as_string() accessor in list_open_docs_sync_tasks and correct test patch targets * [1fdfe711] docs(task-service): record docs-sync JSON accessor fix and list_open_docs_sync_tasks map entry --------- --------- Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> Co-authored-by: Backend Developer 2 <be-dev-2@roboco.tech>
2026-08-03 07:23:24 +02:00 · 2026-07-14 02:22:37 +02:00
parent 09b797fe9c
commit f03859c64c
26 changed files with 1225 additions and 12 deletions
@@ -0,0 +1,228 @@
+"""The release-proposal publish hook originates a docs-update task (best-effort,
+never raises into approve()). Layering: release_proposal calls only the small
+typed seam ``DocsSyncEngine.originate_docs_update`` — this test patches at that
+seam, not the engine's internals.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+from unittest.mock import AsyncMock, MagicMock, patch
+from uuid import uuid4
+
+import pytest
+from roboco.db.tables import AgentTable, ProjectTable, TaskTable
+from roboco.foundation import identity as _foundation
+from roboco.models.base import AgentRole, AgentStatus, TaskNature, TaskStatus, TaskType
+from roboco.models.base import Team as T
+from roboco.services.release_executor import ReleaseResult
+from roboco.services.release_proposal import ReleaseProposalService
+from roboco.services.release_readiness import ReleaseReadinessReport, report_to_dict
+from roboco.services.task import RELEASE_MANAGER_SOURCE
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+_VERSION = "0.23.0"
+
+
+def _report() -> ReleaseReadinessReport:
+    return ReleaseReadinessReport(
+        proposed_version=_VERSION,
+        bump_kind="minor",
+        change_summary=["feat: docs-sync engine", "fix: typos"],
+        drafted_changelog=f"## [{_VERSION}]\n\n### Added\n- docs-sync engine\n",
+        version_bump_plan=["pyproject.toml"],
+        gaps=[],
+        migration_notes=[],
+        gate_state="green",
+    )
+
+
+async def _seed_proposal(session: AsyncSession) -> TaskTable:
+    system_uuid = _foundation.AGENTS["system"].uuid
+    secretary_uuid = _foundation.AGENTS["secretary-1"].uuid
+    for uuid_, slug, role in (
+        (system_uuid, "system", AgentRole.SYSTEM),
+        (secretary_uuid, "secretary-1", AgentRole.SECRETARY),
+    ):
+        if await session.get(AgentTable, uuid_) is None:
+            session.add(
+                AgentTable(
+                    id=uuid_,
+                    name=slug,
+                    slug=slug,
+                    role=role,
+                    team=None,
+                    status=AgentStatus.ACTIVE,
+                    model_config={},
+                    system_prompt="x",
+                    capabilities=[],
+                    permissions={},
+                    metrics={},
+                )
+            )
+    await session.flush()
+    project = ProjectTable(
+        id=uuid4(),
+        name="RoboCo",
+        slug=f"roboco-{uuid4().hex[:6]}",
+        git_url="https://example.com/roboco.git",
+        assigned_cell=T.BACKEND,
+        created_by=system_uuid,
+    )
+    session.add(project)
+    await session.flush()
+    task = TaskTable(
+        id=uuid4(),
+        title=f"Release proposal: v{_VERSION}",
+        description="proposal body",
+        acceptance_criteria=["CEO approves"],
+        status=TaskStatus.PENDING,
+        priority=2,
+        task_type=TaskType.ADMINISTRATIVE,
+        nature=TaskNature.NON_TECHNICAL,
+        project_id=project.id,
+        created_by=system_uuid,
+        assigned_to=secretary_uuid,
+        team=T.MAIN_PM,
+        source=RELEASE_MANAGER_SOURCE,
+        confirmed_by_human=False,
+        orchestration_markers={"release_report": report_to_dict(_report())},
+    )
+    session.add(task)
+    await session.flush()
+    return task
+
+
+@pytest.mark.asyncio
+async def test_publish_success_calls_docs_sync_seam(db_session: AsyncSession) -> None:
+    task = await _seed_proposal(db_session)
+    published = ReleaseResult(
+        status="published",
+        version=_VERSION,
+        files_changed=["pyproject.toml"],
+        commit_sha="abc123",
+        release_url=f"https://github.com/x/roboco/releases/tag/v{_VERSION}",
+        detail="ok",
+    )
+    fake_executor = AsyncMock()
+    fake_executor.execute = AsyncMock(return_value=published)
+    fake_engine = AsyncMock()
+    fake_engine.originate_docs_update = AsyncMock(return_value=None)
+
+    with (
+        patch(
+            "roboco.services.release_proposal.get_release_executor",
+            AsyncMock(return_value=fake_executor),
+        ),
+        patch(
+            "roboco.services.docs_sync_engine.get_docs_sync_engine",
+            return_value=fake_engine,
+        ),
+        patch.object(
+            ReleaseProposalService, "_acquire_release_lock", AsyncMock(return_value="t")
+        ),
+        patch.object(
+            ReleaseProposalService,
+            "_release_release_lock",
+            AsyncMock(return_value=None),
+        ),
+        patch.object(
+            ReleaseProposalService,
+            "_heartbeat_release_lock",
+            AsyncMock(return_value=True),
+        ),
+    ):
+        result = await ReleaseProposalService(db_session).approve(cast("UUID", task.id))
+
+    assert result is not None
+    assert result.status == "published"
+    fake_engine.originate_docs_update.assert_awaited_once_with(
+        version=_VERSION,
+        changelog=f"## [{_VERSION}]\n\n### Added\n- docs-sync engine\n",
+    )
+
+
+@pytest.mark.asyncio
+async def test_docs_sync_failure_never_fails_the_approve(
+    db_session: AsyncSession,
+) -> None:
+    """A docs-sync origination exception is swallowed — the release already
+    published."""
+    task = await _seed_proposal(db_session)
+    published = ReleaseResult(
+        status="published",
+        version=_VERSION,
+        files_changed=["pyproject.toml"],
+        commit_sha="abc123",
+        release_url=None,
+        detail="ok",
+    )
+    fake_executor = AsyncMock()
+    fake_executor.execute = AsyncMock(return_value=published)
+
+    with (
+        patch(
+            "roboco.services.release_proposal.get_release_executor",
+            AsyncMock(return_value=fake_executor),
+        ),
+        patch(
+            "roboco.services.docs_sync_engine.get_docs_sync_engine",
+            side_effect=RuntimeError("docs-sync boom"),
+        ),
+        patch.object(
+            ReleaseProposalService, "_acquire_release_lock", AsyncMock(return_value="t")
+        ),
+        patch.object(
+            ReleaseProposalService,
+            "_release_release_lock",
+            AsyncMock(return_value=None),
+        ),
+        patch.object(
+            ReleaseProposalService,
+            "_heartbeat_release_lock",
+            AsyncMock(return_value=True),
+        ),
+    ):
+        result = await ReleaseProposalService(db_session).approve(cast("UUID", task.id))
+
+    assert result is not None
+    assert result.status == "published"
+    await db_session.refresh(task)
+    assert task.status == TaskStatus.COMPLETED
+
+
+@pytest.mark.asyncio
+async def test_draft_docs_update_calls_engine_seam() -> None:
+    """``_draft_docs_update`` is the best-effort seam; cover it directly so the
+    publish-success path is exercised even when the full ``approve()`` DB fixture
+    is unavailable."""
+    report = _report()
+    fake_engine = AsyncMock()
+    fake_engine.originate_docs_update = AsyncMock(return_value=None)
+
+    with patch(
+        "roboco.services.docs_sync_engine.get_docs_sync_engine",
+        return_value=fake_engine,
+    ):
+        await ReleaseProposalService(MagicMock())._draft_docs_update(report)
+
+    fake_engine.originate_docs_update.assert_awaited_once_with(
+        version=_VERSION,
+        changelog=report.drafted_changelog,
+    )
+
+
+@pytest.mark.asyncio
+async def test_draft_docs_update_swallows_engine_exception() -> None:
+    """An engine exception must never propagate out of the best-effort seam."""
+    report = _report()
+
+    with patch(
+        "roboco.services.docs_sync_engine.get_docs_sync_engine",
+        side_effect=RuntimeError("docs-sync boom"),
+    ):
+        await ReleaseProposalService(MagicMock())._draft_docs_update(report)