Transfered deep scope functionality from the custodian

tests/test_web_api.py

@@ -18,6 +18,7 @@ def test_openapi_groups_agent_facing_endpoints():
         "analysis",
         "review",
         "registry",
+        "scope",
         "search",
         "discovery",
     }
@@ -252,6 +253,15 @@ def test_openapi_contract_snapshot_for_stable_agent_paths():
         "/repos/{repository_id}/export": {
             "get": {"tags": ["discovery"], "success_schema": "application/x-yaml"}
         },
+        "/repos/{repo_slug}/scope": {
+            "get": {"tags": ["scope"], "success_schema": None}
+        },
+        "/repos/{repo_slug}/scope/diff": {
+            "get": {"tags": ["scope"], "success_schema": "object"}
+        },
+        "/repos/{repo_slug}/scope/write": {
+            "post": {"tags": ["scope"], "success_schema": "object"}
+        },
         "/repos/{repository_id}/expectation-gaps": {
             "get": {"tags": ["review"], "success_schema": "list[ExpectationGapResponse]"},
             "post": {"tags": ["review"], "success_schema": "ExpectationGapResponse"},
@@ -455,6 +465,100 @@ def test_api_manual_registry_loop(tmp_path):
         app.dependency_overrides.clear()
 
 
+def test_api_generates_diffs_and_writes_scope_md(tmp_path):
+    source = tmp_path / "scope-repo"
+    source.mkdir()
+
+    def override_settings():
+        return Settings(
+            database_path=str(tmp_path / "scope-api.sqlite3"),
+            checkout_root=str(tmp_path / "checkouts"),
+        )
+
+    app.dependency_overrides[get_settings] = override_settings
+    client = TestClient(app)
+    try:
+        repository = client.post(
+            "/repos",
+            json={
+                "name": "Scope Repo",
+                "url": str(source),
+                "description": "Generates SCOPE.md through the API.",
+            },
+        ).json()
+        ability_id = client.post(
+            f"/repos/{repository['id']}/abilities",
+            json={
+                "name": "Maintain Repository Scope",
+                "description": "Keeps repository utility understandable.",
+            },
+        ).json()["id"]
+        client.post(
+            f"/repos/{repository['id']}/capabilities",
+            json={
+                "ability_id": ability_id,
+                "name": "Generate SCOPE.md",
+                "description": "Renders SCOPE.md from approved characteristics.",
+                "primary_class": "api",
+                "attributes": ["scope", "generation"],
+            },
+        )
+
+        preview = client.get("/repos/scope-repo/scope")
+        assert preview.status_code == 200
+        assert preview.headers["content-type"].startswith("text/markdown")
+        assert "# SCOPE" in preview.text
+        assert "title: Generate SCOPE.md" in preview.text
+
+        diff = client.get("/repos/scope-repo/scope/diff")
+        assert diff.status_code == 200
+        assert diff.json()["needs_update"] is True
+        assert {section["status"] for section in diff.json()["sections"]} == {"missing"}
+
+        write = client.post("/repos/scope-repo/scope/write")
+        assert write.status_code == 200
+        assert write.json() == {"written": True, "path": str(source / "SCOPE.md")}
+        assert (source / "SCOPE.md").read_text(encoding="utf-8").startswith("# SCOPE")
+
+        current = client.get("/repos/scope-repo/scope/diff")
+        assert current.status_code == 200
+        assert current.json()["needs_update"] is False
+        assert {section["status"] for section in current.json()["sections"]} == {"ok"}
+
+        empty = client.post(
+            "/repos",
+            json={
+                "name": "Empty Scope",
+                "url": "https://example.test/empty-scope.git",
+                "description": "No approved characteristics yet.",
+            },
+        ).json()
+        assert client.get("/repos/empty-scope/scope").status_code == 404
+
+        remote = client.post(
+            "/repos",
+            json={
+                "name": "Remote Scope",
+                "url": "https://example.test/remote-scope.git",
+                "description": "Has no known local checkout path.",
+            },
+        ).json()
+        remote_ability = client.post(
+            f"/repos/{remote['id']}/abilities",
+            json={"name": "Remote Scope Generation"},
+        ).json()["id"]
+        client.post(
+            f"/repos/{remote['id']}/capabilities",
+            json={
+                "ability_id": remote_ability,
+                "name": "Generate Remote SCOPE.md",
+            },
+        )
+        assert client.post("/repos/remote-scope/scope/write").status_code == 409
+    finally:
+        app.dependency_overrides.clear()
+
+
 def test_api_compare_gap_and_export_use_cases(tmp_path):
     def override_settings():
         return Settings(