specly 0.1.0__py3-none-any.whl

specly_cli/assets/templates/verification.md

@@ -0,0 +1,44 @@
+# Verification
+
+> **Done checklist.** Validate the implementation against requirements, design, and tasks.
+> Run this after implementation and before marking tasks as complete.
+
+## 1. Requirements Traceability
+
+For each user story in `requirements.md`:
+
+- [ ] All EARS criteria pass (WHEN / IF...THEN / WHILE / WHERE / AS SOON AS)
+- [ ] Ambiguity checklist is resolved
+- [ ] Edge cases are handled (empty state, error state, boundary values)
+
+## 2. Design Compliance
+
+- [ ] Architecture matches `design.md` decisions
+- [ ] Data models match the defined schema
+- [ ] Error handling covers all documented scenarios
+- [ ] Security controls are in place (auth, secrets, data protection)
+- [ ] Tests from design.md pass
+
+## 3. Code Quality
+
+- [ ] No secrets, API keys, or credentials in the code
+- [ ] No debug code, console.log, or TODO left behind
+- [ ] Linter / formatter passes
+- [ ] Diff reviewed and approved
+
+## 4. Task Completion
+
+- [ ] Every task in `tasks.md` is checked and verified
+- [ ] Commits are atomic and follow the project convention
+- [ ] No task was marked done without verification
+
+## 5. Final Sign-Off
+
+- [ ] Build / compilation passes
+- [ ] Tests pass (`npm test` or equivalent)
+- [ ] If applicable: CI pipeline is green
+- [ ] `steering.md` is up to date with any new conventions
+
+---
+
+**Rule:** If any box is unchecked, do not close the feature. Fix it first.

specly_cli/cli.py

@@ -0,0 +1,269 @@
+"""Specly CLI implementation in Python."""
+
+import argparse
+import os
+import re
+import shutil
+import sys
+from typing import List, Optional
+
+from specly_cli.contract import (
+    compute_sha256,
+    load_contract,
+    resolve_artifacts,
+    ContractError,
+)
+from specly_cli.layout import AGENT_KEYS, AGENT_LABELS, detect_agent, resolve_layout, LayoutError
+
+
+def print_help() -> None:
+    agents = ", ".join(AGENT_KEYS)
+    print(f"""
+specly — Spec-Driven Development scaffolding (Python CLI)
+
+Usage:
+  specly [options]
+  specly init [options]
+  specly doctor
+  specly plan <feature>
+  specly verify <feature>
+
+Commands:
+  init                    Create the SDD files (default)
+  doctor                  Check runtime, agent, and template readiness without changing files
+  plan <feature>          Show proposed local writes and effects without executing them
+  verify <feature>        Inspect local artifacts and report observed workflow evidence
+
+Options:
+  -a, --agent <name>      Target agent ({agents})
+  -n, --feature <name>    Feature name (default: starter)
+  -f, --force             Overwrite existing files
+  -l, --list              List supported agents
+  -h, --help              Show this help
+
+Note:
+  run and recover are not supported in the Python CLI.
+""")
+
+
+def print_agents() -> None:
+    print("\nSupported agents:\n")
+    for key in AGENT_KEYS:
+        print(f"  {key.ljust(14)} {AGENT_LABELS.get(key, key)}")
+    print("\nWithout --agent, the CLI auto-detects from project folders.")
+
+
+def run_doctor(root: str) -> int:
+    contract = load_contract()
+    agent = detect_agent(root)
+    py_ver = sys.version_info
+    runtime_ready = py_ver.major == 3 and py_ver.minor >= 10
+
+    artifacts = contract.get("artifacts", [])
+    missing_templates = []
+    for item in artifacts:
+        from specly_cli.contract import get_packaged_template_path
+        tpl_path = get_packaged_template_path(item["template"])
+        if not os.path.exists(tpl_path) or compute_sha256(tpl_path) != item["sha256"]:
+            missing_templates.append(item["id"])
+
+    template_ready = len(missing_templates) == 0
+
+    print("Specly doctor — read-only readiness check (Python)\n")
+    print(f"Runtime:   {'ready' if runtime_ready else 'unsupported'} (Python {sys.version.split()[0]}; requires >=3.10)")
+    print(f"Agent:     ready ({agent}{' fallback' if agent == 'generic' else ' detected'})")
+    print(f"Templates: {'ready' if template_ready else 'incomplete'} ({len(artifacts)} packaged templates verified)")
+    if missing_templates:
+        print(f"Missing:   {', '.join(missing_templates)}")
+
+    return 0 if (runtime_ready and template_ready) else 1
+
+
+def run_plan(feature: str, root: str, agent: Optional[str] = None) -> int:
+    contract = load_contract()
+    if not agent:
+        agent = detect_agent(root)
+    layout = resolve_layout(agent, feature, root, layouts=contract.get("layouts"))
+    artifacts = resolve_artifacts(contract, agent, feature, root)
+
+    print(f"Specly plan — {feature} (read-only; nothing is executed)\n")
+    print(f"Agent: {layout['label']} ({layout['agent']})")
+    print(f"Feature specs: {layout['relativeSpecsDir']}/\n")
+    print("Proposed local file writes:")
+    for art in artifacts:
+        target = art["target_path"]
+        rel = art["relative_target"]
+        state = "preserve existing file" if os.path.exists(target) else "create if init is separately approved"
+        print(f"  {state}: {rel} ({art['file']})")
+
+    print("\nDependency changes: none.")
+    print("External commands: none.")
+    print("Permissions: this plan reads local paths only; a later init would need write access to the listed missing paths.")
+    print("Network, credentials, and IDE launch: none.")
+    return 0
+
+
+def checkbox_state(content: str) -> str:
+    matches = re.findall(r"^\s*- \[([ xX])\]", content, flags=re.MULTILINE)
+    if not matches:
+        return "unavailable"
+    return "passed" if all(m.lower() == "x" for m in matches) else "failed"
+
+
+def run_verify(feature: str, root: str, agent: Optional[str] = None) -> int:
+    contract = load_contract()
+    if not agent:
+        agent = detect_agent(root)
+    layout = resolve_layout(agent, feature, root, layouts=contract.get("layouts"))
+    artifacts = resolve_artifacts(contract, agent, feature, root)
+
+    checks = []
+    tasks_content = ""
+    verification_content = ""
+
+    for art in artifacts:
+        target = art["target_path"]
+        rel = art["relative_target"]
+        if os.path.exists(target):
+            try:
+                with open(target, "r", encoding="utf-8") as f:
+                    content = f.read()
+                checks.append({"label": f"{art['file']} exists and is readable", "status": "passed"})
+                if art["file"] == "tasks.md":
+                    tasks_content = content
+                elif art["file"] == "verification.md":
+                    verification_content = content
+            except Exception:
+                checks.append({"label": f"{art['file']} exists and is readable", "status": "unavailable"})
+        else:
+            checks.append({"label": f"{art['file']} exists and is readable", "status": "failed"})
+
+    checks.append({
+        "label": "tasks.md checklist is complete",
+        "status": checkbox_state(tasks_content) if tasks_content else "unavailable",
+    })
+    checks.append({
+        "label": "verification.md checklist is complete",
+        "status": checkbox_state(verification_content) if verification_content else "unavailable",
+    })
+    checks.append({"label": "requirements/design acceptance evidence", "status": "unavailable"})
+    checks.append({"label": "External test commands", "status": "skipped"})
+
+    counts = {s: sum(1 for c in checks if c["status"] == s) for s in ["passed", "failed", "skipped", "unavailable"]}
+
+    print(f"Specly verify — {feature} (read-only; no commands run)\n")
+    print(f"Agent: {layout['label']} ({layout['agent']})")
+    for check in checks:
+        print(f"  {check['status'].upper().ljust(11)} {check['label']}")
+    print(
+        f"\nSummary: {counts['passed']} passed, {counts['failed']} failed, {counts['skipped']} skipped, {counts['unavailable']} unavailable."
+    )
+    print("Progress is read from durable tasks.md checkboxes. This report is not persisted; acceptance evidence requires project-specific checks.")
+    return 0
+
+
+def run_init(agent: Optional[str], feature: str, force: bool, root: str) -> int:
+    contract = load_contract()
+    if not agent:
+        agent = detect_agent(root)
+    layout = resolve_layout(agent, feature, root, layouts=contract.get("layouts"))
+    artifacts = resolve_artifacts(contract, agent, feature, root)
+
+    print(f"\n🤖 Agent:  {layout['label']} ({layout['agent']})")
+    print(f"📂 Feature: {layout['feature']}")
+    print(f"📁 Specs:   {layout['relativeSpecsDir']}/\n")
+
+    created = 0
+    for art in artifacts:
+        target = art["target_path"]
+        template = art["template_path"]
+        rel = art["relative_target"]
+
+        os.makedirs(os.path.dirname(target), exist_ok=True)
+
+        if os.path.exists(target) and not force:
+            existing_sha = compute_sha256(target)
+            if existing_sha == art["sha256"]:
+                print(f"⚠️  Already exists, skipping: {rel}")
+            else:
+                print(f"⚠️  File differs from template, skipping without --force: {rel}")
+            continue
+
+        shutil.copyfile(template, target)
+        print(f"✅ Created: {rel}")
+        created += 1
+
+    print("\n🚀 SDD initialized.")
+    print(f"   Start with: {layout['relativeSpecsDir']}/requirements.md")
+    if not layout["steeringInSpecs"]:
+        print(f"   Context:    {os.path.relpath(layout['steeringDir'], root)}/steering.md")
+    print(f"   Guide:      {os.path.relpath(layout['agentDir'], root)}/how-to-use.md")
+    return 0
+
+
+def main(argv: Optional[List[str]] = None, root: Optional[str] = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    if root is None:
+        root = os.getcwd()
+
+    if not argv:
+        command = "init"
+        cmd_args = []
+    elif argv[0] in ["init", "doctor", "plan", "verify", "run", "recover"]:
+        command = argv[0]
+        cmd_args = argv[1:]
+    elif argv[0].startswith("-"):
+        command = "init"
+        cmd_args = argv
+    else:
+        # Check for unknown command
+        print(f"Error: Unknown command '{argv[0]}'", file=sys.stderr)
+        print_help()
+        sys.exit(1)
+
+    if command in ["run", "recover"]:
+        print(
+            f"Error: 'specly {command}' is not supported in the Python CLI distribution.\n"
+            "Action execution and recovery are currently provided by the Node CLI (npx specly).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if command == "doctor":
+        if "--help" in cmd_args or "-h" in cmd_args:
+            print("Usage: specly doctor\n\nChecks runtime, agent, and template readiness without writing files.")
+            return 0
+        return run_doctor(root)
+
+    if command == "plan":
+        if not cmd_args or cmd_args[0].startswith("-"):
+            print("Usage: specly plan <feature>", file=sys.stderr)
+            sys.exit(1)
+        feature = cmd_args[0]
+        return run_plan(feature, root)
+
+    if command == "verify":
+        if not cmd_args or cmd_args[0].startswith("-"):
+            print("Usage: specly verify <feature>", file=sys.stderr)
+            sys.exit(1)
+        feature = cmd_args[0]
+        return run_verify(feature, root)
+
+    # init command parsing
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("-a", "--agent", dest="agent", default=None)
+    parser.add_argument("-n", "--feature", "--name", dest="feature", default="starter")
+    parser.add_argument("-f", "--force", dest="force", action="store_true")
+    parser.add_argument("-l", "--list", dest="list", action="store_true")
+    parser.add_argument("-h", "--help", dest="help", action="store_true")
+
+    parsed, remaining = parser.parse_known_args(cmd_args)
+    if parsed.help:
+        print_help()
+        return 0
+    if parsed.list:
+        print_agents()
+        return 0
+
+    return run_init(parsed.agent, parsed.feature, parsed.force, root)

specly_cli/contract.py

@@ -0,0 +1,100 @@
+"""Contract loading, validation, and artifact resolution."""
+
+import hashlib
+import json
+import os
+from typing import Any, Dict, List
+
+from specly_cli.layout import resolve_layout
+
+ASSETS_DIR = os.path.join(os.path.dirname(__file__), "assets")
+DEFAULT_CONTRACT_PATH = os.path.join(ASSETS_DIR, "artifact-contract-v1.json")
+
+
+class ContractError(Exception):
+    """Raised when artifact contract validation or template fingerprint fails."""
+    pass
+
+
+def load_contract(path: str = DEFAULT_CONTRACT_PATH) -> Dict[str, Any]:
+    """Load contract JSON file."""
+    if not os.path.exists(path):
+        raise ContractError(f"Contract file not found: {path}")
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    validate_contract(data)
+    return data
+
+
+def validate_contract(data: Dict[str, Any]) -> None:
+    """Validate contract name, schema version, and structure."""
+    if data.get("contract") != "specly-generated-artifacts":
+        raise ContractError(f"Unsupported contract name: {data.get('contract')}")
+    if data.get("schemaVersion") != 1:
+        raise ContractError(f"Unsupported contract schema version: {data.get('schemaVersion')}")
+    if "artifacts" not in data or "layouts" not in data:
+        raise ContractError("Invalid contract: missing 'artifacts' or 'layouts' sections")
+
+
+def get_packaged_template_path(template_name: str) -> str:
+    """Resolve packaged template path within assets directory."""
+    # Maps src/templates/foo.md -> assets/templates/foo.md
+    # Maps how-to-use.md -> assets/how-to-use.md
+    basename = os.path.basename(template_name)
+    if "templates" in template_name:
+        path = os.path.join(ASSETS_DIR, "templates", basename)
+    else:
+        path = os.path.join(ASSETS_DIR, basename)
+    return path
+
+
+def compute_sha256(file_path: str) -> str:
+    """Calculate SHA-256 hex digest of file."""
+    h = hashlib.sha256()
+    with open(file_path, "rb") as f:
+        while chunk := f.read(8192):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def resolve_artifacts(contract: Dict[str, Any], agent: str, feature: str, root: str) -> List[Dict[str, Any]]:
+    """Resolve and verify all artifacts for an agent layout and feature."""
+    validate_contract(contract)
+    layout = resolve_layout(agent, feature, root, layouts=contract.get("layouts"))
+    artifacts_result = []
+
+    for item in contract.get("artifacts", []):
+        artifact_id = item["id"]
+        dir_key = item["directory"]
+        file_name = item["file"]
+        expected_sha = item["sha256"]
+        template_ref = item["template"]
+
+        dir_path = layout.get(dir_key)
+        if not dir_path:
+            raise ContractError(f"Layout does not define directory key '{dir_key}' for artifact '{artifact_id}'")
+
+        target_file = os.path.join(dir_path, file_name)
+        template_file = get_packaged_template_path(template_ref)
+
+        if not os.path.exists(template_file):
+            raise ContractError(f"Packaged template missing for {artifact_id}: {template_file}")
+
+        actual_sha = compute_sha256(template_file)
+        if actual_sha != expected_sha:
+            raise ContractError(
+                f"Packaged template fingerprint mismatch for {artifact_id}: expected {expected_sha}, got {actual_sha}"
+            )
+
+        artifacts_result.append({
+            "id": artifact_id,
+            "role": item.get("role", ""),
+            "file": file_name,
+            "target_path": target_file,
+            "relative_target": os.path.relpath(target_file, root),
+            "template_path": template_file,
+            "sha256": expected_sha,
+            "ownership": item.get("ownership", "user"),
+        })
+
+    return artifacts_result

specly_cli/layout.py

@@ -0,0 +1,106 @@
+"""Layout detection and resolution for supported agent configurations."""
+
+import os
+import re
+
+AGENT_KEYS = ["generic", "cursor", "kiro", "vscode", "antigravity", "windsurf", "claude"]
+
+AGENT_LABELS = {
+    "generic": "Generic",
+    "cursor": "Cursor",
+    "kiro": "Kiro",
+    "vscode": "VS Code / Copilot",
+    "antigravity": "Antigravity",
+    "windsurf": "Windsurf",
+    "claude": "Claude Code",
+}
+
+FEATURE_REGEX = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]*$")
+
+
+class LayoutError(Exception):
+    """Raised when layout resolution or safety checks fail."""
+    pass
+
+
+def detect_agent(root: str) -> str:
+    """Detect agent from existing project markers in root."""
+    if os.path.exists(os.path.join(root, ".cursor")):
+        return "cursor"
+    if os.path.exists(os.path.join(root, ".kiro")):
+        return "kiro"
+    if os.path.exists(os.path.join(root, ".vscode")) or os.path.exists(
+        os.path.join(root, ".github", "copilot-instructions.md")
+    ):
+        return "vscode"
+    if os.path.exists(os.path.join(root, ".agent")) or os.path.exists(
+        os.path.join(root, ".antigravity")
+    ):
+        return "antigravity"
+    if os.path.exists(os.path.join(root, ".windsurf")):
+        return "windsurf"
+    if os.path.exists(os.path.join(root, "CLAUDE.md")) or os.path.exists(
+        os.path.join(root, ".claude")
+    ):
+        return "claude"
+    return "generic"
+
+
+def resolve_layout(agent: str, feature: str, root: str, layouts: dict = None) -> dict:
+    """Resolve and validate layout paths for an agent and feature."""
+    if not feature or not FEATURE_REGEX.match(feature) or ".." in feature or "/" in feature or "\\" in feature:
+        raise LayoutError(f"Invalid or unsafe feature name: {feature!r}")
+
+    if not agent:
+        agent = detect_agent(root)
+    elif agent not in AGENT_KEYS:
+        raise LayoutError(f"Unknown agent: {agent!r}")
+
+    # Default layout mappings conforming to artifact-contract-v1
+    layout_defs = layouts or {
+        "generic": {"specsDir": "specs", "steeringDir": "specs", "agentDir": "specs"},
+        "cursor": {"specsDir": ".cursor/specs/{feature}", "steeringDir": ".cursor", "agentDir": ".cursor"},
+        "kiro": {"specsDir": ".kiro/specs/{feature}", "steeringDir": ".kiro", "agentDir": ".kiro"},
+        "vscode": {"specsDir": ".vscode/specs/{feature}", "steeringDir": ".vscode", "agentDir": ".vscode"},
+        "antigravity": {"specsDir": ".agent/specs/{feature}", "steeringDir": ".agent", "agentDir": ".agent"},
+        "windsurf": {"specsDir": ".windsurf/specs/{feature}", "steeringDir": ".windsurf", "agentDir": ".windsurf"},
+        "claude": {"specsDir": ".claude/specs/{feature}", "steeringDir": ".claude", "agentDir": ".claude"},
+    }
+
+    if agent not in layout_defs:
+        raise LayoutError(f"Layout definition missing for agent: {agent}")
+
+    conf = layout_defs[agent]
+    real_root = os.path.realpath(root)
+
+    resolved = {
+        "agent": agent,
+        "label": AGENT_LABELS.get(agent, agent.title()),
+        "feature": feature,
+        "specsDir": os.path.join(root, conf["specsDir"].replace("{feature}", feature)),
+        "steeringDir": os.path.join(root, conf["steeringDir"]),
+        "agentDir": os.path.join(root, conf["agentDir"]),
+        "relativeSpecsDir": conf["specsDir"].replace("{feature}", feature),
+        "steeringInSpecs": conf["steeringDir"] == conf["specsDir"].replace("{feature}", feature),
+    }
+
+    # Safety checks: ensure resolved paths are inside root and no symlink escapes root
+    for key in ["specsDir", "steeringDir", "agentDir"]:
+        target_path = resolved[key]
+        rel = os.path.relpath(target_path, root)
+        if rel.startswith("..") or os.path.isabs(rel):
+            raise LayoutError(f"Path escape detected in layout for {key}: {target_path}")
+
+        # Check existing parent or target if it's a symlink pointing outside root
+        curr = target_path
+        while curr and curr != root:
+            if os.path.islink(curr):
+                link_dest = os.path.realpath(curr)
+                if not (link_dest == real_root or link_dest.startswith(real_root + os.sep)):
+                    raise LayoutError(f"Symlink escape detected: {curr} points to {link_dest}")
+            parent = os.path.dirname(curr)
+            if parent == curr:
+                break
+            curr = parent
+
+    return resolved

specly_cli/optional/__init__.py

@@ -0,0 +1 @@
+"""Optional adapters for Specly CLI."""

specly_cli/optional/ax_adapter.py

@@ -0,0 +1,160 @@
+"""Optional Google AX cluster adapter for offline diagnostics and effect preview."""
+
+from dataclasses import dataclass, field
+import datetime
+import hashlib
+import json
+import shutil
+from typing import Any, Callable, Dict, List, Optional
+
+AX_COMPATIBILITY_STATUS = "unverified"
+AX_DOCUMENTED_EVIDENCE = (
+    "Google AX (github.com/google/ax) prerelease. Local prerequisites: kubectl, ko, go, container registry."
+)
+REQUIRED_PREREQUISITES = ["kubectl", "ko", "go"]
+
+
+class AxAdapterError(Exception):
+    """Raised when AX validation, prerequisite checks, or approval matching fails."""
+    pass
+
+
+@dataclass
+class AxPrerequisiteResult:
+    prerequisites: Dict[str, bool]
+    missing: List[str]
+    ready: bool
+    actionable_diagnostic: str
+    compatibility_status: str = AX_COMPATIBILITY_STATUS
+
+
+@dataclass
+class AxPreview:
+    cluster_context: str
+    namespace: str
+    operation: str
+    resource_targets: List[str]
+    proposed_effects: List[str]
+    compatibility_evidence: str
+    approval_digest: str
+    created_at: str
+    is_mutation: bool
+
+
+def check_prerequisites(binaries_checker: Optional[Callable[[str], bool]] = None) -> AxPrerequisiteResult:
+    """Check local required binaries without cluster probing or credential inspection."""
+    checker = binaries_checker or (lambda name: shutil.which(name) is not None)
+    results = {}
+    missing = []
+
+    for name in REQUIRED_PREREQUISITES:
+        found = bool(checker(name))
+        results[name] = found
+        if not found:
+            missing.append(name)
+
+    ready = len(missing) == 0
+    if ready:
+        diag = "All local AX prerequisites detected (kubectl, ko, go). Cluster status remains unverified."
+    else:
+        missing_str = ", ".join(missing)
+        diag = (
+            f"Actionable prerequisite blockers: missing [{missing_str}]. "
+            "Install required tooling before attempting AX operations."
+        )
+
+    return AxPrerequisiteResult(
+        prerequisites=results,
+        missing=missing,
+        ready=ready,
+        actionable_diagnostic=diag,
+        compatibility_status=AX_COMPATIBILITY_STATUS,
+    )
+
+
+def compute_preview_digest(
+    cluster_context: str,
+    namespace: str,
+    operation: str,
+    resource_targets: List[str],
+    proposed_effects: List[str],
+    compatibility_evidence: str,
+) -> str:
+    payload = {
+        "cluster_context": cluster_context,
+        "namespace": namespace,
+        "operation": operation,
+        "resource_targets": sorted(resource_targets),
+        "proposed_effects": sorted(proposed_effects),
+        "compatibility_evidence": compatibility_evidence,
+    }
+    return hashlib.sha256(json.dumps(payload, sort_keys=True).encode("utf-8")).hexdigest()
+
+
+def generate_ax_preview(
+    cluster_context: str,
+    namespace: str,
+    operation: str,
+    resource_targets: List[str],
+    proposed_effects: List[str],
+    compatibility_evidence: str = AX_DOCUMENTED_EVIDENCE,
+) -> AxPreview:
+    """Generate read-only immutable effect preview and approval digest."""
+    digest = compute_preview_digest(
+        cluster_context=cluster_context,
+        namespace=namespace,
+        operation=operation,
+        resource_targets=resource_targets,
+        proposed_effects=proposed_effects,
+        compatibility_evidence=compatibility_evidence,
+    )
+    is_mutation = operation.lower() in {"apply", "create", "delete", "update", "patch"}
+    created_at = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+    return AxPreview(
+        cluster_context=cluster_context,
+        namespace=namespace,
+        operation=operation,
+        resource_targets=resource_targets,
+        proposed_effects=proposed_effects,
+        compatibility_evidence=compatibility_evidence,
+        approval_digest=digest,
+        created_at=created_at,
+        is_mutation=is_mutation,
+    )
+
+
+def submit_ax_operation(
+    preview: AxPreview,
+    approval_digest: str,
+    destination_auth: Dict[str, str],
+    submit_fn: Optional[Callable[[AxPreview], Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """Submit an AX cluster operation after explicit approval bound to the preview."""
+    if not approval_digest:
+        raise AxAdapterError("Approval digest required: cluster submission requires affirmative approval.")
+
+    if approval_digest != preview.approval_digest:
+        raise AxAdapterError(
+            f"Approval digest mismatch: expected {preview.approval_digest}, got {approval_digest}. "
+            "A fresh preview and approval are required."
+        )
+
+    required_auth_keys = {"destination", "operation", "credential_session"}
+    if not required_auth_keys.issubset(destination_auth.keys()) or not all(
+        destination_auth[k] for k in required_auth_keys
+    ):
+        raise AxAdapterError(
+            f"Missing explicit authorization: must provide destination, operation, and credential_session. "
+            f"Provided keys: {list(destination_auth.keys())}"
+        )
+
+    if submit_fn:
+        return submit_fn(preview)
+
+    # Offline / unverified default: do not contact real cluster
+    return {
+        "status": "dry_run_recorded",
+        "digest": preview.approval_digest,
+        "message": "Operation approved and recorded. Real cluster submission requires external provider session.",
+    }