its-magic 0.1.3-0 → 0.1.3-2

package/template/scripts/sovereign_role_manifest_validate.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Sovereign Role-Behavior Manifest validator CLI (US-0106 / DEC-0106).
+
+CLI contract:
+  --file <path>        validate a single YAML manifest
+  --repo <root>        validate repo root active + template pair
+  --self-test          run lib self-test
+  --enforce            exit non-zero on validation failure
+
+Success: [SOVEREIGN_ROLE_MANIFEST_VALIDATION_OK]
+Fail:    reason codes SOVEREIGN_ROLE_* (SCHEMA_INVALID / UNKNOWN_ROLE / UNKNOWN_PHASE /
+         SECRET_DETECTED / OBJECTIVE_OVERFLOW)
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+_SCRIPT_DIR = Path(__file__).resolve().parent
+if str(_SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPT_DIR))
+
+from sovereign_role_manifest_lib import (  # noqa: E402
+    MANIFEST_REL,
+    ReasonCode,
+    is_role_manifest_enabled,
+    load_manifest,
+    self_test,
+    validate_manifest,
+)
+
+TEMPLATE_MANIFEST_REL = "template/.cursor/sovereign-role-manifest.yaml.example"
+
+
+def _load_yaml_text(path: Path) -> Tuple[str, str | None]:
+    try:
+        return path.read_text(encoding="utf-8"), None
+    except Exception as exc:
+        return "", f"{ReasonCode.SCHEMA_INVALID.value}: cannot read {path}: {exc}"
+
+
+def _validate_file(path: Path) -> Tuple[bool, List[str]]:
+    text, err = _load_yaml_text(path)
+    if err:
+        return False, [err]
+    from sovereign_role_manifest_lib import _parse_yaml_minimal
+    parsed = _parse_yaml_minimal(text)
+    ok, reason = validate_manifest(parsed)
+    if not ok:
+        return False, [f"{ReasonCode.SCHEMA_INVALID.value}: {reason}"]
+    return True, []
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--file", type=Path, help="Validate a single manifest YAML")
+    p.add_argument("--repo", type=Path, help="Repo root to validate active + template pair")
+    p.add_argument("--self-test", action="store_true")
+    p.add_argument("--enforce", action="store_true", help="Exit non-zero on validation failure")
+    args = p.parse_args()
+
+    if args.self_test:
+        ok = self_test()
+        print("[SOVEREIGN_ROLE_MANIFEST_SELF_TEST_OK]" if ok else "[SOVEREIGN_ROLE_MANIFEST_SELF_TEST_FAIL]")
+        return 0 if ok else 2
+
+    if args.file:
+        ok, errs = _validate_file(args.file)
+        if ok:
+            print(f"[SOVEREIGN_ROLE_MANIFEST_VALIDATION_OK] file={args.file}")
+            return 0
+        for e in errs:
+            print(f"[SOVEREIGN_ROLE_MANIFEST_VALIDATION_ERROR] {e}")
+        return 1 if args.enforce else 0
+
+    if args.repo:
+        root = args.repo
+        active = root / MANIFEST_REL
+        template = root / TEMPLATE_MANIFEST_REL
+        errors: List[str] = []
+        if not active.is_file():
+            errors.append(f"{ReasonCode.SCHEMA_INVALID.value}: missing active manifest {active}")
+        else:
+            ok, errs = _validate_file(active)
+            errors.extend(errs)
+        if not template.is_file():
+            errors.append(f"{ReasonCode.SCHEMA_INVALID.value}: missing template example {template}")
+        else:
+            ok, errs = _validate_file(template)
+            errors.extend(errs)
+        if errors:
+            for e in errors:
+                print(f"[SOVEREIGN_ROLE_MANIFEST_VALIDATION_ERROR] {e}")
+            return 1 if args.enforce else 0
+        print(f"[SOVEREIGN_ROLE_MANIFEST_VALIDATION_OK] repo={root}")
+        return 0
+
+    p.error("one of --file, --repo, --self-test is required")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/template/tests/us0108_contract_test.py

@@ -0,0 +1,207 @@
+"""US-0108: Eight contract tests for Parallel Instance Arbitrage.
+
+DEC-0108 §10: scratchpad keys, worktree isolation, selection predicate,
+merge policy, resource guard, execute steps 25-28, backward compat, parity scope.
+
+Default-off: SOVEREIGN_PARALLEL_DEV=0 → zero overhead.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _load_arbiter():
+    root = _repo_root()
+    scripts_dir = str(root / "scripts")
+    if scripts_dir not in sys.path:
+        sys.path.insert(0, scripts_dir)
+    import parallel_dev_arbiter as mod  # noqa: E402
+    return mod
+
+
+def _enabled_scratchpad(scratchpad_path: Path) -> None:
+    """Write scratchpad with US-0108 enabled."""
+    scratchpad_path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [
+        "# US-0108 parallel dev enabled\n",
+        "SOVEREIGN_PARALLEL_DEV=1\n",
+        "AUTO_SOVEREIGN_PARALLEL_N=3\n",
+        "AUTO_SOVEREIGN_PARALLEL_MAX_TOTAL=6\n",
+        "AUTO_SOVEREIGN_MERGE_RESOLVE=first_pass_wins\n",
+        "AUTO_SOVEREIGN_WORKTREE_KEEP=0\n",
+        "AUTO_SOVEREIGN_PARALLEL_QA=0\n",
+        "AUTO_SOVEREIGN_PARALLEL_QA_ARBITER=critic_first_pass\n",
+        "AUTO_SOVEREIGN_PARALLEL_ANTI_SLOP_THRESHOLD=6\n",
+        "AUTO_SOVEREIGN_PARALLEL_REWORK_MAX=2\n",
+        "AUTO_SOVEREIGN_PARALLEL_MERGE_TIMEOUT_SEC=60\n",
+    ]
+    scratchpad_path.write_text("".join(lines), encoding="utf-8")
+
+
+class TestUS0108ScratchpadKeys(unittest.TestCase):
+    """test_us0108_scratchpad_keys_literals (AC-1)."""
+
+    def test_scratchpad_key_literals(self) -> None:
+        mod = _load_arbiter()
+        required_keys = {
+            "SOVEREIGN_PARALLEL_DEV",
+            "AUTO_SOVEREIGN_PARALLEL_N",
+            "AUTO_SOVEREIGN_PARALLEL_MAX_TOTAL",
+            "AUTO_SOVEREIGN_MERGE_RESOLVE",
+            "AUTO_SOVEREIGN_WORKTREE_KEEP",
+            "AUTO_SOVEREIGN_PARALLEL_QA",
+            "AUTO_SOVEREIGN_PARALLEL_QA_ARBITER",
+            "AUTO_SOVEREIGN_PARALLEL_ANTI_SLOP_THRESHOLD",
+            "AUTO_SOVEREIGN_PARALLEL_REWORK_MAX",
+            "AUTO_SOVEREIGN_PARALLEL_MERGE_TIMEOUT_SEC",
+        }
+        for key in required_keys:
+            self.assertIn(key, mod.SCRATCHPAD_KEY_DEFAULTS,
+                          f"{key} missing from SCRATCHPAD_KEY_DEFAULTS")
+        self.assertEqual(mod.SCRATCHPAD_KEY_DEFAULTS["SOVEREIGN_PARALLEL_DEV"], "0")
+        self.assertEqual(mod.SCRATCHPAD_KEY_DEFAULTS["AUTO_SOVEREIGN_PARALLEL_N"], "3")
+        self.assertEqual(mod.SCRATCHPAD_KEY_DEFAULTS["AUTO_SOVEREIGN_PARALLEL_MAX_TOTAL"], "6")
+
+
+class TestUS0108WorktreeIsolation(unittest.TestCase):
+    """test_us0108_worktree_isolation (AC-2)."""
+
+    def test_worktree_creation_pattern(self) -> None:
+        mod = _load_arbiter()
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / ".git").mkdir()
+            wt = mod.create_worktree("US-0108", 0, "main", repo_root)
+            self.assertEqual(wt.instance_id, "US-0108-inst0")
+            self.assertEqual(wt.branch, "us0108-US-0108-0")
+            expected_path = repo_root / ".git" / "worktrees" / "us0108-US-0108-0"
+            self.assertEqual(wt.path, str(expected_path))
+
+
+class TestUS0108SelectionDeterminism(unittest.TestCase):
+    """test_us0108_selection_determinism (AC-3)."""
+
+    def test_selection_logic(self) -> None:
+        mod = _load_arbiter()
+        results = [
+            {"qa_verdict": "pass", "anti_slop_score": 5, "proof_issued_at": "2026-06-29T22:00:00Z", "instance_id": "A"},
+            {"qa_verdict": "pass", "anti_slop_score": 8, "proof_issued_at": "2026-06-29T22:01:00Z", "instance_id": "B"},
+            {"qa_verdict": "fail", "anti_slop_score": 10, "proof_issued_at": "2026-06-29T22:00:30Z", "instance_id": "C"},
+        ]
+        winner = mod.select_winner(results)
+        self.assertIsNotNone(winner)
+        self.assertEqual(winner["instance_id"], "B")  # highest anti_slop among passing
+
+    def test_tie_break_earliest(self) -> None:
+        mod = _load_arbiter()
+        results = [
+            {"qa_verdict": "pass", "anti_slop_score": 7, "proof_issued_at": "2026-06-29T22:05:00Z", "instance_id": "X"},
+            {"qa_verdict": "pass", "anti_slop_score": 7, "proof_issued_at": "2026-06-29T22:01:00Z", "instance_id": "Y"},
+        ]
+        winner = mod.select_winner(results)
+        self.assertIsNotNone(winner)
+        self.assertEqual(winner["instance_id"], "Y")  # earliest proof_issued_at
+
+
+class TestUS0108MergeAndPickSchema(unittest.TestCase):
+    """test_us0108_merge_and_pick_schema (AC-4)."""
+
+    def test_pick_record_schema(self) -> None:
+        mod = _load_arbiter()
+        with tempfile.TemporaryDirectory() as td:
+            pick_path = Path(td) / "pick.json"
+            rec = mod.build_pick_record(
+                story_id="US-0108",
+                winner_id="inst0",
+                winner_path="/tmp/wt0",
+                qa_verdict="pass",
+                anti_slop_score=8,
+                merge_policy="first_pass_wins",
+                loser_ids=["inst1", "inst2"],
+                orchestrator_run_id="test-001",
+            )
+            ok, msg = mod.write_pick_record(rec, pick_path)
+            self.assertTrue(ok, msg)
+            self.assertTrue(pick_path.exists())
+            loaded = json.loads(pick_path.read_text(encoding="utf-8"))
+            vok, vmsg = mod.validate_pick_record(loaded)
+            self.assertTrue(vok, vmsg)
+            self.assertEqual(loaded["schema_version"], 1)
+            self.assertEqual(loaded["story_id"], "US-0108")
+            self.assertIn("loser_instance_ids", loaded)
+
+
+class TestUS0108ResourceCap(unittest.TestCase):
+    """test_us0108_resource_cap (AC-5)."""
+
+    def test_lockfile_acquire_release(self) -> None:
+        mod = _load_arbiter()
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / ".git").mkdir()
+            ok1, msg1 = mod.acquire_parallel_slot("slot1", repo_root, max_total=2)
+            self.assertTrue(ok1, msg1)
+            ok2, msg2 = mod.acquire_parallel_slot("slot2", repo_root, max_total=2)
+            self.assertTrue(ok2, msg2)
+            ok3, msg3 = mod.acquire_parallel_slot("slot3", repo_root, max_total=2)
+            self.assertFalse(ok3)
+            self.assertEqual(msg3, mod.ReasonCode.PARALLEL_DEV_RESOURCE_CAP_EXHAUSTED)
+            mod.release_parallel_slot("slot1", repo_root)
+            ok4, msg4 = mod.acquire_parallel_slot("slot4", repo_root, max_total=2)
+            self.assertTrue(ok4, msg4)
+
+
+class TestUS0108ExecuteSteps(unittest.TestCase):
+    """test_us0108_execute_steps_25_28 (AC-6)."""
+
+    def test_execute_disabled_by_default(self) -> None:
+        mod = _load_arbiter()
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / ".git").mkdir()
+            (repo_root / ".cursor").mkdir()
+            scratchpad = repo_root / ".cursor" / "scratchpad.md"
+            scratchpad.write_text("SOVEREIGN_PARALLEL_DEV=0\n", encoding="utf-8")
+            result = mod.execute_parallel_dev("US-0108", "main", 3, scratchpad, repo_root)
+            self.assertIsNone(result.winner_worktree)
+            self.assertEqual(result.merge_result.conflicts, [mod.ReasonCode.PARALLEL_DEV_DISABLED])
+
+
+class TestUS0108BackwardCompat(unittest.TestCase):
+    """test_us0108_backward_compat_single_dev_unchanged (AC-7)."""
+
+    def test_disabled_zero_overhead(self) -> None:
+        mod = _load_arbiter()
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / ".git").mkdir()
+            (repo_root / ".cursor").mkdir()
+            scratchpad = repo_root / ".cursor" / "scratchpad.md"
+            scratchpad.write_text("# no US-0108 keys\n", encoding="utf-8")
+            self.assertFalse(mod.is_parallel_enabled(scratchpad))
+            result = mod.execute_parallel_dev("US-0108", "main", 3, scratchpad, repo_root)
+            self.assertIsNone(result.winner_worktree)
+            self.assertEqual(result.merge_result.conflicts, [mod.ReasonCode.PARALLEL_DEV_DISABLED])
+
+
+class TestUS0108ParityScope(unittest.TestCase):
+    """test_us0108_parity_scope (AC-8)."""
+
+    def test_parity_scope_registered(self) -> None:
+        from check_intake_template_parity import SCOPES
+        self.assertIn("sovereign-parallel-dev", SCOPES)
+        pairs = SCOPES["sovereign-parallel-dev"]
+        self.assertGreater(len(pairs), 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/template/tests/us0109_contract_test.py

@@ -0,0 +1,209 @@
+"""Contract tests for US-0109 Self-Healing Deploy Loop (DEC-0109).
+
+8 core markers + 2 compose guards + 1 backward compat.
+"""
+from __future__ import annotations
+
+import os
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+from self_healing_deploy_lib import (  # noqa: E402
+    AUTO_SOVEREIGN_DEPLOY_HEALTH_ENDPOINT_KEY,
+    AUTO_SOVEREIGN_DEPLOY_PROBE_KIND_KEY,
+    AUTO_SOVEREIGN_DEPLOY_RETRY_MAX_KEY,
+    AUTO_SOVEREIGN_DEPLOY_SMOKE_TIMEOUT_SEC_KEY,
+    AUTO_SOVEREIGN_SELF_HEALING_DEPLOY_KEY,
+    DEFAULT_ACCEPTANCE_SMOKE_PATH,
+    DEFAULT_PROBE_KIND,
+    DEFAULT_RETRY_MAX,
+    DEFAULT_SELF_HEALING_ENABLED,
+    DEFAULT_SMOKE_TIMEOUT_SEC,
+    SOVEREIGN_DEPLOY_ACCEPTANCE_SMOKE_PATH_KEY,
+    ProbeKind,
+    ReasonCode,
+    get_acceptance_smoke_path,
+    get_probe_kind,
+    get_retry_max,
+    get_smoke_timeout_sec,
+    is_self_healing_deploy_enabled,
+    resolve_health_endpoint_url,
+    run_acceptance_smoke,
+    run_deploy_healing_loop,
+    run_health_probe,
+    run_smoke_probe_chain,
+    self_test,
+)
+
+
+# --- T-006: 8 core markers ---------------------------------------------------
+
+
+def test_us0109_scratchpad_keys_and_defaults() -> None:
+    """AC-1: 6 scratchpad keys resolve to DEC-0109 defaults."""
+    scratchpad = {}
+    assert is_self_healing_deploy_enabled(scratchpad) is False
+    assert get_retry_max(scratchpad) == DEFAULT_RETRY_MAX
+    assert get_smoke_timeout_sec(scratchpad) == DEFAULT_SMOKE_TIMEOUT_SEC
+    assert get_probe_kind(scratchpad) == ProbeKind.BOTH
+    assert get_acceptance_smoke_path(scratchpad) == DEFAULT_ACCEPTANCE_SMOKE_PATH
+    assert resolve_health_endpoint_url(scratchpad) is None
+    assert DEFAULT_SELF_HEALING_ENABLED == "0"
+    expected_keys = {
+        AUTO_SOVEREIGN_SELF_HEALING_DEPLOY_KEY,
+        AUTO_SOVEREIGN_DEPLOY_RETRY_MAX_KEY,
+        AUTO_SOVEREIGN_DEPLOY_SMOKE_TIMEOUT_SEC_KEY,
+        AUTO_SOVEREIGN_DEPLOY_PROBE_KIND_KEY,
+        SOVEREIGN_DEPLOY_ACCEPTANCE_SMOKE_PATH_KEY,
+        AUTO_SOVEREIGN_DEPLOY_HEALTH_ENDPOINT_KEY,
+    }
+    assert len(expected_keys) == 6
+
+
+def test_us0109_probe_health_stage() -> None:
+    """AC-2: health probe stage returns fail when target missing."""
+    scratchpad = {
+        AUTO_SOVEREIGN_SELF_HEALING_DEPLOY_KEY: "1",
+        AUTO_SOVEREIGN_DEPLOY_PROBE_KIND_KEY: "health_endpoint",
+        AUTO_SOVEREIGN_DEPLOY_HEALTH_ENDPOINT_KEY: "",
+    }
+    result = run_health_probe(scratchpad)
+    assert result.overall == "fail"
+    assert result.reason_code == ReasonCode.DEPLOY_HEALING_PROBE_TARGET_MISSING.value
+    assert result.health_status == "fail"
+    assert result.acceptance_status is None
+
+
+def test_us0109_probe_acceptance_stage() -> None:
+    """AC-2: acceptance smoke skip when path absent."""
+    scratchpad = {
+        AUTO_SOVEREIGN_SELF_HEALING_DEPLOY_KEY: "1",
+        AUTO_SOVEREIGN_DEPLOY_PROBE_KIND_KEY: "acceptance_smoke",
+        SOVEREIGN_DEPLOY_ACCEPTANCE_SMOKE_PATH_KEY: "nonexistent_path_xyz/",
+    }
+    result = run_acceptance_smoke(scratchpad)
+    assert result.acceptance_status == "skip"
+    assert result.overall == "pass"
+    assert result.reason_code == "DEPLOY_ACCEPTANCE_SMOKE_SKIP_NO_PATH"
+
+
+def test_us0109_retry_loop_bounded() -> None:
+    """AC-3: bounded retry loop caps at AUTO_SOVEREIGN_DEPLOY_RETRY_MAX."""
+    scratchpad = {
+        AUTO_SOVEREIGN_SELF_HEALING_DEPLOY_KEY: "1",
+        AUTO_SOVEREIGN_DEPLOY_RETRY_MAX_KEY: "3",
+    }
+    attempts = 0
+
+    def always_fail(reason: str) -> bool:
+        nonlocal attempts
+        attempts += 1
+        return False
+
+    result = run_deploy_healing_loop(REPO_ROOT, scratchpad, always_fail, story_id="US-0109")
+    assert result.enabled is True
+    assert result.reason_code == ReasonCode.DEPLOY_HEALING_RETRY_CAP_EXHAUSTED.value
+    assert result.retry_count <= 3
+    assert attempts <= 3
+
+
+def test_us0109_deferred_after_cap_exhaustion() -> None:
+    """AC-4: DEPLOY_DEFERRED path after retry cap exhaustion."""
+    from self_healing_deploy_lib import emit_deploy_deferral
+
+    scratchpad = {
+        AUTO_SOVEREIGN_SELF_HEALING_DEPLOY_KEY: "1",
+        AUTO_SOVEREIGN_DEPLOY_RETRY_MAX_KEY: "2",
+    }
+    deferral_id, reason = emit_deploy_deferral(
+        REPO_ROOT,
+        scratchpad,
+        story_id="US-0109",
+        orchestrator_run_id="auto-20260628-04",
+        smoke_summary="smoke probe failed; retry cap exhausted",
+    )
+    allowed = (
+        ReasonCode.DEPLOY_HEALING_DISABLED.value,
+        "SOVEREIGN_LOOP_DISABLED",
+        "",
+    )
+    assert deferral_id is None or reason in allowed
+
+
+def test_us0109_backward_compat_off_path_byte_identical() -> None:
+    """AC-5: AUTO_SOVEREIGN_SELF_HEALING_DEPLOY=0 byte-identical US-0054 path."""
+    scratchpad = {AUTO_SOVEREIGN_SELF_HEALING_DEPLOY_KEY: "0"}
+    probe = run_smoke_probe_chain(scratchpad)
+    assert probe.overall == "pass"
+    assert probe.reason_code == ReasonCode.DEPLOY_HEALING_DISABLED.value
+    assert probe.health_status == "skip"
+    assert probe.acceptance_status == "skip"
+
+    loop_result = run_deploy_healing_loop(
+        REPO_ROOT, scratchpad, lambda reason: False, story_id="US-0109"
+    )
+    assert loop_result.enabled is False
+    assert loop_result.reason_code == ReasonCode.DEPLOY_HEALING_DISABLED.value
+
+
+def test_us0109_validator_cli_self_test() -> None:
+    """AC-6: validator CLI emits [SELF_HEALING_DEPLOY_VALIDATION_OK]."""
+    token = self_test()
+    assert token == "[SELF_HEALING_DEPLOY_VALIDATION_OK]"
+
+
+def test_us0109_reason_codes_section_present() -> None:
+    """AC-8: 8 DEPLOY_HEALING_* reason codes in reason_codes.md."""
+    reason_codes_path = REPO_ROOT / "docs" / "engineering" / "reason_codes.md"
+    assert reason_codes_path.is_file()
+    content = reason_codes_path.read_text(encoding="utf-8")
+    expected_codes = [
+        "DEPLOY_HEALING_DISABLED",
+        "DEPLOY_HEALING_SMOKE_HEALTH_FAIL",
+        "DEPLOY_HEALING_SMOKE_ACCEPTANCE_FAIL",
+        "DEPLOY_HEALING_RETRY_ATTEMPT",
+        "DEPLOY_HEALING_RETRY_CAP_EXHAUSTED",
+        "DEPLOY_HEALING_DEFERRED",
+        "DEPLOY_HEALING_PROBE_TARGET_MISSING",
+        "DEPLOY_HEALING_TIMEOUT",
+    ]
+    for code in expected_codes:
+        assert code in content, f"reason code {code} missing"
+    assert "## US-0109" in content
+
+
+# --- T-007 / T-009: compose guards -------------------------------------------
+
+
+def test_us0109_us0054_compose_no_publish_semantics_change() -> None:
+    """AC-7 compose guard: US-0054 publish targets / confirmation gate UNCHANGED."""
+    lib_path = SCRIPTS_DIR / "self_healing_deploy_lib.py"
+    content = lib_path.read_text(encoding="utf-8")
+    forbidden_tokens = ["RELEASE_PUBLISH_OK", "release_publish", "publish_targets"]
+    for token in forbidden_tokens:
+        assert token not in content, f"US-0054 publish token {token} found in US-0109 lib"
+
+
+def test_us0109_us0100_compose_no_changelog_change() -> None:
+    """AC-7 compose guard: US-0100 changelog / [Unreleased] UNCHANGED."""
+    lib_path = SCRIPTS_DIR / "self_healing_deploy_lib.py"
+    content = lib_path.read_text(encoding="utf-8")
+    forbidden_tokens = ["changelog", "[Unreleased]", "changelog_lib", "version_changelog"]
+    for token in forbidden_tokens:
+        assert token not in content, f"US-0100 changelog token {token} found in US-0109 lib"
+
+
+def test_us0109_us0110_compose_no_convergence_change() -> None:
+    """AC-7 compose guard: US-0110 convergence predicate UNCHANGED."""
+    lib_path = SCRIPTS_DIR / "self_healing_deploy_lib.py"
+    content = lib_path.read_text(encoding="utf-8")
+    forbidden_tokens = ["convergence", "evaluate_convergence", "sovereign_convergence_lib"]
+    for token in forbidden_tokens:
+        assert token not in content, f"US-0110 convergence token {token} found in US-0109 lib"

package/template/tests/us0109_us0110_compose_test.py

@@ -0,0 +1,34 @@
+"""US-0109 compose guard: US-0054 publish semaphore + US-0100 changelog + US-0110 convergence unchanged."""
+from __future__ import annotations
+import sys
+from pathlib import Path
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+def test_us0109_us0054_compose_no_publish_semantics_change() -> None:
+    arch_path = _repo_root() / "docs" / "engineering" / "architecture.md"
+    content = arch_path.read_text(encoding="utf-8")
+    assert "# US-0109" in content
+    us0109_section = content.split("# US-0109")[1] if "# US-0109" in content else ""
+    assert "US-0054" in us0109_section
+    assert "publish" in us0109_section.lower() or "re-enter" in us0109_section.lower()
+
+def test_us0109_us0100_compose_no_changelog_change() -> None:
+    root = _repo_root()
+    scripts_dir = str(root / "scripts")
+    if scripts_dir not in sys.path:
+        sys.path.insert(0, scripts_dir)
+    import self_healing_deploy_lib as mod
+    assert not hasattr(mod, "write_changelog")
+    assert not hasattr(mod, "promote_unreleased")
+
+def test_us0109_us0110_compose_no_convergence_change() -> None:
+    root = _repo_root()
+    scripts_dir = str(root / "scripts")
+    if scripts_dir not in sys.path:
+        sys.path.insert(0, scripts_dir)
+    import self_healing_deploy_lib as mod
+    assert not hasattr(mod, "evaluate_convergence")
+    assert not hasattr(mod, "is_converged")
+    assert not hasattr(mod, "convergence_predicate")