From 795d432f078bfd0e883b0be6a634be4ba730bbc1 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 15 May 2026 11:51:38 -0400
Subject: [PATCH 01/64] feat(otdf-local): multi-instance test environments
 (DSPX-3302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refactors otdf-local from a single-instance CLI (one platform checkout,
fixed ports, hardcoded six KAS instances) into a multi-instance harness
where each named instance under tests/instances/<name>/ owns its own
opentdf.yaml, keys, KAS configs, and port range.

Why
---

A single bug report often describes a *combination* — platform v0.9.0
with Java SDK 0.7.8 and a KAS at a pre-release. Today a developer has
to hand-edit configs and re-checkout the platform to reproduce. After
this change:

  otdf-local instance init java-078 --from-scenario .../scenario.yaml
  otdf-local --instance java-078 up

brings up exactly the topology the scenario describes, using platform
binaries that otdf-sdk-mgr already provisioned (each instance, and each
KAS within an instance, can reference a different pinned version). Two
instances on disjoint ports.base can coexist on a developer laptop.

What changes
------------

otdf-local now depends on otdf-sdk-mgr via a uv path source so both
tools share the canonical Scenario/Instance schema.

Settings (otdf_local.config.settings):
  - New instance_name (env-overridable via OTDF_LOCAL_INSTANCE_NAME),
    instance_dir, instances_root, instance_yaml properties.
  - platform_dir becomes optional; legacy sibling-discovery only kicks
    in when no per-instance configuration is present.
  - platform_binary_for(dist) resolves to the otdf-sdk-mgr-managed
    xtest/platform/dist/<dist>/service binary.
  - keys_dir, logs_dir, config_dir, platform_config, and
    get_kas_config_path switch to per-instance paths whenever
    instance.yaml exists; legacy behavior is preserved otherwise.
  - load_instance() reads the per-instance manifest via the shared
    Pydantic model.

Ports (otdf_local.config.ports):
  - KAS_OFFSETS exposes the offset table (alpha=+101, beta=+202, ...,
    km2=+606) so multiple instances on different bases get disjoint
    port ranges. The legacy 8080-based constants are preserved as
    defaults.
  - get_kas_port(name, base=...) computes the port relative to base.

Services (otdf_local.services.platform / .kas):
  - PlatformService.start() and KASService.start() use the pinned dist
    binary at xtest/platform/dist/<dist>/service when an instance is
    loaded, with cwd set to the recorded worktree so the binary finds
    its embedded resources. Legacy `go run ./service` path runs
    unchanged when no instance is active.
  - KASService.is_key_management defers to the manifest's `mode` field
    instead of the legacy name-based heuristic; per-KAS features (e.g.
    ec_tdf_enabled) pass through to opentdf.yaml.
  - KASManager constructs only the KAS instances listed in
    instance.yaml's kas: map. start_standard / start_km filter on
    is_key_management so subset topologies still work.

utils.keys.setup_golden_keys:
  - Writes key files into the target directory (per-instance keys_dir
    or legacy platform_dir) and uses absolute paths in the generated
    keys_config so the binary finds them regardless of cwd.

CLI:
  - New top-level --instance option threads through every command via
    OTDF_LOCAL_INSTANCE_NAME.
  - New `instance` subcommand group: init [--from-scenario PATH],
    ls --json, rm.
  - New `scenario` subcommand: `run <path>` translates the scenario's
    suite block into `pytest --sdks-encrypt ... --sdks-decrypt ...
    --containers ...` under xtest/ with OTDF_LOCAL_INSTANCE_NAME set.

Tests (otdf-local/tests/test_multi_instance.py):
  - Port arithmetic at default and alternate bases.
  - Settings round-trip with and without an instance.yaml.
  - platform_binary_for resolves under the otdf-sdk-mgr-managed
    xtest/platform/ tree.

.gitignore additions:
  - tests/instances/ (per-instance config and logs)
  - xtest/scenarios/*.installed.json (provisioning records)
  - .claude/tmp/

Backward compatibility:
  - `otdf-local up` with no --instance flag keeps working against a
    sibling platform/ checkout.

Refs: https://virtru.atlassian.net/browse/DSPX-3302

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .gitignore                                    |   7 +
 otdf-local/pyproject.toml                     |   4 +
 otdf-local/src/otdf_local/cli.py              |  28 ++-
 otdf-local/src/otdf_local/cli_instance.py     | 183 ++++++++++++++++++
 otdf-local/src/otdf_local/cli_scenario.py     | 101 ++++++++++
 otdf-local/src/otdf_local/config/ports.py     |  30 ++-
 otdf-local/src/otdf_local/config/settings.py  | 116 +++++++++--
 otdf-local/src/otdf_local/services/kas.py     | 115 +++++++----
 .../src/otdf_local/services/platform.py       |  69 +++++--
 otdf-local/src/otdf_local/utils/keys.py       |  10 +-
 otdf-local/tests/test_multi_instance.py       |  78 ++++++++
 otdf-local/uv.lock                            |  69 ++++++-
 12 files changed, 739 insertions(+), 71 deletions(-)
 create mode 100644 otdf-local/src/otdf_local/cli_instance.py
 create mode 100644 otdf-local/src/otdf_local/cli_scenario.py
 create mode 100644 otdf-local/tests/test_multi_instance.py

diff --git a/.gitignore b/.gitignore
index a1bb32382..6fa376ceb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,3 +32,10 @@ xtest/sdk/java/cmdline.jar
 /xtest/otdfctl/
 
 /tmp/
+
+# Multi-instance test harness state (DSPX-3302). Per-instance config, logs, and
+# keys live under tests/instances/; otdf-sdk-mgr install scenario writes
+# .installed.json next to each scenarios.yaml.
+/instances/
+xtest/scenarios/*.installed.json
+.claude/tmp/
diff --git a/otdf-local/pyproject.toml b/otdf-local/pyproject.toml
index fc3d08bc8..7800389a0 100644
--- a/otdf-local/pyproject.toml
+++ b/otdf-local/pyproject.toml
@@ -6,12 +6,16 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "httpx>=0.27.0",
+    "otdf-sdk-mgr",
     "pydantic-settings>=2.14.1",
     "rich>=15.0.0",
     "ruamel.yaml>=0.18.0",
     "typer>=0.26.5",
 ]
 
+[tool.uv.sources]
+otdf-sdk-mgr = { path = "../otdf-sdk-mgr", editable = true }
+
 [dependency-groups]
 dev = [
     "pyright>=1.1.410",
diff --git a/otdf-local/src/otdf_local/cli.py b/otdf-local/src/otdf_local/cli.py
index d8e3597ff..422daa65a 100644
--- a/otdf-local/src/otdf_local/cli.py
+++ b/otdf-local/src/otdf_local/cli.py
@@ -1,10 +1,12 @@
 """Typer CLI for otdf_local - OpenTDF test environment management."""
 
 import json
+import os
 import shutil
 import sys
 import time
-from typing import Annotated
+from pathlib import Path
+from typing import Annotated, Optional
 
 import httpx
 import typer
@@ -44,6 +46,18 @@
 )
 
 
+def _register_subapps() -> None:
+    """Defer imports so the schema dependency only loads when needed."""
+    from otdf_local.cli_instance import instance_app
+    from otdf_local.cli_scenario import scenario_app
+
+    app.add_typer(instance_app, name="instance")
+    app.add_typer(scenario_app, name="scenario")
+
+
+_register_subapps()
+
+
 def _show_provision_error(result: ProvisionResult, target: str) -> None:
     """Display provisioning error with stderr details."""
     print_error(f"{target} provisioning failed (exit code {result.return_code})")
@@ -75,9 +89,19 @@ def main(
             is_eager=True,
         ),
     ] = False,
+    instance: Annotated[
+        Optional[str],
+        typer.Option(
+            "--instance",
+            help='Named instance under tests/instances/. Defaults to "default" (or $OTDF_LOCAL_INSTANCE_NAME).',
+        ),
+    ] = None,
 ) -> None:
     """OpenTDF test environment management CLI."""
-    pass
+    if instance is not None:
+        os.environ["OTDF_LOCAL_INSTANCE_NAME"] = instance
+        # Invalidate the cached Settings so subsequent commands see the new value
+        get_settings.cache_clear()
 
 
 @app.command()
diff --git a/otdf-local/src/otdf_local/cli_instance.py b/otdf-local/src/otdf_local/cli_instance.py
new file mode 100644
index 000000000..98407f56e
--- /dev/null
+++ b/otdf-local/src/otdf_local/cli_instance.py
@@ -0,0 +1,183 @@
+"""`otdf-local instance` subcommands: init / ls / rm."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from otdf_sdk_mgr.schema import Instance, Metadata, PlatformPin, PortsConfig, dump_instance
+
+from otdf_local.config.settings import get_settings
+
+instance_app = typer.Typer(help="Manage named test environment instances.")
+
+
+@instance_app.command("init")
+def init(
+    name: Annotated[str, typer.Argument(help="Instance name (used as directory name)")],
+    from_scenario: Annotated[
+        Optional[Path],
+        typer.Option("--from-scenario", help="Initialize from a scenarios.yaml or instance.yaml"),
+    ] = None,
+    ports_base: Annotated[
+        int,
+        typer.Option("--ports-base", help="Base port (KAS ports computed as base+N*101)"),
+    ] = 8080,
+    platform_dist: Annotated[
+        Optional[str],
+        typer.Option("--platform", help="Platform dist version (e.g., v0.9.0)"),
+    ] = None,
+) -> None:
+    """Scaffold a new instance directory at tests/instances/<name>/."""
+    settings = get_settings()
+    instance_dir = settings.instances_root / name
+
+    if from_scenario is not None:
+        _init_from_scenario(name, from_scenario, instance_dir)
+    else:
+        if platform_dist is None:
+            typer.echo("Error: --platform <dist> is required when not using --from-scenario", err=True)
+            raise typer.Exit(2)
+        _init_minimal(name, instance_dir, ports_base, platform_dist)
+
+    _validate_port_uniqueness(settings.instances_root, name)
+    typer.echo(f"  Initialized instance '{name}' at {instance_dir}")
+
+
+def _init_from_scenario(name: str, scenario_path: Path, instance_dir: Path) -> None:
+    """Copy the embedded Instance from a Scenario or load a standalone Instance."""
+    from otdf_sdk_mgr.schema import load_instance, load_scenario
+    from ruamel.yaml import YAML
+
+    y = YAML(typ="safe")
+    raw = y.load(scenario_path.read_text())
+    if not isinstance(raw, dict):
+        raise typer.BadParameter(f"{scenario_path} top-level YAML must be a mapping")
+    kind = raw.get("kind")
+    if kind == "Scenario":
+        scenario = load_scenario(scenario_path)
+        instance = scenario.instance
+    elif kind == "Instance":
+        instance = load_instance(scenario_path)
+    else:
+        raise typer.BadParameter(f"{scenario_path} has unknown kind {kind!r}")
+    # Ensure the metadata name matches the chosen directory name.
+    instance.metadata = Metadata(**{**instance.metadata.model_dump(exclude_none=True), "name": name})
+    instance_dir.mkdir(parents=True, exist_ok=True)
+    (instance_dir / "kas").mkdir(parents=True, exist_ok=True)
+    (instance_dir / "keys").mkdir(mode=0o700, parents=True, exist_ok=True)
+    (instance_dir / "logs").mkdir(parents=True, exist_ok=True)
+    dump_instance(instance, instance_dir / "instance.yaml")
+
+
+def _init_minimal(name: str, instance_dir: Path, ports_base: int, platform_dist: str) -> None:
+    """Create a barebones instance.yaml with default KAS layout."""
+    instance = Instance(
+        metadata=Metadata(name=name),
+        platform=PlatformPin(dist=platform_dist),
+        ports=PortsConfig(base=ports_base),
+        kas={},
+    )
+    instance_dir.mkdir(parents=True, exist_ok=True)
+    (instance_dir / "kas").mkdir(parents=True, exist_ok=True)
+    (instance_dir / "keys").mkdir(mode=0o700, parents=True, exist_ok=True)
+    (instance_dir / "logs").mkdir(parents=True, exist_ok=True)
+    dump_instance(instance, instance_dir / "instance.yaml")
+
+
+def _validate_port_uniqueness(instances_root: Path, new_name: str) -> None:
+    """Warn if another instance shares the same `ports.base`."""
+    from otdf_sdk_mgr.schema import load_instance
+
+    new_yaml = instances_root / new_name / "instance.yaml"
+    if not new_yaml.exists():
+        return
+    new_inst = load_instance(new_yaml)
+    new_base = new_inst.ports.base
+    if not instances_root.exists():
+        return
+    for child in instances_root.iterdir():
+        if not child.is_dir() or child.name == new_name:
+            continue
+        other_yaml = child / "instance.yaml"
+        if not other_yaml.is_file():
+            continue
+        try:
+            other = load_instance(other_yaml)
+        except Exception:
+            continue
+        if other.ports.base == new_base:
+            typer.echo(
+                f"  Warning: instance '{child.name}' already uses ports.base={new_base}; "
+                f"running both simultaneously will collide. Change one with `otdf-local instance init`.",
+                err=True,
+            )
+
+
+@instance_app.command("ls")
+def ls(
+    as_json: Annotated[bool, typer.Option("--json", "-j", help="Emit JSON")] = False,
+) -> None:
+    """List known instances."""
+    import json as _json
+
+    from otdf_sdk_mgr.schema import load_instance
+
+    settings = get_settings()
+    root = settings.instances_root
+    if not root.exists():
+        if as_json:
+            typer.echo(_json.dumps([]))
+        else:
+            typer.echo("  (no instances yet)")
+        return
+    rows: list[dict[str, object]] = []
+    for child in sorted(root.iterdir()):
+        if not child.is_dir():
+            continue
+        ymp = child / "instance.yaml"
+        if not ymp.is_file():
+            continue
+        try:
+            inst = load_instance(ymp)
+        except Exception as e:
+            rows.append({"name": child.name, "error": str(e)})
+            continue
+        rows.append(
+            {
+                "name": child.name,
+                "platform": (
+                    inst.platform.dist
+                    or (inst.platform.source.ref if inst.platform.source else inst.platform.image)
+                ),
+                "ports_base": inst.ports.base,
+                "kas": list(inst.kas.keys()),
+            }
+        )
+    if as_json:
+        typer.echo(_json.dumps(rows, indent=2))
+    else:
+        for row in rows:
+            typer.echo(f"  {row}")
+
+
+@instance_app.command("rm")
+def rm(
+    name: Annotated[str, typer.Argument(help="Instance to remove")],
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Skip confirmation")] = False,
+) -> None:
+    """Remove an instance directory."""
+    settings = get_settings()
+    instance_dir = settings.instances_root / name
+    if not instance_dir.exists():
+        typer.echo(f"Error: instance '{name}' not found at {instance_dir}", err=True)
+        raise typer.Exit(1)
+    if not yes:
+        confirm = typer.confirm(f"Delete {instance_dir}?", default=False)
+        if not confirm:
+            typer.echo("aborted")
+            raise typer.Exit(1)
+    shutil.rmtree(instance_dir)
+    typer.echo(f"  Removed {instance_dir}")
diff --git a/otdf-local/src/otdf_local/cli_scenario.py b/otdf-local/src/otdf_local/cli_scenario.py
new file mode 100644
index 000000000..7d1dfde30
--- /dev/null
+++ b/otdf-local/src/otdf_local/cli_scenario.py
@@ -0,0 +1,101 @@
+"""`otdf-local scenario` subcommands.
+
+Today's surface area is intentionally narrow — `run` is the only command
+that's part of the bug-repro MVP. Bisect and other higher-level loops are
+deferred (see plan §9).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from otdf_sdk_mgr.schema import (
+    Scenario,
+    installed_json_for,
+    load_scenario,
+    scenario_to_pytest_sdks,
+)
+
+from otdf_local.config.settings import get_settings
+
+scenario_app = typer.Typer(help="Run scenarios.yaml against a healthy instance.")
+
+
+def _build_pytest_args(scenario: Scenario, scenario_path: Path) -> list[str]:
+    """Translate the scenario's `suite` block into pytest CLI args.
+
+    SDK pins go through `scenario_to_pytest_sdks` so they're forwarded as
+    the `sdk@<resolved-dist>` tokens xtest's #446 specifier format expects.
+    Requires that `otdf-sdk-mgr install scenario` has been run first; the
+    helper raises FileNotFoundError with a clean hint otherwise.
+    """
+    suite = scenario.suite
+    args: list[str] = [suite.select]
+
+    tokens = scenario_to_pytest_sdks(scenario, installed_json_for(scenario_path))
+    if tokens["encrypt"]:
+        args.extend(["--sdks-encrypt", " ".join(tokens["encrypt"])])
+    if tokens["decrypt"]:
+        args.extend(["--sdks-decrypt", " ".join(tokens["decrypt"])])
+    if suite.containers:
+        args.extend(["--containers", suite.containers])
+    if suite.markers:
+        args.extend(["-m", suite.markers])
+    args.extend(suite.extra_args)
+    return args
+
+
+@scenario_app.command("run")
+def run(
+    path: Annotated[Path, typer.Argument(help="Path to scenarios.yaml")],
+    instance: Annotated[
+        str | None,
+        typer.Option(
+            "--instance",
+            help="Override which instance to use (defaults to scenario.instance.metadata.name)",
+        ),
+    ] = None,
+    extra: Annotated[
+        list[str] | None,
+        typer.Argument(help="Extra args passed through to pytest (after --)"),
+    ] = None,
+) -> None:
+    """Run the pytest suite declared by the scenario against its instance."""
+    if not path.exists():
+        typer.echo(f"Error: {path} not found", err=True)
+        raise typer.Exit(1)
+
+    scenario = load_scenario(path)
+    instance_name = instance or scenario.instance.metadata.name
+    if not instance_name:
+        typer.echo("Error: scenario.instance.metadata.name not set; pass --instance", err=True)
+        raise typer.Exit(2)
+
+    settings = get_settings()
+    # Force the chosen instance via env so child pytest invocations agree.
+    os.environ["OTDF_LOCAL_INSTANCE_NAME"] = instance_name
+
+    xtest_root = settings.xtest_root
+    if not xtest_root.exists():
+        typer.echo(f"Error: xtest root not found at {xtest_root}", err=True)
+        raise typer.Exit(1)
+
+    try:
+        pytest_args = _build_pytest_args(scenario, path)
+    except FileNotFoundError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    if extra:
+        pytest_args.extend(extra)
+
+    cmd = ["uv", "run", "pytest", *pytest_args]
+    typer.echo(f"  Running: {' '.join(cmd)} (cwd={xtest_root})")
+    completed = subprocess.run(cmd, cwd=xtest_root)
+    raise typer.Exit(completed.returncode)
diff --git a/otdf-local/src/otdf_local/config/ports.py b/otdf-local/src/otdf_local/config/ports.py
index 21d193358..913f970d0 100644
--- a/otdf-local/src/otdf_local/config/ports.py
+++ b/otdf-local/src/otdf_local/config/ports.py
@@ -33,14 +33,40 @@ class Ports:
         "km2": "KAS_KM2",
     }
 
+    # Offset of each KAS port from `base` (which is the platform port).
+    # The defaults at base=8080 reproduce the historical 8181/8282/... layout.
+    KAS_OFFSETS: ClassVar[dict[str, int]] = {
+        "alpha": 101,
+        "beta": 202,
+        "gamma": 303,
+        "delta": 404,
+        "km1": 505,
+        "km2": 606,
+    }
+
     @classmethod
-    def get_kas_port(cls, name: str) -> int:
-        """Get port for a KAS instance by name."""
+    def get_kas_port(cls, name: str, *, base: int | None = None) -> int:
+        """Get port for a KAS instance by name.
+
+        When `base` is provided, the port is computed as `base + offset` so
+        multiple instances can coexist on disjoint port ranges. Otherwise the
+        legacy class constants are returned (base=8080 layout).
+        """
+        if base is not None:
+            offset = cls.KAS_OFFSETS.get(name)
+            if offset is None:
+                raise ValueError(f"Unknown KAS instance: {name}")
+            return base + offset
         attr = cls._KAS_NAMES.get(name)
         if attr is None:
             raise ValueError(f"Unknown KAS instance: {name}")
         return getattr(cls, attr)
 
+    @classmethod
+    def platform_port_for(cls, base: int) -> int:
+        """Return the platform port for a given `base`. Trivially `base` today."""
+        return base
+
     @classmethod
     def all_kas_names(cls) -> list[str]:
         """Return all KAS instance names."""
diff --git a/otdf-local/src/otdf_local/config/settings.py b/otdf-local/src/otdf_local/config/settings.py
index 96a4c20e8..dffc2cefc 100644
--- a/otdf-local/src/otdf_local/config/settings.py
+++ b/otdf-local/src/otdf_local/config/settings.py
@@ -8,6 +8,8 @@
 
 from otdf_local.config.ports import Ports
 
+DEFAULT_INSTANCE_NAME = "default"
+
 
 def _pyproject_has_name(path: Path, project_name: str) -> bool:
     """Return True if path/pyproject.toml contains the given project name."""
@@ -80,6 +82,19 @@ def _find_platform_dir(xtest_root: Path) -> Path:
     )
 
 
+def _find_platform_dir_optional(xtest_root: Path) -> Path | None:
+    """Same as `_find_platform_dir` but returns None instead of raising.
+
+    Multi-instance mode looks up platform binaries via `otdf-sdk-mgr` instead of
+    a sibling repo, so a missing sibling `platform/` is no longer fatal — only
+    the legacy single-instance path needs it.
+    """
+    try:
+        return _find_platform_dir(xtest_root)
+    except FileNotFoundError:
+        return None
+
+
 class Settings(BaseSettings):
     """Application settings with environment variable support."""
 
@@ -91,44 +106,100 @@ class Settings(BaseSettings):
 
     # Directory paths - computed from xtest_root
     xtest_root: Path = Field(default_factory=_find_xtest_root)
-    platform_dir: Path = Field(
-        default_factory=lambda: _find_platform_dir(_find_xtest_root())
+    platform_dir: Path | None = Field(
+        default_factory=lambda: _find_platform_dir_optional(_find_xtest_root())
     )
 
+    # Multi-instance: which named instance under `tests/instances/<name>/` to use.
+    instance_name: str = DEFAULT_INSTANCE_NAME
+
+    @property
+    def tests_root(self) -> Path:
+        """Repo root that holds `xtest/`, `instances/`, `otdf-local/`, etc."""
+        return self.xtest_root.parent
+
+    @property
+    def instances_root(self) -> Path:
+        """Top-level `tests/instances/` directory (created on demand)."""
+        return self.tests_root / "instances"
+
+    @property
+    def instance_dir(self) -> Path:
+        """Per-instance directory: `tests/instances/<instance_name>/`."""
+        return self.instances_root / self.instance_name
+
+    @property
+    def instance_yaml(self) -> Path:
+        """Path to the per-instance manifest."""
+        return self.instance_dir / "instance.yaml"
+
+    def has_instance(self) -> bool:
+        """Return True if `instance.yaml` exists for the selected instance."""
+        return self.instance_yaml.is_file()
+
+    def platform_binary_for(self, dist: str) -> Path:
+        """Resolve a platform dist version to its built `service` binary path.
+
+        Looks under `xtest/platform/dist/<dist>/service` (managed by
+        `otdf-sdk-mgr install platform:<version>`). The binary is not required
+        to exist at the time of the call — callers should check existence and
+        surface a clear error suggesting `otdf-sdk-mgr install` when missing.
+        """
+        from otdf_sdk_mgr.platform_installer import get_platform_dir
+
+        return get_platform_dir() / "dist" / dist / "service"
+
     @property
     def logs_dir(self) -> Path:
-        """Logs directory."""
+        """Logs directory. Per-instance when an instance is selected, falls back to legacy."""
+        if self.has_instance():
+            return self.instance_dir / "logs"
         return self.xtest_root / "tmp" / "logs"
 
     @property
     def keys_dir(self) -> Path:
-        """Keys directory."""
+        """Keys directory. Per-instance when an instance is selected, falls back to legacy."""
+        if self.has_instance():
+            return self.instance_dir / "keys"
         return self.xtest_root / "tmp" / "keys"
 
     @property
     def config_dir(self) -> Path:
-        """Generated config files directory."""
+        """Generated config files directory. Per-instance when present."""
+        if self.has_instance():
+            return self.instance_dir
         return self.xtest_root / "tmp" / "config"
 
+    def _require_platform_dir(self) -> Path:
+        if self.platform_dir is None:
+            raise FileNotFoundError(
+                "No sibling platform/ directory found. Either check out opentdf/platform as "
+                "a sibling of tests/, or run `otdf-sdk-mgr install platform:<version>` and "
+                "select an instance with `otdf-local --instance <name>`."
+            )
+        return self.platform_dir
+
     @property
     def platform_config(self) -> Path:
-        """Platform config file path."""
-        return self.platform_dir / "opentdf-dev.yaml"
+        """Platform config file. Per-instance when present, else legacy template."""
+        if self.has_instance():
+            return self.instance_dir / "opentdf.yaml"
+        return self._require_platform_dir() / "opentdf-dev.yaml"
 
     @property
     def platform_template_config(self) -> Path:
-        """Platform config template path."""
-        return self.platform_dir / "opentdf.yaml"
+        """Platform config template path (legacy mode)."""
+        return self._require_platform_dir() / "opentdf.yaml"
 
     @property
     def kas_template_config(self) -> Path:
-        """KAS config template path."""
-        return self.platform_dir / "opentdf-kas-mode.yaml"
+        """KAS config template path (legacy mode)."""
+        return self._require_platform_dir() / "opentdf-kas-mode.yaml"
 
     @property
     def docker_compose_file(self) -> Path:
         """Docker compose file path."""
-        return self.platform_dir / "docker-compose.yaml"
+        return self._require_platform_dir() / "docker-compose.yaml"
 
     # Service ports
     keycloak_port: int = Ports.KEYCLOAK
@@ -147,11 +218,28 @@ def docker_compose_file(self) -> Path:
     log_level: str = "info"
 
     def get_kas_port(self, name: str) -> int:
-        """Get port for a KAS instance."""
+        """Get port for a KAS instance.
+
+        When an `instance.yaml` exists with a `ports.base`, computes ports
+        relative to it so multiple instances on different bases don't clash.
+        """
+        instance = self.load_instance()
+        if instance is not None:
+            return Ports.get_kas_port(name, base=instance.ports.base)
         return Ports.get_kas_port(name)
 
+    def load_instance(self):
+        """Load the per-instance manifest, or return None when not present."""
+        if not self.has_instance():
+            return None
+        from otdf_sdk_mgr.schema import load_instance as _load
+
+        return _load(self.instance_yaml)
+
     def get_kas_config_path(self, name: str) -> Path:
         """Get config file path for a KAS instance."""
+        if self.has_instance():
+            return self.instance_dir / "kas" / name / "opentdf.yaml"
         return self.config_dir / f"kas-{name}.yaml"
 
     def get_kas_log_path(self, name: str) -> Path:
@@ -163,6 +251,8 @@ def ensure_directories(self) -> None:
         self.logs_dir.mkdir(parents=True, exist_ok=True)
         self.config_dir.mkdir(parents=True, exist_ok=True)
         self.keys_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        if self.has_instance():
+            (self.instance_dir / "kas").mkdir(parents=True, exist_ok=True)
 
 
 @lru_cache
diff --git a/otdf-local/src/otdf_local/services/kas.py b/otdf-local/src/otdf_local/services/kas.py
index 00de6a2cd..8c2ed5b09 100644
--- a/otdf-local/src/otdf_local/services/kas.py
+++ b/otdf-local/src/otdf_local/services/kas.py
@@ -35,7 +35,7 @@ def name(self) -> str:
 
     @property
     def port(self) -> int:
-        return Ports.get_kas_port(self._kas_name)
+        return self.settings.get_kas_port(self._kas_name)
 
     @property
     def service_type(self) -> ServiceType:
@@ -47,25 +47,60 @@ def health_url(self) -> str:
 
     @property
     def is_key_management(self) -> bool:
-        """Check if this is a key management KAS instance."""
+        """Check if this is a key management KAS instance.
+
+        When an instance.yaml pins this KAS, prefer the manifest's `mode`
+        field. Otherwise fall back to the legacy name-based heuristic.
+        """
+        instance = self.settings.load_instance()
+        if instance is not None and self._kas_name in instance.kas:
+            return instance.kas[self._kas_name].mode == "key_management"
         return Ports.is_km_kas(self._kas_name)
 
+    def _instance_paths(self) -> tuple[Path, Path] | None:
+        """Return (binary, worktree) for an instance-pinned KAS, or None."""
+        instance = self.settings.load_instance()
+        if instance is None:
+            return None
+        pin = instance.kas.get(self._kas_name)
+        if pin is None or pin.dist is None:
+            return None
+        binary = self.settings.platform_binary_for(pin.dist)
+        if not binary.exists():
+            raise FileNotFoundError(
+                f"KAS {self._kas_name} binary not found at {binary}. "
+                f"Run `otdf-sdk-mgr install release platform:{pin.dist}`."
+            )
+        worktree = binary.parent
+        version_file = binary.parent / ".version"
+        if version_file.exists():
+            for line in version_file.read_text().splitlines():
+                if line.startswith("worktree="):
+                    worktree = Path(line.split("=", 1)[1].strip())
+                    break
+        return binary, worktree
+
     def _generate_config(self) -> Path:
         """Generate the KAS config file from template."""
+        instance_paths = self._instance_paths()
+        if instance_paths is not None:
+            _, worktree = instance_paths
+            platform_dir = worktree
+        else:
+            platform_dir = self.settings._require_platform_dir()
+
         config_path = self.settings.get_kas_config_path(self._kas_name)
-        template_path = self.settings.kas_template_config
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        template_path = platform_dir / "opentdf-kas-mode.yaml"
 
         # Load platform config to get root_key
         platform_config = load_yaml(self.settings.platform_config)
         root_key = get_nested(platform_config, "services.kas.root_key", "")
 
         # Detect platform features to determine supported config options
-        features = PlatformFeatures.detect(self.settings.platform_dir)
-
-        # Use stderr if supported, otherwise stdout (v0.9.0 only supports stdout)
+        features = PlatformFeatures.detect(platform_dir)
         logger_output = "stderr" if features.supports("logger_stderr") else "stdout"
 
-        # Base updates for all KAS instances
         updates = {
             "logger.type": "json",
             "logger.output": logger_output,
@@ -73,7 +108,11 @@ def _generate_config(self) -> Path:
             "services.kas.root_key": root_key,
         }
 
-        # Key management KAS instances need additional config
+        # Per-KAS features from instance.yaml override the legacy heuristic.
+        instance = self.settings.load_instance()
+        kas_pin = instance.kas.get(self._kas_name) if instance is not None else None
+        extra_features: dict[str, bool] = dict(kas_pin.features) if kas_pin is not None else {}
+
         if self.is_key_management:
             updates["services.kas.preview.key_management"] = True
             updates["services.kas.preview.ec_tdf_enabled"] = True
@@ -81,37 +120,33 @@ def _generate_config(self) -> Path:
             # registered_kas_uri should NOT have /kas suffix
             updates["services.kas.registered_kas_uri"] = f"http://localhost:{self.port}"
 
+        for feature_key, feature_val in extra_features.items():
+            updates[f"services.kas.preview.{feature_key}"] = feature_val
+
         copy_yaml_with_updates(template_path, config_path, updates)
         return config_path
 
     def start(self) -> bool:
         """Start the KAS instance."""
-        # Ensure directories exist
         self.settings.ensure_directories()
-
-        # Kill any existing process on the port
         kill_process_on_port(self.port)
-
-        # Generate config
         config_path = self._generate_config()
 
-        # Build the command
-        cmd = [
-            "go",
-            "run",
-            "./service",
-            "start",
-            "--config-file",
-            str(config_path),
-        ]
-
-        # Start the process
+        instance_paths = self._instance_paths()
+        if instance_paths is not None:
+            binary, worktree = instance_paths
+            cmd = [str(binary), "start", "--config-file", str(config_path)]
+            cwd = worktree
+        else:
+            cmd = ["go", "run", "./service", "start", "--config-file", str(config_path)]
+            cwd = self.settings._require_platform_dir()
+
         log_file = self.settings.get_kas_log_path(self._kas_name)
 
         self._process = self._process_manager.start(
             name=self.name,
             cmd=cmd,
-            cwd=self.settings.platform_dir,
+            cwd=cwd,
             log_file=log_file,
             env={"OPENTDF_LOG_LEVEL": "info"},
         )
@@ -149,7 +184,12 @@ def get_info(self) -> ServiceInfo:
 
 
 class KASManager:
-    """Manages all KAS instances."""
+    """Manages KAS instances.
+
+    When an `instance.yaml` is loaded, the managed set is restricted to the
+    KAS names listed in the manifest. Otherwise the legacy full set
+    (alpha/beta/gamma/delta/km1/km2) is managed.
+    """
 
     def __init__(
         self,
@@ -160,8 +200,13 @@ def __init__(
         self._process_manager = process_manager or ProcessManager()
         self._instances: dict[str, KASService] = {}
 
-        # Create instances for all configured KAS
-        for kas_name in Ports.all_kas_names():
+        instance = settings.load_instance()
+        if instance is not None and instance.kas:
+            kas_names = list(instance.kas.keys())
+        else:
+            kas_names = Ports.all_kas_names()
+
+        for kas_name in kas_names:
             self._instances[kas_name] = KASService(
                 settings, kas_name, self._process_manager
             )
@@ -185,17 +230,19 @@ def stop_all(self) -> dict[str, bool]:
         return results
 
     def start_standard(self) -> dict[str, bool]:
-        """Start only standard (non-km) KAS instances."""
+        """Start only standard (non-key-management) KAS instances under management."""
         results = {}
-        for name in Ports.standard_kas_names():
-            results[name] = self._instances[name].start()
+        for name, inst in self._instances.items():
+            if not inst.is_key_management:
+                results[name] = inst.start()
         return results
 
     def start_km(self) -> dict[str, bool]:
-        """Start only key management KAS instances."""
+        """Start only key-management KAS instances under management."""
         results = {}
-        for name in Ports.km_kas_names():
-            results[name] = self._instances[name].start()
+        for name, inst in self._instances.items():
+            if inst.is_key_management:
+                results[name] = inst.start()
         return results
 
     def get_all_info(self) -> list[ServiceInfo]:
diff --git a/otdf-local/src/otdf_local/services/platform.py b/otdf-local/src/otdf_local/services/platform.py
index 15f7f4e5e..aa65dcf1d 100644
--- a/otdf-local/src/otdf_local/services/platform.py
+++ b/otdf-local/src/otdf_local/services/platform.py
@@ -39,6 +39,9 @@ def name(self) -> str:
 
     @property
     def port(self) -> int:
+        instance = self.settings.load_instance()
+        if instance is not None:
+            return Ports.platform_port_for(instance.ports.base)
         return Ports.PLATFORM
 
     @property
@@ -49,13 +52,46 @@ def service_type(self) -> ServiceType:
     def health_url(self) -> str:
         return f"http://localhost:{self.port}/healthz"
 
+    def _instance_dist_paths(self) -> tuple[Path, Path] | None:
+        """Return (binary, worktree) for an instance-pinned platform, or None.
+
+        The platform binary is at `xtest/platform/dist/<dist>/service` and its
+        `.version` file records the source worktree path that should be used
+        as `cwd` so the binary finds its embedded resources.
+        """
+        instance = self.settings.load_instance()
+        if instance is None or instance.platform.dist is None:
+            return None
+        binary = self.settings.platform_binary_for(instance.platform.dist)
+        if not binary.exists():
+            raise FileNotFoundError(
+                f"Platform binary not found at {binary}. "
+                f"Run `otdf-sdk-mgr install release platform:{instance.platform.dist}` "
+                f"or `otdf-sdk-mgr install scenario` to provision it."
+            )
+        worktree = binary.parent  # safe fallback
+        version_file = binary.parent / ".version"
+        if version_file.exists():
+            for line in version_file.read_text().splitlines():
+                if line.startswith("worktree="):
+                    worktree = Path(line.split("=", 1)[1].strip())
+                    break
+        return binary, worktree
+
     def _generate_config(self) -> Path:
         """Generate the platform config file from template."""
+        instance_paths = self._instance_dist_paths()
+        if instance_paths is not None:
+            _, worktree = instance_paths
+            platform_dir = worktree
+        else:
+            platform_dir = self.settings._require_platform_dir()
+
         config_path = self.settings.platform_config
-        template_path = self.settings.platform_template_config
+        template_path = platform_dir / "opentdf.yaml"
 
         # Detect platform features to determine supported config options
-        features = PlatformFeatures.detect(self.settings.platform_dir)
+        features = PlatformFeatures.detect(platform_dir)
 
         # Use stderr if supported, otherwise stdout (v0.9.0 only supports stdout)
         logger_output = "stderr" if features.supports("logger_stderr") else "stdout"
@@ -80,10 +116,14 @@ def _setup_golden_keys(self, config_path: Path) -> None:
         Extracts keys from extra-keys.json and adds them to the platform config
         so legacy golden TDFs can be decrypted.
         """
-        # Set up golden key files and get their config entries
+        # In multi-instance mode, golden keys live alongside the instance
+        # config; otherwise they go into the legacy platform_dir.
+        target_dir = self.settings.keys_dir if self.settings.has_instance() else (
+            self.settings._require_platform_dir()
+        )
         golden_keys = setup_golden_keys(
             self.settings.xtest_root,
-            self.settings.platform_dir,
+            target_dir,
         )
 
         if not golden_keys:
@@ -112,15 +152,16 @@ def start(self) -> bool:
         # Generate config
         config_path = self._generate_config()
 
-        # Build the command
-        cmd = [
-            "go",
-            "run",
-            "./service",
-            "start",
-            "--config-file",
-            str(config_path),
-        ]
+        # Build the command — pinned binary when an instance is loaded,
+        # legacy `go run ./service` otherwise.
+        instance_paths = self._instance_dist_paths()
+        if instance_paths is not None:
+            binary, worktree = instance_paths
+            cmd = [str(binary), "start", "--config-file", str(config_path)]
+            cwd = worktree
+        else:
+            cmd = ["go", "run", "./service", "start", "--config-file", str(config_path)]
+            cwd = self.settings._require_platform_dir()
 
         # Start the process
         log_file = self.settings.logs_dir / "platform.log"
@@ -128,7 +169,7 @@ def start(self) -> bool:
         self._process = self._process_manager.start(
             name=self.name,
             cmd=cmd,
-            cwd=self.settings.platform_dir,
+            cwd=cwd,
             log_file=log_file,
             env={"OPENTDF_LOG_LEVEL": "info"},
         )
diff --git a/otdf-local/src/otdf_local/utils/keys.py b/otdf-local/src/otdf_local/utils/keys.py
index dee84f2af..79b58bf08 100644
--- a/otdf-local/src/otdf_local/utils/keys.py
+++ b/otdf-local/src/otdf_local/utils/keys.py
@@ -197,7 +197,9 @@ def setup_golden_keys(
                 f"Missing required fields in extra-keys.json for kid: {kid}"
             )
 
-        # Write key files to platform directory
+        # Write key files into the target directory (platform_dir for legacy
+        # single-instance, or the per-instance keys dir for multi-instance).
+        platform_dir.mkdir(parents=True, exist_ok=True)
         private_path = platform_dir / f"{kid}-private.pem"
         cert_path = platform_dir / f"{kid}-cert.pem"
 
@@ -205,12 +207,14 @@ def setup_golden_keys(
         private_path.chmod(0o600)
         cert_path.write_text(cert)
 
+        # Use absolute paths so the platform binary finds them regardless of
+        # its working directory (worktree in multi-instance mode).
         keys_config.append(
             {
                 "kid": kid,
                 "alg": alg,
-                "private": f"{kid}-private.pem",
-                "cert": f"{kid}-cert.pem",
+                "private": str(private_path.resolve()),
+                "cert": str(cert_path.resolve()),
             }
         )
 
diff --git a/otdf-local/tests/test_multi_instance.py b/otdf-local/tests/test_multi_instance.py
new file mode 100644
index 000000000..e290d7731
--- /dev/null
+++ b/otdf-local/tests/test_multi_instance.py
@@ -0,0 +1,78 @@
+"""Smoke tests for the multi-instance refactor.
+
+These tests exercise the path resolution and port arithmetic without
+requiring a real platform build or running services. The goal is to catch
+regressions in the wiring between `otdf-sdk-mgr.schema`, `Settings`, and the
+service launchers.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+from otdf_sdk_mgr.schema import (
+    Instance,
+    KasPin,
+    Metadata,
+    PlatformPin,
+    PortsConfig,
+    dump_instance,
+)
+
+from otdf_local.config.ports import Ports
+from otdf_local.config.settings import Settings
+
+
+def test_ports_offset_layout_at_default_base() -> None:
+    assert Ports.platform_port_for(8080) == 8080
+    assert Ports.get_kas_port("alpha", base=8080) == 8181
+    assert Ports.get_kas_port("km2", base=8080) == 8686
+
+
+def test_ports_offset_layout_at_alternate_base() -> None:
+    assert Ports.platform_port_for(9080) == 9080
+    assert Ports.get_kas_port("alpha", base=9080) == 9181
+    assert Ports.get_kas_port("km1", base=9080) == 9585
+
+
+def test_settings_default_has_no_instance(tmp_path: Path) -> None:
+    fake_xtest = tmp_path / "xtest"
+    fake_xtest.mkdir()
+    s = Settings(xtest_root=fake_xtest, platform_dir=None)
+    assert s.instance_name == "default"
+    assert not s.has_instance()
+
+
+def test_settings_loads_instance_when_present(tmp_path: Path) -> None:
+    fake_xtest = tmp_path / "xtest"
+    fake_xtest.mkdir()
+    instances_root = tmp_path / "instances"
+    instance_dir = instances_root / "demo"
+    instance_dir.mkdir(parents=True)
+    dump_instance(
+        Instance(
+            metadata=Metadata(name="demo"),
+            platform=PlatformPin(dist="v0.9.0"),
+            ports=PortsConfig(base=9080),
+            kas={"alpha": KasPin(dist="v0.9.0", mode="standard")},
+        ),
+        instance_dir / "instance.yaml",
+    )
+    s = Settings(xtest_root=fake_xtest, platform_dir=None, instance_name="demo")
+    assert s.has_instance()
+    inst = s.load_instance()
+    assert inst is not None
+    assert inst.ports.base == 9080
+    # Per-instance port arithmetic
+    assert s.get_kas_port("alpha") == 9181
+    # Per-instance directory layout
+    assert s.logs_dir == instance_dir / "logs"
+    assert s.keys_dir == instance_dir / "keys"
+
+
+def test_platform_binary_for_resolves_under_xtest_platform(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("OTDF_PLATFORM_DIR", "/tmp/fake-platform")
+    s = Settings()
+    assert s.platform_binary_for("v0.9.0") == Path("/tmp/fake-platform/dist/v0.9.0/service")
diff --git a/otdf-local/uv.lock b/otdf-local/uv.lock
index 4da54a0f6..f594e80f2 100644
--- a/otdf-local/uv.lock
+++ b/otdf-local/uv.lock
@@ -51,6 +51,30 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
 ]
 
+[[package]]
+name = "gitdb"
+version = "4.0.12"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "smmap" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/72/94/63b0fc47eb32792c7ba1fe1b694daec9a63620db1e313033d18140c2320a/gitdb-4.0.12.tar.gz", hash = "sha256:5ef71f855d191a3326fcfbc0d5da835f26b13fbcba60c32c21091c349ffdb571", size = 394684, upload-time = "2025-01-02T07:20:46.413Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/61/5c78b91c3143ed5c14207f463aecfc8f9dbb5092fb2869baf37c273b2705/gitdb-4.0.12-py3-none-any.whl", hash = "sha256:67073e15955400952c6565cc3e707c554a4eea2e428946f7a4c162fab9bd9bcf", size = 62794, upload-time = "2025-01-02T07:20:43.624Z" },
+]
+
+[[package]]
+name = "gitpython"
+version = "3.1.50"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "gitdb" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/33/f6/354ae6491228b5eb40e10d89c4d13c651fe1cf7556e35ebdded50cff57ce/gitpython-3.1.50.tar.gz", hash = "sha256:80da2d12504d52e1f998772dc5baf6e553f8d2fcfe1fcc226c9d9a2ee3372dcc", size = 219798, upload-time = "2026-05-06T04:01:26.571Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/7a/1c6e3562dfd8950adbb11ffbc65d21e7c89d01a6e4f137fa981056de25c5/gitpython-3.1.50-py3-none-any.whl", hash = "sha256:d352abe2908d07355014abdd21ddf798c2a961469239afec4962e9da884858f9", size = 212507, upload-time = "2026-05-06T04:01:23.799Z" },
+]
+
 [[package]]
 name = "h11"
 version = "0.16.0"
@@ -142,6 +166,7 @@ version = "0.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
+    { name = "otdf-sdk-mgr" },
     { name = "pydantic-settings" },
     { name = "rich" },
     { name = "ruamel-yaml" },
@@ -158,6 +183,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "httpx", specifier = ">=0.27.0" },
+    { name = "otdf-sdk-mgr", editable = "../otdf-sdk-mgr" },
     { name = "pydantic-settings", specifier = ">=2.14.1" },
     { name = "rich", specifier = ">=15.0.0" },
     { name = "ruamel-yaml", specifier = ">=0.18.0" },
@@ -171,6 +197,34 @@ dev = [
     { name = "ruff", specifier = ">=0.15.15" },
 ]
 
+[[package]]
+name = "otdf-sdk-mgr"
+version = "0.1.0"
+source = { editable = "../otdf-sdk-mgr" }
+dependencies = [
+    { name = "gitpython" },
+    { name = "pydantic" },
+    { name = "rich" },
+    { name = "ruamel-yaml" },
+    { name = "typer" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "gitpython", specifier = ">=3.1.50" },
+    { name = "pydantic", specifier = ">=2.6.0" },
+    { name = "rich", specifier = ">=15.0.0" },
+    { name = "ruamel-yaml", specifier = ">=0.18.0" },
+    { name = "typer", specifier = ">=0.26.5" },
+]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "pyright", specifier = ">=1.1.410" },
+    { name = "pytest", specifier = ">=9.0.3" },
+    { name = "ruff", specifier = ">=0.15.15" },
+]
+
 [[package]]
 name = "packaging"
 version = "26.0"
@@ -418,9 +472,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
 ]
 
+[[package]]
+name = "smmap"
+version = "5.0.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1f/ea/49c993d6dfdd7338c9b1000a0f36817ed7ec84577ae2e52f890d1a4ff909/smmap-5.0.3.tar.gz", hash = "sha256:4d9debb8b99007ae47165abc08670bd74cb74b5227dda7f643eccc4e9eb5642c", size = 22506, upload-time = "2026-03-09T03:43:26.1Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c1/d4/59e74daffcb57a07668852eeeb6035af9f32cbfd7a1d2511f17d2fe6a738/smmap-5.0.3-py3-none-any.whl", hash = "sha256:c106e05d5a61449cf6ba9a1e650227ecfb141590d2a98412103ff35d89fc7b2f", size = 24390, upload-time = "2026-03-09T03:43:24.361Z" },
+]
+
 [[package]]
 name = "typer"
-version = "0.26.5"
+version = "0.26.7"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "annotated-doc" },
@@ -428,9 +491,9 @@ dependencies = [
     { name = "rich" },
     { name = "shellingham" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/eb/1a/2cf40b65b1d9c254fe5814bb0519f9b8f2ac38059df0810f9b866300c04a/typer-0.26.5.tar.gz", hash = "sha256:9b9b39e35c3afc9e1e51a06f21155246e457c0911279b09b35d8210ca74b935c", size = 201494, upload-time = "2026-06-01T14:42:49.744Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5e/ed/ef06584ccdd5c410df0837951ecd7e15d9a6144ea1bd4c73cecab1a89891/typer-0.26.7.tar.gz", hash = "sha256:e314a34c617e419c091b2830dda3ea1f257134ff593061a8f5b9717ab8dddb3a", size = 201709, upload-time = "2026-06-03T07:18:06.843Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ec/d6/baac76fc04a6532883de3d8722c7f921dae94d10965e7ffba9e38e42a251/typer-0.26.5-py3-none-any.whl", hash = "sha256:4bfd901d564e41608920134aa5d4481200f4ba76d98e982d9f9d32dcb7b84da0", size = 122451, upload-time = "2026-06-01T14:42:51.021Z" },
+    { url = "https://files.pythonhosted.org/packages/24/25/2201973529af2c954de0bb725323c3aaed6d7f0ceee8f550dec9185df013/typer-0.26.7-py3-none-any.whl", hash = "sha256:5c87cfbc5d34491c5346ebf49c23e18d56ccb863268d3a8d592b26087c2f5e58", size = 122456, upload-time = "2026-06-03T07:18:05.732Z" },
 ]
 
 [[package]]

From 0597e26d7cb5ba7a4c56a0cbe75325ccea1b8d6c Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 2 Jun 2026 08:25:33 -0400
Subject: [PATCH 02/64] feat(otdf-local): self-provision keys + opentdf.yaml at
 instance init
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Before this change, `otdf-local instance init` only wrote `instance.yaml`
and empty subdirs. Anyone running a fresh instance had to manually copy
keys from another worktree, run `init-temp-keys.sh` by hand, and copy
`opentdf-dev.yaml` into the instance dir before `up` would succeed —
otherwise Keycloak crash-looped on a missing `truststore.jks`, and
pytest failed with `OT_ROOT_KEY environment variable is not set`.

Changes:
- utils/keys.py: add `generate_localhost_cert()` and `generate_ca_jks()`
  to produce the Keycloak TLS pair + JKS truststore (matches the
  platform's `init-temp-keys.sh`). `generate_ca_jks()` runs `keytool`
  inside the `keycloak/keycloak:25.0` image so a local JDK isn't
  required. `ensure_keys_exist()` now generates the full bootstrap
  bundle, idempotently.
- cli_instance.py: `_init_from_scenario` and `_init_minimal` call a new
  `_provision_instance_dir()` helper that runs `ensure_keys_exist()` and
  copies the platform's `opentdf-dev.yaml` (or `opentdf-example.yaml`)
  into the instance dir, overriding `services.kas.root_key` with a
  freshly generated value so every instance owns its own root key.
- services/platform.py: `_generate_config()` preserves an existing
  per-instance `opentdf.yaml`, only patching logger + golden-key fields
  in place, so the init-time `root_key` survives restarts.
- services/docker.py: docker-compose subprocesses are now run with
  `KEYS_DIR=<instance>/keys` so the compose file's `${KEYS_DIR:-./keys}`
  mounts resolve to the per-instance bundle.

Users can now run:

  otdf-local instance init <name> --from-scenario path/to/scenario.yaml
  otdf-local --instance <name> up
  eval $(otdf-local --instance <name> env)
  cd xtest && uv run pytest ...

with no manual key-copying, no editing of `opentdf.yaml`, and no
shell-script fallback. Verified end-to-end against `pure-mlkem.yaml`
(PR opentdf/platform#3537): all 9 services come up healthy on the first
try and `env` exports `OT_ROOT_KEY`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 otdf-local/src/otdf_local/cli_instance.py     | 116 +++++++++-
 otdf-local/src/otdf_local/services/docker.py  |  11 +
 .../src/otdf_local/services/platform.py       |  26 ++-
 otdf-local/src/otdf_local/utils/keys.py       | 200 +++++++++++++++++-
 4 files changed, 334 insertions(+), 19 deletions(-)

diff --git a/otdf-local/src/otdf_local/cli_instance.py b/otdf-local/src/otdf_local/cli_instance.py
index 98407f56e..712dc2967 100644
--- a/otdf-local/src/otdf_local/cli_instance.py
+++ b/otdf-local/src/otdf_local/cli_instance.py
@@ -7,9 +7,17 @@
 from typing import Annotated, Optional
 
 import typer
-from otdf_sdk_mgr.schema import Instance, Metadata, PlatformPin, PortsConfig, dump_instance
+from otdf_sdk_mgr.schema import (
+    Instance,
+    Metadata,
+    PlatformPin,
+    PortsConfig,
+    dump_instance,
+)
 
-from otdf_local.config.settings import get_settings
+from otdf_local.config.settings import Settings, get_settings
+from otdf_local.utils.keys import ensure_keys_exist, generate_root_key
+from otdf_local.utils.yaml import copy_yaml_with_updates
 
 instance_app = typer.Typer(help="Manage named test environment instances.")
 
@@ -19,11 +27,15 @@ def init(
     name: Annotated[str, typer.Argument(help="Instance name (used as directory name)")],
     from_scenario: Annotated[
         Optional[Path],
-        typer.Option("--from-scenario", help="Initialize from a scenarios.yaml or instance.yaml"),
+        typer.Option(
+            "--from-scenario", help="Initialize from a scenarios.yaml or instance.yaml"
+        ),
     ] = None,
     ports_base: Annotated[
         int,
-        typer.Option("--ports-base", help="Base port (KAS ports computed as base+N*101)"),
+        typer.Option(
+            "--ports-base", help="Base port (KAS ports computed as base+N*101)"
+        ),
     ] = 8080,
     platform_dist: Annotated[
         Optional[str],
@@ -38,7 +50,10 @@ def init(
         _init_from_scenario(name, from_scenario, instance_dir)
     else:
         if platform_dist is None:
-            typer.echo("Error: --platform <dist> is required when not using --from-scenario", err=True)
+            typer.echo(
+                "Error: --platform <dist> is required when not using --from-scenario",
+                err=True,
+            )
             raise typer.Exit(2)
         _init_minimal(name, instance_dir, ports_base, platform_dist)
 
@@ -64,15 +79,20 @@ def _init_from_scenario(name: str, scenario_path: Path, instance_dir: Path) -> N
     else:
         raise typer.BadParameter(f"{scenario_path} has unknown kind {kind!r}")
     # Ensure the metadata name matches the chosen directory name.
-    instance.metadata = Metadata(**{**instance.metadata.model_dump(exclude_none=True), "name": name})
+    instance.metadata = Metadata(
+        **{**instance.metadata.model_dump(exclude_none=True), "name": name}
+    )
     instance_dir.mkdir(parents=True, exist_ok=True)
     (instance_dir / "kas").mkdir(parents=True, exist_ok=True)
     (instance_dir / "keys").mkdir(mode=0o700, parents=True, exist_ok=True)
     (instance_dir / "logs").mkdir(parents=True, exist_ok=True)
     dump_instance(instance, instance_dir / "instance.yaml")
+    _provision_instance_dir(instance_dir, instance)
 
 
-def _init_minimal(name: str, instance_dir: Path, ports_base: int, platform_dist: str) -> None:
+def _init_minimal(
+    name: str, instance_dir: Path, ports_base: int, platform_dist: str
+) -> None:
     """Create a barebones instance.yaml with default KAS layout."""
     instance = Instance(
         metadata=Metadata(name=name),
@@ -85,6 +105,82 @@ def _init_minimal(name: str, instance_dir: Path, ports_base: int, platform_dist:
     (instance_dir / "keys").mkdir(mode=0o700, parents=True, exist_ok=True)
     (instance_dir / "logs").mkdir(parents=True, exist_ok=True)
     dump_instance(instance, instance_dir / "instance.yaml")
+    _provision_instance_dir(instance_dir, instance)
+
+
+def _resolve_platform_worktree(instance: Instance) -> Path:
+    """Find the platform source worktree for this instance's pin.
+
+    For both `dist` and `source` pins, the platform installer writes a
+    `.version` file next to the binary with `worktree=<path>`. We follow
+    that pointer because the binary's parent directory only holds the
+    built artifact — the YAML templates live in the source tree.
+    """
+    from otdf_sdk_mgr.platform_installer import get_platform_dir
+    from otdf_sdk_mgr.refs import expand_pr_shorthand, ref_slug
+
+    settings = Settings()
+    pin = instance.platform
+    if pin.dist is not None:
+        dist_name = pin.dist
+    elif pin.source is not None:
+        dist_name = ref_slug(expand_pr_shorthand(pin.source.ref))
+    else:
+        raise typer.BadParameter("instance.platform must set dist or source")
+
+    binary = get_platform_dir() / "dist" / dist_name / "service"
+    if not binary.exists():
+        raise FileNotFoundError(
+            f"Platform binary not found at {binary}. "
+            f"Run `otdf-sdk-mgr install scenario` (or `install release platform:<v>`) "
+            f"to provision it before `instance init`."
+        )
+    version_file = binary.parent / ".version"
+    if version_file.exists():
+        for line in version_file.read_text().splitlines():
+            if line.startswith("worktree="):
+                worktree = Path(line.split("=", 1)[1].strip())
+                if worktree.is_dir():
+                    return worktree
+    # Fallback to sibling platform dir (legacy single-instance layout).
+    if settings.platform_dir is not None:
+        return settings.platform_dir
+    raise FileNotFoundError(
+        f"Could not resolve platform source worktree from {version_file}; "
+        f"no sibling platform/ directory available either."
+    )
+
+
+def _provision_instance_dir(instance_dir: Path, instance: Instance) -> None:
+    """Generate the bootstrap bundle: keys + opentdf.yaml with a fresh root_key.
+
+    Idempotent — `ensure_keys_exist` skips files that already exist, and
+    `opentdf.yaml` is only generated when missing so reruns of `instance init`
+    don't churn the per-instance root_key.
+    """
+    keys_dir = instance_dir / "keys"
+    keys_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+    ensure_keys_exist(keys_dir)
+
+    config_path = instance_dir / "opentdf.yaml"
+    if config_path.exists():
+        return
+
+    worktree = _resolve_platform_worktree(instance)
+    template = worktree / "opentdf-dev.yaml"
+    if not template.is_file():
+        template = worktree / "opentdf-example.yaml"
+    if not template.is_file():
+        raise FileNotFoundError(
+            f"No platform config template found in {worktree} "
+            f"(looked for opentdf-dev.yaml and opentdf-example.yaml)."
+        )
+
+    copy_yaml_with_updates(
+        template,
+        config_path,
+        {"services.kas.root_key": generate_root_key()},
+    )
 
 
 def _validate_port_uniqueness(instances_root: Path, new_name: str) -> None:
@@ -150,7 +246,11 @@ def ls(
                 "name": child.name,
                 "platform": (
                     inst.platform.dist
-                    or (inst.platform.source.ref if inst.platform.source else inst.platform.image)
+                    or (
+                        inst.platform.source.ref
+                        if inst.platform.source
+                        else inst.platform.image
+                    )
                 ),
                 "ports_base": inst.ports.base,
                 "kas": list(inst.kas.keys()),
diff --git a/otdf-local/src/otdf_local/services/docker.py b/otdf-local/src/otdf_local/services/docker.py
index 911b42e3c..5cf746f2d 100644
--- a/otdf-local/src/otdf_local/services/docker.py
+++ b/otdf-local/src/otdf_local/services/docker.py
@@ -1,6 +1,7 @@
 """Docker compose service management."""
 
 import json
+import os
 import subprocess
 
 from otdf_local.config.ports import Ports
@@ -16,6 +17,13 @@ def __init__(self, settings: Settings) -> None:
         super().__init__(settings)
         self._compose_file = settings.docker_compose_file
 
+    def _compose_env(self) -> dict[str, str]:
+        """Env passed to docker-compose so `${KEYS_DIR}` resolves per-instance."""
+        env = os.environ.copy()
+        if self.settings.has_instance():
+            env["KEYS_DIR"] = str(self.settings.keys_dir.resolve())
+        return env
+
     @property
     def name(self) -> str:
         return "docker"
@@ -42,6 +50,7 @@ def start(self) -> bool:
             capture_output=True,
             text=True,
             cwd=self._compose_file.parent,
+            env=self._compose_env(),
         )
         return result.returncode == 0
 
@@ -55,6 +64,7 @@ def stop(self) -> bool:
             capture_output=True,
             text=True,
             cwd=self._compose_file.parent,
+            env=self._compose_env(),
         )
         return result.returncode == 0
 
@@ -89,6 +99,7 @@ def get_container_status(self) -> dict[str, dict]:
             capture_output=True,
             text=True,
             cwd=self._compose_file.parent,
+            env=self._compose_env(),
         )
 
         if result.returncode != 0:
diff --git a/otdf-local/src/otdf_local/services/platform.py b/otdf-local/src/otdf_local/services/platform.py
index aa65dcf1d..3f2ad9cb0 100644
--- a/otdf-local/src/otdf_local/services/platform.py
+++ b/otdf-local/src/otdf_local/services/platform.py
@@ -18,6 +18,7 @@
     copy_yaml_with_updates,
     load_yaml,
     save_yaml,
+    set_nested,
 )
 
 
@@ -79,7 +80,13 @@ def _instance_dist_paths(self) -> tuple[Path, Path] | None:
         return binary, worktree
 
     def _generate_config(self) -> Path:
-        """Generate the platform config file from template."""
+        """Generate the platform config file from template.
+
+        When an instance config already exists (written at `instance init`
+        time), we keep its body intact — only patch logger keys + golden
+        keys in place. This preserves the per-instance root_key across
+        restarts.
+        """
         instance_paths = self._instance_dist_paths()
         if instance_paths is not None:
             _, worktree = instance_paths
@@ -88,7 +95,6 @@ def _generate_config(self) -> Path:
             platform_dir = self.settings._require_platform_dir()
 
         config_path = self.settings.platform_config
-        template_path = platform_dir / "opentdf.yaml"
 
         # Detect platform features to determine supported config options
         features = PlatformFeatures.detect(platform_dir)
@@ -96,14 +102,20 @@ def _generate_config(self) -> Path:
         # Use stderr if supported, otherwise stdout (v0.9.0 only supports stdout)
         logger_output = "stderr" if features.supports("logger_stderr") else "stdout"
 
-        # Updates for platform config
         updates = {
             "logger.level": "debug",
             "logger.type": "json",
             "logger.output": logger_output,
         }
 
-        copy_yaml_with_updates(template_path, config_path, updates)
+        if config_path.exists():
+            data = load_yaml(config_path)
+            for dot_path, value in updates.items():
+                set_nested(data, dot_path, value)
+            save_yaml(config_path, data)
+        else:
+            template_path = platform_dir / "opentdf.yaml"
+            copy_yaml_with_updates(template_path, config_path, updates)
 
         # Set up golden keys for legacy TDF tests
         self._setup_golden_keys(config_path)
@@ -118,8 +130,10 @@ def _setup_golden_keys(self, config_path: Path) -> None:
         """
         # In multi-instance mode, golden keys live alongside the instance
         # config; otherwise they go into the legacy platform_dir.
-        target_dir = self.settings.keys_dir if self.settings.has_instance() else (
-            self.settings._require_platform_dir()
+        target_dir = (
+            self.settings.keys_dir
+            if self.settings.has_instance()
+            else (self.settings._require_platform_dir())
         )
         golden_keys = setup_golden_keys(
             self.settings.xtest_root,
diff --git a/otdf-local/src/otdf_local/utils/keys.py b/otdf-local/src/otdf_local/utils/keys.py
index 79b58bf08..5dd5fe5fe 100644
--- a/otdf-local/src/otdf_local/utils/keys.py
+++ b/otdf-local/src/otdf_local/utils/keys.py
@@ -1,6 +1,7 @@
 """Cryptographic key generation utilities."""
 
 import json
+import os
 import secrets
 import subprocess
 from pathlib import Path
@@ -136,24 +137,213 @@ def generate_ec_keypair(key_dir: Path, name: str = "kas-ec") -> tuple[Path, Path
     return private_key, public_key
 
 
+def generate_localhost_cert(key_dir: Path) -> tuple[Path, Path]:
+    """Generate the TLS cert pair Keycloak mounts at /etc/x509/tls/.
+
+    Mirrors the localhost cert flow in the platform's init-temp-keys.sh:
+    self-signed CA → CSR with SAN → signed leaf cert. Keycloak rejects a
+    plain self-signed leaf because it pins the SAN to localhost+127.0.0.1.
+    """
+    key_dir.mkdir(parents=True, exist_ok=True)
+    ca_key = key_dir / "keycloak-ca-private.pem"
+    ca_cert = key_dir / "keycloak-ca.pem"
+    leaf_key = key_dir / "localhost.key"
+    leaf_csr = key_dir / "localhost.req"
+    leaf_cert = key_dir / "localhost.crt"
+    san_conf = key_dir / "sanX509.conf"
+    req_conf = key_dir / "req.conf"
+
+    san_conf.write_text("subjectAltName=DNS:localhost,IP:127.0.0.1")
+    req_conf.write_text(
+        "[req]\n"
+        "distinguished_name=req_distinguished_name\n"
+        "[req_distinguished_name]\n"
+        "[alt_names]\n"
+        "DNS.1=localhost\n"
+        "IP.1=127.0.0.1"
+    )
+
+    subprocess.run(
+        [
+            "openssl",
+            "req",
+            "-x509",
+            "-nodes",
+            "-newkey",
+            "RSA:2048",
+            "-subj",
+            "/CN=ca",
+            "-keyout",
+            str(ca_key),
+            "-out",
+            str(ca_cert),
+            "-days",
+            "365",
+        ],
+        check=True,
+        capture_output=True,
+    )
+    ca_key.chmod(0o600)
+    subprocess.run(
+        [
+            "openssl",
+            "req",
+            "-new",
+            "-nodes",
+            "-newkey",
+            "rsa:2048",
+            "-keyout",
+            str(leaf_key),
+            "-out",
+            str(leaf_csr),
+            "-batch",
+            "-subj",
+            "/CN=localhost",
+            "-config",
+            str(req_conf),
+        ],
+        check=True,
+        capture_output=True,
+    )
+    leaf_key.chmod(0o600)
+    subprocess.run(
+        [
+            "openssl",
+            "x509",
+            "-req",
+            "-in",
+            str(leaf_csr),
+            "-CA",
+            str(ca_cert),
+            "-CAkey",
+            str(ca_key),
+            "-CAcreateserial",
+            "-out",
+            str(leaf_cert),
+            "-days",
+            "3650",
+            "-sha256",
+            "-extfile",
+            str(san_conf),
+        ],
+        check=True,
+        capture_output=True,
+    )
+
+    return leaf_key, leaf_cert
+
+
+def generate_ca_jks(key_dir: Path, password: str = "password") -> Path:
+    """Convert the keycloak CA into the JKS truststore Keycloak mounts.
+
+    Uses keytool inside the keycloak/keycloak:25.0 image so we don't need a
+    local JDK — docker is already a hard dependency for the test env.
+    Requires generate_localhost_cert() to have run first.
+    """
+    ca_key = key_dir / "keycloak-ca-private.pem"
+    ca_cert = key_dir / "keycloak-ca.pem"
+    if not ca_key.exists() or not ca_cert.exists():
+        raise FileNotFoundError(
+            f"CA files missing in {key_dir}; call generate_localhost_cert() first"
+        )
+    p12 = key_dir / "ca.p12"
+    jks = key_dir / "ca.jks"
+
+    subprocess.run(
+        [
+            "openssl",
+            "pkcs12",
+            "-export",
+            "-in",
+            str(ca_cert),
+            "-inkey",
+            str(ca_key),
+            "-out",
+            str(p12),
+            "-nodes",
+            "-passout",
+            f"pass:{password}",
+        ],
+        check=True,
+        capture_output=True,
+    )
+
+    # keytool -importkeystore via the keycloak image (matches init-temp-keys.sh)
+    result = subprocess.run(
+        [
+            "docker",
+            "run",
+            "--rm",
+            "-v",
+            f"{key_dir.resolve()}:/keys",
+            "--entrypoint",
+            "keytool",
+            "--user",
+            f"{os.getuid()}:{os.getgid()}",
+            "keycloak/keycloak:25.0",
+            "-importkeystore",
+            "-srckeystore",
+            "/keys/ca.p12",
+            "-srcstoretype",
+            "PKCS12",
+            "-destkeystore",
+            "/keys/ca.jks",
+            "-deststoretype",
+            "JKS",
+            "-srcstorepass",
+            password,
+            "-deststorepass",
+            password,
+            "-noprompt",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"keytool failed converting PKCS12 → JKS:\n{result.stderr}\n"
+            "Ensure Docker is running and `keycloak/keycloak:25.0` is pullable."
+        )
+    return jks
+
+
 def ensure_keys_exist(key_dir: Path, force: bool = False) -> bool:
     """Ensure all required keys exist, generating if needed.
 
+    Generates the full bootstrap bundle the platform + Keycloak need:
+    KAS RSA/EC keypairs, the localhost TLS cert pair, and the ca.jks
+    truststore. PQC keys (ML-KEM, X-Wing) are not generated here — those
+    are provisioned at test time via the key-management API.
+
     Args:
         key_dir: Directory for key storage
         force: If True, regenerate keys even if they exist
 
     Returns:
-        True if keys were generated, False if they already existed
+        True if any keys were generated, False if everything already existed
     """
     rsa_private = key_dir / "kas-private.pem"
     ec_private = key_dir / "kas-ec-private.pem"
-
-    if not force and rsa_private.exists() and ec_private.exists():
+    localhost_key = key_dir / "localhost.key"
+    ca_jks = key_dir / "ca.jks"
+
+    if (
+        not force
+        and rsa_private.exists()
+        and ec_private.exists()
+        and localhost_key.exists()
+        and ca_jks.exists()
+    ):
         return False
 
-    generate_rsa_keypair(key_dir, "kas")
-    generate_ec_keypair(key_dir, "kas-ec")
+    if force or not rsa_private.exists():
+        generate_rsa_keypair(key_dir, "kas")
+    if force or not ec_private.exists():
+        generate_ec_keypair(key_dir, "kas-ec")
+    if force or not localhost_key.exists():
+        generate_localhost_cert(key_dir)
+    if force or not ca_jks.exists():
+        generate_ca_jks(key_dir)
     return True
 
 

From e4b2e69d018cec5d115db5db573168a60144c343 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 2 Jun 2026 09:25:52 -0400
Subject: [PATCH 03/64] fix(otdf-local): translate scenario suite to pytest
 argv per actual schema

`_build_pytest_args` read `suite.select` and treated `suite.containers`
as a string, but the Pydantic Suite model exposes `targets: list[str]`
and `containers: list[ContainerKind]`. Any user invoking
`otdf-local scenario run` hit AttributeError. Also wires `suite.kexpr`
through as `-k`; it was silently dropped.

Adds unit tests covering empty/multi targets, container join, kexpr,
markers + extra args, and SDK token forwarding.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 otdf-local/src/otdf_local/cli_scenario.py |  10 +-
 otdf-local/tests/test_cli_scenario.py     | 115 ++++++++++++++++++++++
 2 files changed, 122 insertions(+), 3 deletions(-)
 create mode 100644 otdf-local/tests/test_cli_scenario.py

diff --git a/otdf-local/src/otdf_local/cli_scenario.py b/otdf-local/src/otdf_local/cli_scenario.py
index 7d1dfde30..08e8def65 100644
--- a/otdf-local/src/otdf_local/cli_scenario.py
+++ b/otdf-local/src/otdf_local/cli_scenario.py
@@ -34,7 +34,7 @@ def _build_pytest_args(scenario: Scenario, scenario_path: Path) -> list[str]:
     helper raises FileNotFoundError with a clean hint otherwise.
     """
     suite = scenario.suite
-    args: list[str] = [suite.select]
+    args: list[str] = list(suite.targets)
 
     tokens = scenario_to_pytest_sdks(scenario, installed_json_for(scenario_path))
     if tokens["encrypt"]:
@@ -42,7 +42,9 @@ def _build_pytest_args(scenario: Scenario, scenario_path: Path) -> list[str]:
     if tokens["decrypt"]:
         args.extend(["--sdks-decrypt", " ".join(tokens["decrypt"])])
     if suite.containers:
-        args.extend(["--containers", suite.containers])
+        args.extend(["--containers", " ".join(suite.containers)])
+    if suite.kexpr:
+        args.extend(["-k", suite.kexpr])
     if suite.markers:
         args.extend(["-m", suite.markers])
     args.extend(suite.extra_args)
@@ -72,7 +74,9 @@ def run(
     scenario = load_scenario(path)
     instance_name = instance or scenario.instance.metadata.name
     if not instance_name:
-        typer.echo("Error: scenario.instance.metadata.name not set; pass --instance", err=True)
+        typer.echo(
+            "Error: scenario.instance.metadata.name not set; pass --instance", err=True
+        )
         raise typer.Exit(2)
 
     settings = get_settings()
diff --git a/otdf-local/tests/test_cli_scenario.py b/otdf-local/tests/test_cli_scenario.py
new file mode 100644
index 000000000..628f7f0a1
--- /dev/null
+++ b/otdf-local/tests/test_cli_scenario.py
@@ -0,0 +1,115 @@
+"""Tests for `_build_pytest_args` — the scenario-suite → pytest argv translator."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from otdf_sdk_mgr.schema import (
+    Instance,
+    Metadata,
+    PlatformPin,
+    Scenario,
+    ScenarioSdk,
+    ScenarioSdks,
+    Suite,
+)
+
+from otdf_local import cli_scenario
+
+
+def _scenario(suite: Suite, sdks: ScenarioSdks | None = None) -> Scenario:
+    return Scenario(
+        metadata=Metadata(name="t"),
+        instance=Instance(
+            metadata=Metadata(name="t"),
+            platform=PlatformPin(dist="v0.9.0"),
+        ),
+        sdks=sdks or ScenarioSdks(),
+        suite=suite,
+    )
+
+
+@pytest.fixture
+def stub_sdks(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Bypass the installed.json round-trip; tests focus on the suite block."""
+    monkeypatch.setattr(
+        cli_scenario,
+        "scenario_to_pytest_sdks",
+        lambda _s, _p: {"encrypt": [], "decrypt": []},
+    )
+
+
+def test_empty_targets(stub_sdks: None) -> None:
+    args = cli_scenario._build_pytest_args(_scenario(Suite(targets=[])), Path("s.yaml"))
+    assert args == []
+
+
+def test_multi_target(stub_sdks: None) -> None:
+    args = cli_scenario._build_pytest_args(
+        _scenario(Suite(targets=["test_a.py", "test_b.py::test_x"])), Path("s.yaml")
+    )
+    assert args == ["test_a.py", "test_b.py::test_x"]
+
+
+def test_containers_joined(stub_sdks: None) -> None:
+    args = cli_scenario._build_pytest_args(
+        _scenario(Suite(targets=["test_pqc.py"], containers=["ztdf", "ztdf-ecwrap"])),
+        Path("s.yaml"),
+    )
+    assert args == ["test_pqc.py", "--containers", "ztdf ztdf-ecwrap"]
+
+
+def test_no_containers_omits_flag(stub_sdks: None) -> None:
+    args = cli_scenario._build_pytest_args(
+        _scenario(Suite(targets=["t.py"], containers=[])), Path("s.yaml")
+    )
+    assert "--containers" not in args
+
+
+def test_kexpr_forwarded(stub_sdks: None) -> None:
+    args = cli_scenario._build_pytest_args(
+        _scenario(Suite(targets=["t.py"], kexpr="not slow")), Path("s.yaml")
+    )
+    assert args == ["t.py", "-k", "not slow"]
+
+
+def test_markers_and_extra_args(stub_sdks: None) -> None:
+    args = cli_scenario._build_pytest_args(
+        _scenario(Suite(targets=["t.py"], markers="smoke", extra_args=["-vv", "-x"])),
+        Path("s.yaml"),
+    )
+    assert args == ["t.py", "-m", "smoke", "-vv", "-x"]
+
+
+def test_sdks_tokens_forwarded(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        cli_scenario,
+        "scenario_to_pytest_sdks",
+        lambda _s, _p: {
+            "encrypt": ["go@v0.24.0"],
+            "decrypt": ["go@v0.24.0", "java@v0.10.0"],
+        },
+    )
+    args = cli_scenario._build_pytest_args(
+        _scenario(
+            Suite(targets=["t.py"]),
+            sdks=ScenarioSdks(
+                encrypt=[ScenarioSdk(sdk="go", version="v0.24.0")],
+                decrypt=[
+                    ScenarioSdk(sdk="go", version="v0.24.0"),
+                    ScenarioSdk(sdk="java", version="v0.10.0"),
+                ],
+            ),
+        ),
+        Path("s.yaml"),
+    )
+    assert args == [
+        "t.py",
+        "--sdks-encrypt",
+        "go@v0.24.0",
+        "--sdks-decrypt",
+        "go@v0.24.0 java@v0.10.0",
+    ]

From 3250bfa3755b7153fdb1b29553a96f5c2909b80e Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 2 Jun 2026 09:26:32 -0400
Subject: [PATCH 04/64] style(otdf-local): apply ruff format

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 otdf-local/src/otdf_local/services/kas.py | 4 +++-
 otdf-local/tests/test_multi_instance.py   | 8 ++++++--
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/otdf-local/src/otdf_local/services/kas.py b/otdf-local/src/otdf_local/services/kas.py
index 8c2ed5b09..7c7e5cd6f 100644
--- a/otdf-local/src/otdf_local/services/kas.py
+++ b/otdf-local/src/otdf_local/services/kas.py
@@ -111,7 +111,9 @@ def _generate_config(self) -> Path:
         # Per-KAS features from instance.yaml override the legacy heuristic.
         instance = self.settings.load_instance()
         kas_pin = instance.kas.get(self._kas_name) if instance is not None else None
-        extra_features: dict[str, bool] = dict(kas_pin.features) if kas_pin is not None else {}
+        extra_features: dict[str, bool] = (
+            dict(kas_pin.features) if kas_pin is not None else {}
+        )
 
         if self.is_key_management:
             updates["services.kas.preview.key_management"] = True
diff --git a/otdf-local/tests/test_multi_instance.py b/otdf-local/tests/test_multi_instance.py
index e290d7731..8c3b44908 100644
--- a/otdf-local/tests/test_multi_instance.py
+++ b/otdf-local/tests/test_multi_instance.py
@@ -72,7 +72,11 @@ def test_settings_loads_instance_when_present(tmp_path: Path) -> None:
     assert s.keys_dir == instance_dir / "keys"
 
 
-def test_platform_binary_for_resolves_under_xtest_platform(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_platform_binary_for_resolves_under_xtest_platform(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
     monkeypatch.setenv("OTDF_PLATFORM_DIR", "/tmp/fake-platform")
     s = Settings()
-    assert s.platform_binary_for("v0.9.0") == Path("/tmp/fake-platform/dist/v0.9.0/service")
+    assert s.platform_binary_for("v0.9.0") == Path(
+        "/tmp/fake-platform/dist/v0.9.0/service"
+    )

From b54aae946c8eb6b6cf50a4fa3603d87693fb4a73 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 9 Jun 2026 10:54:54 -0400
Subject: [PATCH 05/64] =?UTF-8?q?fix(otdf-local):=20address=20review=20fee?=
 =?UTF-8?q?dback=20=E2=80=94=20instance-aware=20up=20ports,=20cleanup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `up` command now uses `settings.get_platform_port()` and iterates
  `kas_manager._instances` with `settings.get_kas_port()` for health checks
  so non-default instances with a different `ports.base` work correctly
- Add `Settings.get_platform_port()` alongside the existing `get_kas_port()`
- Simplify metadata name update: `instance.metadata.name = name` (frozen=False)
- Use `shlex.join(cmd)` for display in cli_scenario.py
- Add `"Instance | None"` return type to `load_instance` via TYPE_CHECKING
- Drop unused `Path` import in cli.py, stale `os` import in test file

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 otdf-local/src/otdf_local/cli.py             |  7 +++----
 otdf-local/src/otdf_local/cli_instance.py    |  4 +---
 otdf-local/src/otdf_local/cli_scenario.py    |  3 ++-
 otdf-local/src/otdf_local/config/settings.py | 13 ++++++++++++-
 otdf-local/tests/test_multi_instance.py      |  1 -
 5 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/otdf-local/src/otdf_local/cli.py b/otdf-local/src/otdf_local/cli.py
index 422daa65a..efccb289d 100644
--- a/otdf-local/src/otdf_local/cli.py
+++ b/otdf-local/src/otdf_local/cli.py
@@ -5,7 +5,6 @@
 import shutil
 import sys
 import time
-from pathlib import Path
 from typing import Annotated, Optional
 
 import httpx
@@ -189,7 +188,7 @@ def up(
         with status_spinner("Waiting for Platform..."):
             try:
                 wait_for_health(
-                    f"http://localhost:{Ports.PLATFORM}/healthz",
+                    f"http://localhost:{settings.get_platform_port()}/healthz",
                     timeout=120,
                     service_name="Platform",
                 )
@@ -221,8 +220,8 @@ def up(
             raise typer.Exit(1)
 
         with status_spinner("Waiting for KAS instances..."):
-            for kas_name in Ports.all_kas_names():
-                port = Ports.get_kas_port(kas_name)
+            for kas_name in kas_manager._instances:
+                port = settings.get_kas_port(kas_name)
                 try:
                     wait_for_health(
                         f"http://localhost:{port}/healthz",
diff --git a/otdf-local/src/otdf_local/cli_instance.py b/otdf-local/src/otdf_local/cli_instance.py
index 712dc2967..94e4d1a95 100644
--- a/otdf-local/src/otdf_local/cli_instance.py
+++ b/otdf-local/src/otdf_local/cli_instance.py
@@ -79,9 +79,7 @@ def _init_from_scenario(name: str, scenario_path: Path, instance_dir: Path) -> N
     else:
         raise typer.BadParameter(f"{scenario_path} has unknown kind {kind!r}")
     # Ensure the metadata name matches the chosen directory name.
-    instance.metadata = Metadata(
-        **{**instance.metadata.model_dump(exclude_none=True), "name": name}
-    )
+    instance.metadata.name = name
     instance_dir.mkdir(parents=True, exist_ok=True)
     (instance_dir / "kas").mkdir(parents=True, exist_ok=True)
     (instance_dir / "keys").mkdir(mode=0o700, parents=True, exist_ok=True)
diff --git a/otdf-local/src/otdf_local/cli_scenario.py b/otdf-local/src/otdf_local/cli_scenario.py
index 08e8def65..cd9ecf084 100644
--- a/otdf-local/src/otdf_local/cli_scenario.py
+++ b/otdf-local/src/otdf_local/cli_scenario.py
@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import os
+import shlex
 import subprocess
 from pathlib import Path
 from typing import Annotated
@@ -100,6 +101,6 @@ def run(
         pytest_args.extend(extra)
 
     cmd = ["uv", "run", "pytest", *pytest_args]
-    typer.echo(f"  Running: {' '.join(cmd)} (cwd={xtest_root})")
+    typer.echo(f"  Running: {shlex.join(cmd)} (cwd={xtest_root})")
     completed = subprocess.run(cmd, cwd=xtest_root)
     raise typer.Exit(completed.returncode)
diff --git a/otdf-local/src/otdf_local/config/settings.py b/otdf-local/src/otdf_local/config/settings.py
index dffc2cefc..f03cc6e58 100644
--- a/otdf-local/src/otdf_local/config/settings.py
+++ b/otdf-local/src/otdf_local/config/settings.py
@@ -2,8 +2,12 @@
 
 from functools import lru_cache
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from pydantic import Field
+
+if TYPE_CHECKING:
+    from otdf_sdk_mgr.schema import Instance
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from otdf_local.config.ports import Ports
@@ -228,7 +232,14 @@ def get_kas_port(self, name: str) -> int:
             return Ports.get_kas_port(name, base=instance.ports.base)
         return Ports.get_kas_port(name)
 
-    def load_instance(self):
+    def get_platform_port(self) -> int:
+        """Get the platform port, respecting instance ports.base."""
+        instance = self.load_instance()
+        if instance is not None:
+            return Ports.platform_port_for(instance.ports.base)
+        return Ports.PLATFORM
+
+    def load_instance(self) -> "Instance | None":
         """Load the per-instance manifest, or return None when not present."""
         if not self.has_instance():
             return None
diff --git a/otdf-local/tests/test_multi_instance.py b/otdf-local/tests/test_multi_instance.py
index 8c3b44908..04768207c 100644
--- a/otdf-local/tests/test_multi_instance.py
+++ b/otdf-local/tests/test_multi_instance.py
@@ -8,7 +8,6 @@
 
 from __future__ import annotations
 
-import os
 from pathlib import Path
 
 import pytest

From 02d7fd2a97d8a2c005584eb5a22f3cafed7fa80d Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 9 Jun 2026 11:08:03 -0400
Subject: [PATCH 06/64] fix(otdf-local): address pyright errors in cli and
 cli_instance

Guard platform_dir None-access in env command; replace non-existent
PlatformPin.image attribute with "unknown" fallback in ls command.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 otdf-local/src/otdf_local/cli.py          | 10 ++++++----
 otdf-local/src/otdf_local/cli_instance.py |  6 +-----
 2 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/otdf-local/src/otdf_local/cli.py b/otdf-local/src/otdf_local/cli.py
index efccb289d..2b22ad8f6 100644
--- a/otdf-local/src/otdf_local/cli.py
+++ b/otdf-local/src/otdf_local/cli.py
@@ -581,12 +581,14 @@ def env(
 
     # Platform configuration
     env_vars["PLATFORMURL"] = settings.platform_url
-    env_vars["PLATFORM_DIR"] = str(settings.platform_dir.resolve())
+    if settings.platform_dir is not None:
+        env_vars["PLATFORM_DIR"] = str(settings.platform_dir.resolve())
 
     # Schema file for manifest validation
-    schema_file = settings.platform_dir / "sdk" / "schema" / "manifest.schema.json"
-    if schema_file.exists():
-        env_vars["SCHEMA_FILE"] = str(schema_file.resolve())
+    if settings.platform_dir is not None:
+        schema_file = settings.platform_dir / "sdk" / "schema" / "manifest.schema.json"
+        if schema_file.exists():
+            env_vars["SCHEMA_FILE"] = str(schema_file.resolve())
 
     # Log file paths
     platform_log = settings.logs_dir / "platform.log"
diff --git a/otdf-local/src/otdf_local/cli_instance.py b/otdf-local/src/otdf_local/cli_instance.py
index 94e4d1a95..6b6e5da49 100644
--- a/otdf-local/src/otdf_local/cli_instance.py
+++ b/otdf-local/src/otdf_local/cli_instance.py
@@ -244,11 +244,7 @@ def ls(
                 "name": child.name,
                 "platform": (
                     inst.platform.dist
-                    or (
-                        inst.platform.source.ref
-                        if inst.platform.source
-                        else inst.platform.image
-                    )
+                    or (inst.platform.source.ref if inst.platform.source else "unknown")
                 ),
                 "ports_base": inst.ports.base,
                 "kas": list(inst.kas.keys()),

From 3ba16e30a50ec65a9945bd9982c765deea166855 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 9 Jun 2026 12:55:23 -0400
Subject: [PATCH 07/64] fix(otdf-local): address coderabbit review feedback

- cli_scenario: set OTDF_LOCAL_INSTANCE_NAME + clear settings cache before
  get_settings() so scenario-driven instance name is picked up
- cli_instance: add _validate_instance_name() to guard against path traversal
  in init/rm; add --force flag to init to prevent silent overwrite
- kas: add get_instance_names() public method; replace _instances access in cli
- keys: generate_ca_jks() now imports cert only (keytool -importcert) so ca.jks
  is a proper truststore; ensure_keys_exist() guards include cert files alongside
  private keys to catch partial-init broken state

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 otdf-local/src/otdf_local/cli.py          |  2 +-
 otdf-local/src/otdf_local/cli_instance.py | 25 +++++++++
 otdf-local/src/otdf_local/cli_scenario.py |  3 +-
 otdf-local/src/otdf_local/services/kas.py |  4 ++
 otdf-local/src/otdf_local/utils/keys.py   | 64 +++++++++--------------
 5 files changed, 57 insertions(+), 41 deletions(-)

diff --git a/otdf-local/src/otdf_local/cli.py b/otdf-local/src/otdf_local/cli.py
index 2b22ad8f6..a062e62a2 100644
--- a/otdf-local/src/otdf_local/cli.py
+++ b/otdf-local/src/otdf_local/cli.py
@@ -220,7 +220,7 @@ def up(
             raise typer.Exit(1)
 
         with status_spinner("Waiting for KAS instances..."):
-            for kas_name in kas_manager._instances:
+            for kas_name in kas_manager.get_instance_names():
                 port = settings.get_kas_port(kas_name)
                 try:
                     wait_for_health(
diff --git a/otdf-local/src/otdf_local/cli_instance.py b/otdf-local/src/otdf_local/cli_instance.py
index 6b6e5da49..6fc06f1ea 100644
--- a/otdf-local/src/otdf_local/cli_instance.py
+++ b/otdf-local/src/otdf_local/cli_instance.py
@@ -22,6 +22,17 @@
 instance_app = typer.Typer(help="Manage named test environment instances.")
 
 
+def _validate_instance_name(name: str) -> None:
+    """Reject names that could escape the instances root via path traversal."""
+    from pathlib import PurePosixPath
+
+    p = PurePosixPath(name)
+    if not name or p.is_absolute() or len(p.parts) != 1 or name in {".", ".."}:
+        raise typer.BadParameter(
+            f"instance name must be a single directory name, got {name!r}"
+        )
+
+
 @instance_app.command("init")
 def init(
     name: Annotated[str, typer.Argument(help="Instance name (used as directory name)")],
@@ -41,11 +52,24 @@ def init(
         Optional[str],
         typer.Option("--platform", help="Platform dist version (e.g., v0.9.0)"),
     ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite existing instance directory"),
+    ] = False,
 ) -> None:
     """Scaffold a new instance directory at tests/instances/<name>/."""
+    _validate_instance_name(name)
     settings = get_settings()
     instance_dir = settings.instances_root / name
 
+    if instance_dir.exists() and not force:
+        typer.echo(
+            f"Error: instance '{name}' already exists at {instance_dir}. "
+            "Pass --force to overwrite.",
+            err=True,
+        )
+        raise typer.Exit(2)
+
     if from_scenario is not None:
         _init_from_scenario(name, from_scenario, instance_dir)
     else:
@@ -263,6 +287,7 @@ def rm(
     yes: Annotated[bool, typer.Option("--yes", "-y", help="Skip confirmation")] = False,
 ) -> None:
     """Remove an instance directory."""
+    _validate_instance_name(name)
     settings = get_settings()
     instance_dir = settings.instances_root / name
     if not instance_dir.exists():
diff --git a/otdf-local/src/otdf_local/cli_scenario.py b/otdf-local/src/otdf_local/cli_scenario.py
index cd9ecf084..cbd9cb227 100644
--- a/otdf-local/src/otdf_local/cli_scenario.py
+++ b/otdf-local/src/otdf_local/cli_scenario.py
@@ -80,9 +80,10 @@ def run(
         )
         raise typer.Exit(2)
 
-    settings = get_settings()
     # Force the chosen instance via env so child pytest invocations agree.
     os.environ["OTDF_LOCAL_INSTANCE_NAME"] = instance_name
+    get_settings.cache_clear()
+    settings = get_settings()
 
     xtest_root = settings.xtest_root
     if not xtest_root.exists():
diff --git a/otdf-local/src/otdf_local/services/kas.py b/otdf-local/src/otdf_local/services/kas.py
index 7c7e5cd6f..582bf98cc 100644
--- a/otdf-local/src/otdf_local/services/kas.py
+++ b/otdf-local/src/otdf_local/services/kas.py
@@ -251,6 +251,10 @@ def get_all_info(self) -> list[ServiceInfo]:
         """Get info for all KAS instances."""
         return [instance.get_info() for instance in self._instances.values()]
 
+    def get_instance_names(self) -> list[str]:
+        """Return names of all managed KAS instances."""
+        return list(self._instances.keys())
+
     def get_running(self) -> list[str]:
         """Get names of running KAS instances."""
         return [name for name, inst in self._instances.items() if inst.is_running()]
diff --git a/otdf-local/src/otdf_local/utils/keys.py b/otdf-local/src/otdf_local/utils/keys.py
index 5dd5fe5fe..95cd4c612 100644
--- a/otdf-local/src/otdf_local/utils/keys.py
+++ b/otdf-local/src/otdf_local/utils/keys.py
@@ -234,41 +234,23 @@ def generate_localhost_cert(key_dir: Path) -> tuple[Path, Path]:
 
 
 def generate_ca_jks(key_dir: Path, password: str = "password") -> Path:
-    """Convert the keycloak CA into the JKS truststore Keycloak mounts.
+    """Convert the keycloak CA certificate into a JKS truststore Keycloak mounts.
 
     Uses keytool inside the keycloak/keycloak:25.0 image so we don't need a
     local JDK — docker is already a hard dependency for the test env.
     Requires generate_localhost_cert() to have run first.
+
+    Only the CA certificate (public) is imported — not the private key — so the
+    JKS is a proper truststore, not a keystore.
     """
-    ca_key = key_dir / "keycloak-ca-private.pem"
     ca_cert = key_dir / "keycloak-ca.pem"
-    if not ca_key.exists() or not ca_cert.exists():
+    if not ca_cert.exists():
         raise FileNotFoundError(
-            f"CA files missing in {key_dir}; call generate_localhost_cert() first"
+            f"CA certificate missing in {key_dir}; call generate_localhost_cert() first"
         )
-    p12 = key_dir / "ca.p12"
     jks = key_dir / "ca.jks"
 
-    subprocess.run(
-        [
-            "openssl",
-            "pkcs12",
-            "-export",
-            "-in",
-            str(ca_cert),
-            "-inkey",
-            str(ca_key),
-            "-out",
-            str(p12),
-            "-nodes",
-            "-passout",
-            f"pass:{password}",
-        ],
-        check=True,
-        capture_output=True,
-    )
-
-    # keytool -importkeystore via the keycloak image (matches init-temp-keys.sh)
+    # keytool -importcert via the keycloak image: cert-only truststore entry
     result = subprocess.run(
         [
             "docker",
@@ -281,18 +263,16 @@ def generate_ca_jks(key_dir: Path, password: str = "password") -> Path:
             "--user",
             f"{os.getuid()}:{os.getgid()}",
             "keycloak/keycloak:25.0",
-            "-importkeystore",
-            "-srckeystore",
-            "/keys/ca.p12",
-            "-srcstoretype",
-            "PKCS12",
-            "-destkeystore",
+            "-importcert",
+            "-file",
+            "/keys/keycloak-ca.pem",
+            "-alias",
+            "ca",
+            "-keystore",
             "/keys/ca.jks",
-            "-deststoretype",
+            "-storetype",
             "JKS",
-            "-srcstorepass",
-            password,
-            "-deststorepass",
+            "-storepass",
             password,
             "-noprompt",
         ],
@@ -301,7 +281,7 @@ def generate_ca_jks(key_dir: Path, password: str = "password") -> Path:
     )
     if result.returncode != 0:
         raise RuntimeError(
-            f"keytool failed converting PKCS12 → JKS:\n{result.stderr}\n"
+            f"keytool failed importing CA cert into JKS truststore:\n{result.stderr}\n"
             "Ensure Docker is running and `keycloak/keycloak:25.0` is pullable."
         )
     return jks
@@ -323,24 +303,30 @@ def ensure_keys_exist(key_dir: Path, force: bool = False) -> bool:
         True if any keys were generated, False if everything already existed
     """
     rsa_private = key_dir / "kas-private.pem"
+    rsa_cert = key_dir / "kas-cert.pem"
     ec_private = key_dir / "kas-ec-private.pem"
+    ec_cert = key_dir / "kas-ec-cert.pem"
     localhost_key = key_dir / "localhost.key"
+    localhost_cert = key_dir / "localhost.crt"
     ca_jks = key_dir / "ca.jks"
 
     if (
         not force
         and rsa_private.exists()
+        and rsa_cert.exists()
         and ec_private.exists()
+        and ec_cert.exists()
         and localhost_key.exists()
+        and localhost_cert.exists()
         and ca_jks.exists()
     ):
         return False
 
-    if force or not rsa_private.exists():
+    if force or not rsa_private.exists() or not rsa_cert.exists():
         generate_rsa_keypair(key_dir, "kas")
-    if force or not ec_private.exists():
+    if force or not ec_private.exists() or not ec_cert.exists():
         generate_ec_keypair(key_dir, "kas-ec")
-    if force or not localhost_key.exists():
+    if force or not localhost_key.exists() or not localhost_cert.exists():
         generate_localhost_cert(key_dir)
     if force or not ca_jks.exists():
         generate_ca_jks(key_dir)

From 0e89a71162129f6b327de1e23cd3108831903004 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 9 Jun 2026 13:50:07 -0400
Subject: [PATCH 08/64] =?UTF-8?q?fix(otdf-local):=20restore=20PKCS12?=
 =?UTF-8?q?=E2=86=92JKS=20flow=20in=20generate=5Fca=5Fjks?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reverts the keytool -importcert change from the previous commit.
The PKCS12 + importkeystore approach mirrors init-temp-keys.sh in the
platform repo exactly (lines 65-90); Keycloak requires this form of
ca.jks and the cert-only truststore broke it.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 otdf-local/src/otdf_local/utils/keys.py | 53 +++++++++++++++++--------
 1 file changed, 37 insertions(+), 16 deletions(-)

diff --git a/otdf-local/src/otdf_local/utils/keys.py b/otdf-local/src/otdf_local/utils/keys.py
index 95cd4c612..b0812a0c9 100644
--- a/otdf-local/src/otdf_local/utils/keys.py
+++ b/otdf-local/src/otdf_local/utils/keys.py
@@ -234,23 +234,42 @@ def generate_localhost_cert(key_dir: Path) -> tuple[Path, Path]:
 
 
 def generate_ca_jks(key_dir: Path, password: str = "password") -> Path:
-    """Convert the keycloak CA certificate into a JKS truststore Keycloak mounts.
+    """Convert the keycloak CA into the JKS file Keycloak mounts.
 
+    Mirrors the PKCS12 → JKS flow in the platform's init-temp-keys.sh exactly.
     Uses keytool inside the keycloak/keycloak:25.0 image so we don't need a
     local JDK — docker is already a hard dependency for the test env.
     Requires generate_localhost_cert() to have run first.
-
-    Only the CA certificate (public) is imported — not the private key — so the
-    JKS is a proper truststore, not a keystore.
     """
+    ca_key = key_dir / "keycloak-ca-private.pem"
     ca_cert = key_dir / "keycloak-ca.pem"
-    if not ca_cert.exists():
+    if not ca_key.exists() or not ca_cert.exists():
         raise FileNotFoundError(
-            f"CA certificate missing in {key_dir}; call generate_localhost_cert() first"
+            f"CA files missing in {key_dir}; call generate_localhost_cert() first"
         )
+    p12 = key_dir / "ca.p12"
     jks = key_dir / "ca.jks"
 
-    # keytool -importcert via the keycloak image: cert-only truststore entry
+    subprocess.run(
+        [
+            "openssl",
+            "pkcs12",
+            "-export",
+            "-in",
+            str(ca_cert),
+            "-inkey",
+            str(ca_key),
+            "-out",
+            str(p12),
+            "-nodes",
+            "-passout",
+            f"pass:{password}",
+        ],
+        check=True,
+        capture_output=True,
+    )
+
+    # keytool -importkeystore via the keycloak image (matches init-temp-keys.sh)
     result = subprocess.run(
         [
             "docker",
@@ -263,16 +282,18 @@ def generate_ca_jks(key_dir: Path, password: str = "password") -> Path:
             "--user",
             f"{os.getuid()}:{os.getgid()}",
             "keycloak/keycloak:25.0",
-            "-importcert",
-            "-file",
-            "/keys/keycloak-ca.pem",
-            "-alias",
-            "ca",
-            "-keystore",
+            "-importkeystore",
+            "-srckeystore",
+            "/keys/ca.p12",
+            "-srcstoretype",
+            "PKCS12",
+            "-destkeystore",
             "/keys/ca.jks",
-            "-storetype",
+            "-deststoretype",
             "JKS",
-            "-storepass",
+            "-srcstorepass",
+            password,
+            "-deststorepass",
             password,
             "-noprompt",
         ],
@@ -281,7 +302,7 @@ def generate_ca_jks(key_dir: Path, password: str = "password") -> Path:
     )
     if result.returncode != 0:
         raise RuntimeError(
-            f"keytool failed importing CA cert into JKS truststore:\n{result.stderr}\n"
+            f"keytool failed converting PKCS12 → JKS:\n{result.stderr}\n"
             "Ensure Docker is running and `keycloak/keycloak:25.0` is pullable."
         )
     return jks

From 36e3147f5a040d6d91799e6a176676c49bdc89c8 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 9 Jun 2026 15:54:14 -0400
Subject: [PATCH 09/64] docs: add simplification design spec for multi-instance
 PR

---
 ...06-09-simplify-multi-instance-pr-design.md | 76 +++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-09-simplify-multi-instance-pr-design.md

diff --git a/docs/superpowers/specs/2026-06-09-simplify-multi-instance-pr-design.md b/docs/superpowers/specs/2026-06-09-simplify-multi-instance-pr-design.md
new file mode 100644
index 000000000..f52d0978a
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-09-simplify-multi-instance-pr-design.md
@@ -0,0 +1,76 @@
+# Simplify Multi-Instance PR — Design
+
+**Date:** 2026-06-09  
+**Branch:** DSPX-3302-03-multi-instance  
+**Scope:** Code-quality cleanup within the existing PR; no scope reduction.
+
+## Problem
+
+The multi-instance PR introduces three independent copies of the same binary/worktree resolution logic:
+
+- `KASService._instance_paths()` in `services/kas.py`
+- `PlatformService._instance_dist_paths()` in `services/platform.py`
+- `_resolve_platform_worktree()` in `cli_instance.py`
+
+All three do: load instance manifest → extract dist string → locate binary under `get_platform_dir()/dist/<dist>/service` → read `.version` file for `worktree=<path>` line → return `(binary, worktree)`.
+
+Additionally:
+- `settings.load_instance()` re-reads and parses YAML from disk on every call; it is invoked on nearly every property access in the service classes.
+- `Ports` has two parallel lookup tables (`_KAS_NAMES` mapping names to class attributes, and `KAS_OFFSETS` mapping names to ints) that represent the same domain. The legacy constants are numerically equal to `8080 + offset`, so `_KAS_NAMES` is misleading dead weight.
+
+## Design
+
+### 1. `Settings.resolve_binary_worktree(dist: str) -> tuple[Path, Path]`
+
+Add a single method to `Settings` that encapsulates binary-path resolution:
+
+1. Compute `binary = get_platform_dir() / "dist" / dist / "service"`.
+2. Raise `FileNotFoundError` with a `otdf-sdk-mgr install` hint if the binary is missing.
+3. Read `binary.parent / ".version"` and extract the `worktree=<path>` line if present; fall back to `binary.parent` if the file is absent or has no such line.
+4. Return `(binary, worktree)`.
+
+### 2. Cache `load_instance()` on the Settings instance
+
+`load_instance()` stores its result in a private `_instance_cache` attribute on first call (`None` sentinel, `False` meaning "no instance"). Because `Settings` is already invalidated via `get_settings.cache_clear()` whenever `--instance` is set or `scenario run` overrides the instance name, caching on the instance is safe.
+
+### 3. Simplify callers
+
+`KASService._instance_paths()` and `PlatformService._instance_dist_paths()` are reduced to:
+- Call `settings.load_instance()` to get the manifest (or `None`).
+- Extract the relevant `dist` string (kas pin or platform pin).
+- Delegate to `settings.resolve_binary_worktree(dist)`.
+
+`_resolve_platform_worktree()` in `cli_instance.py` is deleted; its callers use `settings.resolve_binary_worktree(dist_name)` directly.
+
+The `if instance_paths is not None: ..., worktree = instance_paths[1]; else: platform_dir = self.settings._require_platform_dir()` fallback pattern remains in both service `_generate_config()` methods — it is now 4–5 lines each and clearly readable.
+
+### 4. Unify `Ports` lookup
+
+Remove `_KAS_NAMES` (the name → class-attribute map) and the duplicated `ALPHA`, `BETA`, … constants that back it. Rewrite `get_kas_port` to always use `KAS_OFFSETS` with a default `base=8080`:
+
+```python
+@classmethod
+def get_kas_port(cls, name: str, *, base: int = 8080) -> int:
+    offset = cls.KAS_OFFSETS.get(name)
+    if offset is None:
+        raise ValueError(f"Unknown KAS instance: {name}")
+    return base + offset
+```
+
+The numeric values are unchanged (8080+101=8181, etc.). Any callers that were using the class constants directly (e.g., `Ports.ALPHA`) are updated to `Ports.get_kas_port("alpha")`.
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `otdf-local/src/otdf_local/config/settings.py` | Add `resolve_binary_worktree()`, cache `load_instance()` |
+| `otdf-local/src/otdf_local/config/ports.py` | Remove `_KAS_NAMES`, unify `get_kas_port` to use `KAS_OFFSETS` |
+| `otdf-local/src/otdf_local/services/kas.py` | Shrink `_instance_paths()` to delegate |
+| `otdf-local/src/otdf_local/services/platform.py` | Shrink `_instance_dist_paths()` to delegate |
+| `otdf-local/src/otdf_local/cli_instance.py` | Delete `_resolve_platform_worktree()`, inline the simpler call |
+
+## Out of Scope
+
+- Splitting the PR into smaller PRs (user confirmed code quality only).
+- Changing the `InstanceContext` dataclass approach (A chosen over B).
+- Touching test files or non-`otdf-local` packages.

From a86d59a922b470e0cd64556032f58558532447f0 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 09:41:13 -0400
Subject: [PATCH 10/64] refactor(otdf-local): unify Ports.get_kas_port to
 always use KAS_OFFSETS

---
 otdf-local/src/otdf_local/config/ports.py | 39 +++--------------------
 1 file changed, 5 insertions(+), 34 deletions(-)

diff --git a/otdf-local/src/otdf_local/config/ports.py b/otdf-local/src/otdf_local/config/ports.py
index 913f970d0..c14053659 100644
--- a/otdf-local/src/otdf_local/config/ports.py
+++ b/otdf-local/src/otdf_local/config/ports.py
@@ -15,24 +15,6 @@ class Ports:
     # Platform
     PLATFORM: int = 8080
 
-    # KAS instances
-    KAS_ALPHA: int = 8181
-    KAS_BETA: int = 8282
-    KAS_GAMMA: int = 8383
-    KAS_DELTA: int = 8484
-    KAS_KM1: int = 8585
-    KAS_KM2: int = 8686
-
-    # Mapping from KAS name to class attribute name
-    _KAS_NAMES: ClassVar[dict[str, str]] = {
-        "alpha": "KAS_ALPHA",
-        "beta": "KAS_BETA",
-        "gamma": "KAS_GAMMA",
-        "delta": "KAS_DELTA",
-        "km1": "KAS_KM1",
-        "km2": "KAS_KM2",
-    }
-
     # Offset of each KAS port from `base` (which is the platform port).
     # The defaults at base=8080 reproduce the historical 8181/8282/... layout.
     KAS_OFFSETS: ClassVar[dict[str, int]] = {
@@ -45,22 +27,11 @@ class Ports:
     }
 
     @classmethod
-    def get_kas_port(cls, name: str, *, base: int | None = None) -> int:
-        """Get port for a KAS instance by name.
-
-        When `base` is provided, the port is computed as `base + offset` so
-        multiple instances can coexist on disjoint port ranges. Otherwise the
-        legacy class constants are returned (base=8080 layout).
-        """
-        if base is not None:
-            offset = cls.KAS_OFFSETS.get(name)
-            if offset is None:
-                raise ValueError(f"Unknown KAS instance: {name}")
-            return base + offset
-        attr = cls._KAS_NAMES.get(name)
-        if attr is None:
+    def get_kas_port(cls, name: str, *, base: int = 8080) -> int:
+        offset = cls.KAS_OFFSETS.get(name)
+        if offset is None:
             raise ValueError(f"Unknown KAS instance: {name}")
-        return getattr(cls, attr)
+        return base + offset
 
     @classmethod
     def platform_port_for(cls, base: int) -> int:
@@ -70,7 +41,7 @@ def platform_port_for(cls, base: int) -> int:
     @classmethod
     def all_kas_names(cls) -> list[str]:
         """Return all KAS instance names."""
-        return list(cls._KAS_NAMES.keys())
+        return list(cls.KAS_OFFSETS.keys())
 
     @classmethod
     def standard_kas_names(cls) -> list[str]:

From 2fbd9770be48b80d9d3897d73f807038d1658ba8 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 10:22:57 -0400
Subject: [PATCH 11/64] refactor(otdf-local): add resolve_binary_worktree() and
 cache load_instance() on Settings

---
 otdf-local/src/otdf_local/config/settings.py | 39 +++++++++++++++++---
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/otdf-local/src/otdf_local/config/settings.py b/otdf-local/src/otdf_local/config/settings.py
index f03cc6e58..7de066b68 100644
--- a/otdf-local/src/otdf_local/config/settings.py
+++ b/otdf-local/src/otdf_local/config/settings.py
@@ -4,7 +4,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from pydantic import Field
+from pydantic import Field, PrivateAttr
 
 if TYPE_CHECKING:
     from otdf_sdk_mgr.schema import Instance
@@ -108,6 +108,8 @@ class Settings(BaseSettings):
         extra="ignore",
     )
 
+    _instance_cache: object = PrivateAttr(default=None)
+
     # Directory paths - computed from xtest_root
     xtest_root: Path = Field(default_factory=_find_xtest_root)
     platform_dir: Path | None = Field(
@@ -153,6 +155,26 @@ def platform_binary_for(self, dist: str) -> Path:
 
         return get_platform_dir() / "dist" / dist / "service"
 
+    def resolve_binary_worktree(self, dist: str) -> tuple[Path, Path]:
+        """Resolve a dist string to (binary, worktree), raising if the binary is missing.
+
+        Reads the `.version` file next to the binary for a `worktree=<path>` line;
+        falls back to `binary.parent` when the file is absent or has no such line.
+        """
+        binary = self.platform_binary_for(dist)
+        if not binary.exists():
+            raise FileNotFoundError(
+                f"Binary not found at {binary}. Run `otdf-sdk-mgr install` to provision it."
+            )
+        worktree = binary.parent
+        version_file = binary.parent / ".version"
+        if version_file.exists():
+            for line in version_file.read_text().splitlines():
+                if line.startswith("worktree="):
+                    worktree = Path(line.split("=", 1)[1].strip())
+                    break
+        return binary, worktree
+
     @property
     def logs_dir(self) -> Path:
         """Logs directory. Per-instance when an instance is selected, falls back to legacy."""
@@ -240,12 +262,17 @@ def get_platform_port(self) -> int:
         return Ports.PLATFORM
 
     def load_instance(self) -> "Instance | None":
-        """Load the per-instance manifest, or return None when not present."""
-        if not self.has_instance():
+        """Load the per-instance manifest, cached on first call."""
+        if self._instance_cache is None:
+            if not self.has_instance():
+                self._instance_cache = False
+            else:
+                from otdf_sdk_mgr.schema import load_instance as _load
+
+                self._instance_cache = _load(self.instance_yaml)
+        if self._instance_cache is False:
             return None
-        from otdf_sdk_mgr.schema import load_instance as _load
-
-        return _load(self.instance_yaml)
+        return self._instance_cache  # type: ignore[return-value]
 
     def get_kas_config_path(self, name: str) -> Path:
         """Get config file path for a KAS instance."""

From d319600b877bba5fc71a3733e8698adfdc16613c Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 10:33:13 -0400
Subject: [PATCH 12/64] refactor(otdf-local): delegate
 KASService._instance_paths() to settings.resolve_binary_worktree

---
 otdf-local/src/otdf_local/services/kas.py | 15 +--------------
 1 file changed, 1 insertion(+), 14 deletions(-)

diff --git a/otdf-local/src/otdf_local/services/kas.py b/otdf-local/src/otdf_local/services/kas.py
index 582bf98cc..a4b616a63 100644
--- a/otdf-local/src/otdf_local/services/kas.py
+++ b/otdf-local/src/otdf_local/services/kas.py
@@ -65,20 +65,7 @@ def _instance_paths(self) -> tuple[Path, Path] | None:
         pin = instance.kas.get(self._kas_name)
         if pin is None or pin.dist is None:
             return None
-        binary = self.settings.platform_binary_for(pin.dist)
-        if not binary.exists():
-            raise FileNotFoundError(
-                f"KAS {self._kas_name} binary not found at {binary}. "
-                f"Run `otdf-sdk-mgr install release platform:{pin.dist}`."
-            )
-        worktree = binary.parent
-        version_file = binary.parent / ".version"
-        if version_file.exists():
-            for line in version_file.read_text().splitlines():
-                if line.startswith("worktree="):
-                    worktree = Path(line.split("=", 1)[1].strip())
-                    break
-        return binary, worktree
+        return self.settings.resolve_binary_worktree(pin.dist)
 
     def _generate_config(self) -> Path:
         """Generate the KAS config file from template."""

From 3a8699cb355ae4b84e44186d68b4fcf3f0c74b20 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 10:33:42 -0400
Subject: [PATCH 13/64] refactor(otdf-local): delegate
 PlatformService._instance_dist_paths() to settings.resolve_binary_worktree

---
 .../src/otdf_local/services/platform.py       | 23 ++-----------------
 1 file changed, 2 insertions(+), 21 deletions(-)

diff --git a/otdf-local/src/otdf_local/services/platform.py b/otdf-local/src/otdf_local/services/platform.py
index 3f2ad9cb0..66d61b820 100644
--- a/otdf-local/src/otdf_local/services/platform.py
+++ b/otdf-local/src/otdf_local/services/platform.py
@@ -54,30 +54,11 @@ def health_url(self) -> str:
         return f"http://localhost:{self.port}/healthz"
 
     def _instance_dist_paths(self) -> tuple[Path, Path] | None:
-        """Return (binary, worktree) for an instance-pinned platform, or None.
-
-        The platform binary is at `xtest/platform/dist/<dist>/service` and its
-        `.version` file records the source worktree path that should be used
-        as `cwd` so the binary finds its embedded resources.
-        """
+        """Return (binary, worktree) for an instance-pinned platform, or None."""
         instance = self.settings.load_instance()
         if instance is None or instance.platform.dist is None:
             return None
-        binary = self.settings.platform_binary_for(instance.platform.dist)
-        if not binary.exists():
-            raise FileNotFoundError(
-                f"Platform binary not found at {binary}. "
-                f"Run `otdf-sdk-mgr install release platform:{instance.platform.dist}` "
-                f"or `otdf-sdk-mgr install scenario` to provision it."
-            )
-        worktree = binary.parent  # safe fallback
-        version_file = binary.parent / ".version"
-        if version_file.exists():
-            for line in version_file.read_text().splitlines():
-                if line.startswith("worktree="):
-                    worktree = Path(line.split("=", 1)[1].strip())
-                    break
-        return binary, worktree
+        return self.settings.resolve_binary_worktree(instance.platform.dist)
 
     def _generate_config(self) -> Path:
         """Generate the platform config file from template.

From 653db219dce2669e7fac03eaf7884bfa11ee4ba8 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 10:34:25 -0400
Subject: [PATCH 14/64] refactor(otdf-local): delete
 _resolve_platform_worktree(), inline into _provision_instance_dir()

---
 otdf-local/src/otdf_local/cli_instance.py | 56 +++++------------------
 1 file changed, 12 insertions(+), 44 deletions(-)

diff --git a/otdf-local/src/otdf_local/cli_instance.py b/otdf-local/src/otdf_local/cli_instance.py
index 6fc06f1ea..2463d6a7a 100644
--- a/otdf-local/src/otdf_local/cli_instance.py
+++ b/otdf-local/src/otdf_local/cli_instance.py
@@ -130,49 +130,6 @@ def _init_minimal(
     _provision_instance_dir(instance_dir, instance)
 
 
-def _resolve_platform_worktree(instance: Instance) -> Path:
-    """Find the platform source worktree for this instance's pin.
-
-    For both `dist` and `source` pins, the platform installer writes a
-    `.version` file next to the binary with `worktree=<path>`. We follow
-    that pointer because the binary's parent directory only holds the
-    built artifact — the YAML templates live in the source tree.
-    """
-    from otdf_sdk_mgr.platform_installer import get_platform_dir
-    from otdf_sdk_mgr.refs import expand_pr_shorthand, ref_slug
-
-    settings = Settings()
-    pin = instance.platform
-    if pin.dist is not None:
-        dist_name = pin.dist
-    elif pin.source is not None:
-        dist_name = ref_slug(expand_pr_shorthand(pin.source.ref))
-    else:
-        raise typer.BadParameter("instance.platform must set dist or source")
-
-    binary = get_platform_dir() / "dist" / dist_name / "service"
-    if not binary.exists():
-        raise FileNotFoundError(
-            f"Platform binary not found at {binary}. "
-            f"Run `otdf-sdk-mgr install scenario` (or `install release platform:<v>`) "
-            f"to provision it before `instance init`."
-        )
-    version_file = binary.parent / ".version"
-    if version_file.exists():
-        for line in version_file.read_text().splitlines():
-            if line.startswith("worktree="):
-                worktree = Path(line.split("=", 1)[1].strip())
-                if worktree.is_dir():
-                    return worktree
-    # Fallback to sibling platform dir (legacy single-instance layout).
-    if settings.platform_dir is not None:
-        return settings.platform_dir
-    raise FileNotFoundError(
-        f"Could not resolve platform source worktree from {version_file}; "
-        f"no sibling platform/ directory available either."
-    )
-
-
 def _provision_instance_dir(instance_dir: Path, instance: Instance) -> None:
     """Generate the bootstrap bundle: keys + opentdf.yaml with a fresh root_key.
 
@@ -188,7 +145,18 @@ def _provision_instance_dir(instance_dir: Path, instance: Instance) -> None:
     if config_path.exists():
         return
 
-    worktree = _resolve_platform_worktree(instance)
+    pin = instance.platform
+    if pin.dist is not None:
+        dist_name = pin.dist
+    elif pin.source is not None:
+        from otdf_sdk_mgr.refs import expand_pr_shorthand, ref_slug
+
+        dist_name = ref_slug(expand_pr_shorthand(pin.source.ref))
+    else:
+        raise typer.BadParameter("instance.platform must set dist or source")
+
+    _, worktree = Settings().resolve_binary_worktree(dist_name)
+
     template = worktree / "opentdf-dev.yaml"
     if not template.is_file():
         template = worktree / "opentdf-example.yaml"

From 1842283e154ade1edf82675dc1f5aeab78550a6b Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 10:37:28 -0400
Subject: [PATCH 15/64] fixup remove devlocal spec

---
 ...06-09-simplify-multi-instance-pr-design.md | 76 -------------------
 1 file changed, 76 deletions(-)
 delete mode 100644 docs/superpowers/specs/2026-06-09-simplify-multi-instance-pr-design.md

diff --git a/docs/superpowers/specs/2026-06-09-simplify-multi-instance-pr-design.md b/docs/superpowers/specs/2026-06-09-simplify-multi-instance-pr-design.md
deleted file mode 100644
index f52d0978a..000000000
--- a/docs/superpowers/specs/2026-06-09-simplify-multi-instance-pr-design.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# Simplify Multi-Instance PR — Design
-
-**Date:** 2026-06-09  
-**Branch:** DSPX-3302-03-multi-instance  
-**Scope:** Code-quality cleanup within the existing PR; no scope reduction.
-
-## Problem
-
-The multi-instance PR introduces three independent copies of the same binary/worktree resolution logic:
-
-- `KASService._instance_paths()` in `services/kas.py`
-- `PlatformService._instance_dist_paths()` in `services/platform.py`
-- `_resolve_platform_worktree()` in `cli_instance.py`
-
-All three do: load instance manifest → extract dist string → locate binary under `get_platform_dir()/dist/<dist>/service` → read `.version` file for `worktree=<path>` line → return `(binary, worktree)`.
-
-Additionally:
-- `settings.load_instance()` re-reads and parses YAML from disk on every call; it is invoked on nearly every property access in the service classes.
-- `Ports` has two parallel lookup tables (`_KAS_NAMES` mapping names to class attributes, and `KAS_OFFSETS` mapping names to ints) that represent the same domain. The legacy constants are numerically equal to `8080 + offset`, so `_KAS_NAMES` is misleading dead weight.
-
-## Design
-
-### 1. `Settings.resolve_binary_worktree(dist: str) -> tuple[Path, Path]`
-
-Add a single method to `Settings` that encapsulates binary-path resolution:
-
-1. Compute `binary = get_platform_dir() / "dist" / dist / "service"`.
-2. Raise `FileNotFoundError` with a `otdf-sdk-mgr install` hint if the binary is missing.
-3. Read `binary.parent / ".version"` and extract the `worktree=<path>` line if present; fall back to `binary.parent` if the file is absent or has no such line.
-4. Return `(binary, worktree)`.
-
-### 2. Cache `load_instance()` on the Settings instance
-
-`load_instance()` stores its result in a private `_instance_cache` attribute on first call (`None` sentinel, `False` meaning "no instance"). Because `Settings` is already invalidated via `get_settings.cache_clear()` whenever `--instance` is set or `scenario run` overrides the instance name, caching on the instance is safe.
-
-### 3. Simplify callers
-
-`KASService._instance_paths()` and `PlatformService._instance_dist_paths()` are reduced to:
-- Call `settings.load_instance()` to get the manifest (or `None`).
-- Extract the relevant `dist` string (kas pin or platform pin).
-- Delegate to `settings.resolve_binary_worktree(dist)`.
-
-`_resolve_platform_worktree()` in `cli_instance.py` is deleted; its callers use `settings.resolve_binary_worktree(dist_name)` directly.
-
-The `if instance_paths is not None: ..., worktree = instance_paths[1]; else: platform_dir = self.settings._require_platform_dir()` fallback pattern remains in both service `_generate_config()` methods — it is now 4–5 lines each and clearly readable.
-
-### 4. Unify `Ports` lookup
-
-Remove `_KAS_NAMES` (the name → class-attribute map) and the duplicated `ALPHA`, `BETA`, … constants that back it. Rewrite `get_kas_port` to always use `KAS_OFFSETS` with a default `base=8080`:
-
-```python
-@classmethod
-def get_kas_port(cls, name: str, *, base: int = 8080) -> int:
-    offset = cls.KAS_OFFSETS.get(name)
-    if offset is None:
-        raise ValueError(f"Unknown KAS instance: {name}")
-    return base + offset
-```
-
-The numeric values are unchanged (8080+101=8181, etc.). Any callers that were using the class constants directly (e.g., `Ports.ALPHA`) are updated to `Ports.get_kas_port("alpha")`.
-
-## Files Changed
-
-| File | Change |
-|------|--------|
-| `otdf-local/src/otdf_local/config/settings.py` | Add `resolve_binary_worktree()`, cache `load_instance()` |
-| `otdf-local/src/otdf_local/config/ports.py` | Remove `_KAS_NAMES`, unify `get_kas_port` to use `KAS_OFFSETS` |
-| `otdf-local/src/otdf_local/services/kas.py` | Shrink `_instance_paths()` to delegate |
-| `otdf-local/src/otdf_local/services/platform.py` | Shrink `_instance_dist_paths()` to delegate |
-| `otdf-local/src/otdf_local/cli_instance.py` | Delete `_resolve_platform_worktree()`, inline the simpler call |
-
-## Out of Scope
-
-- Splitting the PR into smaller PRs (user confirmed code quality only).
-- Changing the `InstanceContext` dataclass approach (A chosen over B).
-- Touching test files or non-`otdf-local` packages.

From 837416f93579a9c7194009b0ad30494fd52295bf Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 15 May 2026 11:45:34 -0400
Subject: [PATCH 16/64] feat(xtest): --scenario and --instance flags for
 conftest (DSPX-3302)

Adds two new pytest CLI options so xtest can be driven by a scenarios.yaml
and run against a specific otdf-local instance.

  --scenario PATH    When set, defaults --sdks-encrypt, --sdks-decrypt,
                     and --containers from the scenario's `sdks` and
                     `suite` blocks. Options explicitly passed on the
                     CLI always override.
  --instance NAME    Propagated to OTDF_LOCAL_INSTANCE_NAME so child
                     `otdf-local` invocations within the test see the
                     same instance the scenario expects.

If otdf-sdk-mgr is not installed (minimal pytest environments), the
--scenario flag silently no-ops via an ImportError guard. The flag
shape is invariant either way so CI configs don't fork.

This is the consumer side of the PR 3 / scenario-driven flow: the
authoritative entry point remains `otdf-local scenario run <path>`,
which sets these flags for you; this PR lets pytest accept them
directly when running scenario-aware sessions outside the wrapper.

Refs: https://virtru.atlassian.net/browse/DSPX-3302

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 xtest/conftest.py | 62 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/xtest/conftest.py b/xtest/conftest.py
index eaa88c342..e4abd289c 100644
--- a/xtest/conftest.py
+++ b/xtest/conftest.py
@@ -78,6 +78,16 @@ def sdk_spec_type(v: str) -> str:
 
 def pytest_addoption(parser: pytest.Parser):
     """Add custom CLI options for pytest."""
+    parser.addoption(
+        "--scenario",
+        help="path to scenarios.yaml; --sdks-encrypt/--sdks-decrypt/--containers default from it",
+        type=Path,
+    )
+    parser.addoption(
+        "--instance",
+        help="otdf-local instance name; sets OTDF_LOCAL_INSTANCE_NAME for child tooling",
+        type=str,
+    )
     parser.addoption(
         "--audit-log-dir",
         help="directory to write audit logs on test failure (default: tmp/audit-logs)",
@@ -130,6 +140,58 @@ def pytest_addoption(parser: pytest.Parser):
     )
 
 
+def pytest_configure(config: pytest.Config) -> None:
+    """Apply --scenario defaults and --instance env-var threading.
+
+    When `--scenario PATH` is given, missing `--sdks-encrypt`, `--sdks-decrypt`,
+    and `--containers` options are populated from the scenario file. Options
+    explicitly passed on the CLI always win. `--instance NAME` is propagated
+    via `OTDF_LOCAL_INSTANCE_NAME` so any child `otdf-local` invocation sees
+    the same instance.
+    """
+    import os
+
+    instance = config.getoption("--instance")
+    if instance:
+        os.environ["OTDF_LOCAL_INSTANCE_NAME"] = instance
+
+    scenario_path = config.getoption("--scenario")
+    if not scenario_path:
+        return
+    try:
+        from otdf_sdk_mgr.schema import (
+            installed_json_for,
+            load_scenario,
+            scenario_to_pytest_sdks,
+        )
+    except ImportError:
+        # otdf-sdk-mgr may not be installed in a minimal pytest env.
+        return
+    scenario = load_scenario(scenario_path)
+    # `sdk@<version>` tokens come from the install record so they match the
+    # dist directories #446's parser walks under `xtest/sdk/<lang>/dist/`.
+    # If the user passed --sdks-encrypt / --sdks-decrypt explicitly, their
+    # tokens win and we skip the resolution step entirely.
+    need_resolve = (
+        not config.getoption("--sdks-encrypt") and scenario.sdks.encrypt
+    ) or (not config.getoption("--sdks-decrypt") and scenario.sdks.decrypt)
+    if need_resolve:
+        try:
+            tokens = scenario_to_pytest_sdks(
+                scenario, installed_json_for(scenario_path)
+            )
+        except FileNotFoundError as e:
+            raise pytest.UsageError(str(e)) from e
+        if not config.getoption("--sdks-encrypt") and tokens["encrypt"]:
+            config.option.sdks_encrypt = " ".join(tokens["encrypt"])
+        if not config.getoption("--sdks-decrypt") and tokens["decrypt"]:
+            config.option.sdks_decrypt = " ".join(tokens["decrypt"])
+    if not config.getoption("--containers") and scenario.suite.containers:
+        config.option.containers = scenario.suite.containers
+    if not instance and scenario.instance.metadata.name:
+        os.environ["OTDF_LOCAL_INSTANCE_NAME"] = scenario.instance.metadata.name
+
+
 def pytest_generate_tests(metafunc: pytest.Metafunc):
     """Dynamically parametrize test functions based on CLI options.
 

From e753ba61c439ce99f807547821af0f170f14ccc9 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 15 May 2026 11:54:44 -0400
Subject: [PATCH 17/64] feat(.claude): bug-repro plugin for OpenTDF (DSPX-3302)

Adds five Claude Code skills under tests/.claude/skills/ that together
turn a Jira bug ticket into a running reproduction, plus a downstream-
installable plugin manifest under .claude/plugin/.

Why
---

The end-to-end goal of DSPX-3302 is to make bug reproduction approachable
for QA, downstream-product engineers, and CI. PRs 1-4 build the plumbing
(shared schema, platform installer, multi-instance otdf-local, xtest
conftest hooks). This PR is the user-facing surface: a Claude can pull
context from Jira, draft an xtest/scenarios/<jira-key>.yaml (and, when
needed, an xtest/bug_<jira_key>_test.py), bring the environment up at
the right version pins, run the scenario's pytest selection, and tear
down.

Skills
------

  scenario-from-bug-report
    Pulls the Jira issue and its comments via `acli jira workitem view
    --fields '*all' --json` and `acli jira workitem comment list`,
    extracts version pins / KAS topology / container type / feature
    flags, then writes xtest/scenarios/<jira-key-lowercased>.yaml
    validated against otdf_sdk_mgr.schema.Scenario. Drafts a new
    xtest/bug_<id>_test.py only when no existing pytest covers the
    case; never silently lands assertions.

  scenario-up
    Runs `otdf-sdk-mgr install scenario`, then `otdf-local instance
    init --from-scenario`, then `otdf-local --instance <name> up`, and
    polls status until healthy. Surfaces logs rather than retrying
    blindly when something stays unhealthy.

  scenario-run
    Invokes `otdf-local scenario run <path>` and classifies the
    result: "bug reproduced" / "not reproduced" / "unrelated failure".
    Cites the evidence line and points at per-service logs.

  scenario-tear-down
    Stops the instance and optionally removes the directory after
    explicit user confirmation.

  instance-status
    Lists known instances, their port bases, health, and flags port
    collisions.

Jira-safety
-----------

Permissions in both .claude/settings.json and the plugin manifest
allow only read+comment via acli jira: workitem view, workitem search,
workitem comment list, workitem comment create, plus a handful of
read-only project/board/sprint queries. edit, delete, transition,
assign, archive, link create, watcher add are all denied. The
plugin.json carries a permission_notes block explaining the policy.

Plugin manifest
---------------

.claude/plugin/plugin.json declares the skill names, runtime
requirements (uv, go, git, docker, acli), and the canonical permission
allowlist, so downstream first/third-party integrators can install
this plugin into their own Claude Code setups.

Refs: https://virtru.atlassian.net/browse/DSPX-3302

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/plugin/plugin.json                    |  38 ++++++
 .claude/settings.json                         |  32 +++++
 .claude/skills/instance-status/SKILL.md       |  36 ++++++
 .../skills/scenario-from-bug-report/SKILL.md  | 111 ++++++++++++++++++
 .claude/skills/scenario-run/SKILL.md          |  43 +++++++
 .claude/skills/scenario-tear-down/SKILL.md    |  42 +++++++
 .claude/skills/scenario-up/SKILL.md           |  51 ++++++++
 7 files changed, 353 insertions(+)
 create mode 100644 .claude/plugin/plugin.json
 create mode 100644 .claude/settings.json
 create mode 100644 .claude/skills/instance-status/SKILL.md
 create mode 100644 .claude/skills/scenario-from-bug-report/SKILL.md
 create mode 100644 .claude/skills/scenario-run/SKILL.md
 create mode 100644 .claude/skills/scenario-tear-down/SKILL.md
 create mode 100644 .claude/skills/scenario-up/SKILL.md

diff --git a/.claude/plugin/plugin.json b/.claude/plugin/plugin.json
new file mode 100644
index 000000000..fce6cee4c
--- /dev/null
+++ b/.claude/plugin/plugin.json
@@ -0,0 +1,38 @@
+{
+  "name": "opentdf-test-harness",
+  "version": "0.1.0",
+  "description": "Skills for reproducing OpenTDF bugs locally via otdf-local and otdf-sdk-mgr. Pulls bug context from Jira (acli), provisions pinned platform/KAS/SDK versions, runs the xtest pytest suite, and tears down. Useful for QA, platform/SDK developers, and downstream first/third-party integrators.",
+  "skills_dir": "../skills",
+  "skills": [
+    "scenario-from-bug-report",
+    "scenario-up",
+    "scenario-run",
+    "scenario-tear-down",
+    "instance-status"
+  ],
+  "requirements": [
+    "uv (python package manager) on PATH",
+    "go toolchain (platform binaries are built from source)",
+    "git (for worktrees of opentdf/platform)",
+    "docker (for keycloak/postgres dependencies)",
+    "acli (Atlassian CLI; needed for the scenario-from-bug-report skill)"
+  ],
+  "permissions": {
+    "allow": [
+      "Bash(uv run otdf-local *)",
+      "Bash(uv run otdf-sdk-mgr *)",
+      "Bash(uv run pytest *)",
+      "Bash(acli jira workitem view *)",
+      "Bash(acli jira workitem search *)",
+      "Bash(acli jira workitem comment list *)",
+      "Bash(acli jira workitem comment create *)",
+      "Bash(acli jira workitem attachment list *)",
+      "Bash(acli jira workitem link list *)",
+      "Bash(acli jira project view *)",
+      "Write(xtest/scenarios/**)",
+      "Write(xtest/bug_*_test.py)",
+      "Write(tests/instances/**)"
+    ]
+  },
+  "permission_notes": "acli jira write-paths intentionally excluded: edit/delete/transition/assign/archive/clone/create/create-bulk/link create/watcher add/comment update/comment delete. Add them explicitly via .claude/settings.local.json if your team needs them; the default plugin is read+comment only."
+}
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 000000000..a1dba2d80
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,32 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run otdf-local *)",
+      "Bash(uv run otdf-sdk-mgr *)",
+      "Bash(uv run pytest *)",
+      "Bash(uv sync *)",
+      "Bash(git status *)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git show *)",
+      "Bash(gh api *)",
+      "Bash(gh issue view *)",
+      "Bash(gh pr view *)",
+      "Bash(gh run *)",
+      "Bash(acli jira workitem view *)",
+      "Bash(acli jira workitem search *)",
+      "Bash(acli jira workitem comment list *)",
+      "Bash(acli jira workitem comment create *)",
+      "Bash(acli jira workitem attachment list *)",
+      "Bash(acli jira workitem link list *)",
+      "Bash(acli jira workitem watcher list *)",
+      "Bash(acli jira project view *)",
+      "Bash(acli jira board view *)",
+      "Bash(acli jira sprint view *)",
+      "Write(xtest/scenarios/**)",
+      "Write(xtest/bug_*_test.py)",
+      "Write(tests/instances/**)",
+      "Write(.claude/tmp/**)"
+    ]
+  }
+}
diff --git a/.claude/skills/instance-status/SKILL.md b/.claude/skills/instance-status/SKILL.md
new file mode 100644
index 000000000..64bd545a0
--- /dev/null
+++ b/.claude/skills/instance-status/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: instance-status
+description: Report which test instances exist on disk, which are running, and the health of each service. Use when the user asks "what's running" or before bringing up another scenario to avoid port collisions.
+allowed-tools: Bash, Read
+---
+
+# instance-status
+
+You give the user a snapshot of all test instances in this checkout: what's defined, what's running, and whether each service is healthy.
+
+## Process
+
+1. **List instances on disk**:
+
+   ```bash
+   uv run otdf-local instance ls --json
+   ```
+
+   Each entry includes `name`, `platform` version, `ports_base`, and the `kas:` keys. Flag any two instances that share a `ports_base` — they cannot run concurrently.
+
+2. **For each instance**, check service status:
+
+   ```bash
+   uv run otdf-local --instance <name> status --json
+   ```
+
+   Each service reports `running`, `healthy`, and the bound port. Don't run all instances in parallel — iterate; a status query is cheap.
+
+3. **Summarize**:
+   - A short table per instance: service → port → state.
+   - Flag any unhealthy service with the path to its log (e.g. `tests/instances/<name>/logs/kas-alpha.log`).
+   - Mention port conflicts if two instances would collide on `ports.base`.
+
+## When ports collide
+
+`otdf-local instance init` warns about this at creation time but does not enforce it. If you see two instances with the same `ports_base`, recommend the user reassign one via `uv run otdf-local instance init <name> --from-scenario <path> --ports-base <new>` (or hand-edit the `instance.yaml`).
diff --git a/.claude/skills/scenario-from-bug-report/SKILL.md b/.claude/skills/scenario-from-bug-report/SKILL.md
new file mode 100644
index 000000000..3c28144ff
--- /dev/null
+++ b/.claude/skills/scenario-from-bug-report/SKILL.md
@@ -0,0 +1,111 @@
+---
+name: scenario-from-bug-report
+description: Pull a Jira bug into context (via `acli jira workitem view`) and turn it into an xtest/scenarios/<JIRA-KEY>.yaml manifest, optionally drafting xtest/bug_<jira_key>_test.py when no existing pytest covers it. Use when the user mentions a Jira issue key like DSPX-1234 (or another [PROJECT]-[NUMBER] format) and asks for a reproducer.
+allowed-tools: Bash, Read, Write, Grep, Glob
+---
+
+# scenario-from-bug-report
+
+Bugs are tracked in Jira. The user will reference an issue by its key in the form `[PROJECT]-[NUMBER]` — examples: `DSPX-3302`, `DSPX-1234`. `DSPX` is the current project's prefix but the prefix can change (e.g. `OPS-`, `SDK-`); accept any short uppercase prefix.
+
+You produce two artifacts the rest of the toolchain consumes:
+
+1. `xtest/scenarios/<jira-key-lowercased>.yaml` — validated against `otdf_sdk_mgr.schema.Scenario`.
+2. (Optional) `xtest/bug_<jira_key_lowercased>_test.py` — only if no existing xtest pytest already exercises the bug.
+
+The Jira key also becomes the working **branch name** (`<JIRA-KEY>-repro` if a fresh branch is needed) and the scenario file's `metadata.id`.
+
+## Step 1 — Pull the Jira issue into context
+
+Always start by fetching the full issue content. Don't proceed on the user's free-text summary alone — the issue body has the version pins and reproduction details you need.
+
+```bash
+acli jira workitem view <JIRA-KEY> --fields '*all' --json
+acli jira workitem comment list <JIRA-KEY>
+```
+
+The first command's JSON output includes `summary`, `description`, `status`, and labels. The second lists comments. Extract:
+
+- The **summary** (becomes scenario `metadata.title`).
+- The **description** (read carefully — version numbers, KAS topology, container types, and feature flags typically live here).
+- Recent **comments** — reproductions and "what changed" notes often appear in comments rather than the original description.
+
+If the issue references attached logs, screenshots, or linked PRs, list them via `acli jira workitem attachment list <JIRA-KEY>` and `acli jira workitem link list <JIRA-KEY>` and mention them in your reply.
+
+**Permitted Jira writes**: only `acli jira workitem comment create <JIRA-KEY> ...` (to post a reproduction-status update if the user asks). Everything else — `edit`, `transition`, `assign`, `archive`, `delete`, `link create`, `watcher add` — is explicitly disallowed by the plugin's permissions; if the user wants those actions, instruct them to run the command themselves.
+
+## Step 2 — Identify the scenario inputs
+
+From the issue text, extract:
+
+- **Encrypt-side SDKs** — which SDKs *create* the TDF? (`go`, `java`, `js`). Pin versions.
+- **Decrypt-side SDKs** — which SDKs *consume* the TDF? Pin versions.
+- **Platform version** — git tag like `v0.9.0` (resolves to the `service/v0.9.0` tag in `opentdf/platform`).
+- **KAS topology** — which KAS instances must be running (`alpha`, `beta`, `gamma`, `delta`, `km1`, `km2`) and whether any need a different pinned version than the platform.
+- **Container type** — `ztdf`, `ztdf-ecwrap`, `nano`, or `nano-with-policy`.
+- **Feature flags** — e.g. `ec_tdf_enabled`.
+- **Expected vs actual behavior** — copy concise prose from the issue.
+
+If anything is ambiguous in the Jira issue, ask the user — don't guess at versions.
+
+## Step 3 — Pick the id and (optionally) the branch
+
+- `metadata.id = <jira-key-lowercased>` — e.g. `DSPX-3302` → `dspx-3302`.
+- Scenario file path: `xtest/scenarios/<jira-key-lowercased>.yaml`.
+- If you need a new git branch, propose `<JIRA-KEY>-repro` (e.g. `DSPX-3302-repro`) and let the user confirm before switching.
+
+## Step 4 — Search for an existing pytest
+
+```bash
+grep -rn "<key_term>" xtest/test_*.py
+```
+
+Likely candidates: `test_tdfs.py` (roundtrip), `test_abac.py` (ABAC), `test_legacy.py` (golden), `test_pqc.py`. If a test already asserts the relevant behavior, reuse it — only the scenario changes, not the code.
+
+## Step 5 — Write `xtest/scenarios/<id>.yaml`
+
+Exact field shape (the schema rejects unknown fields):
+
+```yaml
+apiVersion: opentdf.io/v1alpha1
+kind: Scenario
+metadata:
+  id: <jira-key-lowercased>
+  title: "<Jira summary>"
+  created: <YYYY-MM-DD>
+instance:
+  metadata: { name: <jira-key-lowercased> }
+  platform: { dist: <platform_version> }
+  ports: { base: <pick free base; 8080 if first, +1000 per concurrent scenario> }
+  kas:
+    <name>: { dist: <version>, mode: standard }   # or mode: key_management
+sdks:
+  encrypt:
+    <sdk>: { version: <version> }
+  decrypt:
+    <sdk>: { version: <version> }
+suite:
+  select: "<pytest selector, e.g. xtest/test_tdfs.py::test_tdf_roundtrip>"
+  containers: <ztdf|ztdf-ecwrap|nano|nano-with-policy>
+  # markers: "not slow"
+  # extra_args: ["--no-audit-logs"]
+expected: "<expected behavior copied from Jira>"
+actual:   "<actual behavior copied from Jira>"
+```
+
+Validate before reporting success:
+
+```bash
+uv run python -m otdf_sdk_mgr.schema validate xtest/scenarios/<id>.yaml
+```
+
+## Step 6 — If no existing test fits
+
+Draft `xtest/bug_<id>_test.py` using the `encrypt_sdk` / `decrypt_sdk` fixtures (pattern: `xtest/test_tdfs.py`). Surface the new file in your reply for the user to review — never silently land assertions.
+
+## Notes
+
+- `sdks.encrypt` and `sdks.decrypt` map to xtest's `--sdks-encrypt` / `--sdks-decrypt`. After PR #446 those pytest options take `sdk@version` specifiers like `go@v0.24.0`, `go@main`, or `go@*`. **Do NOT write those tokens in the YAML** — write a normal `{ version: lts }` (or any version string `otdf-sdk-mgr resolve` accepts: `v0.24.0`, `main`, an SDK-specific SHA, etc.). The `scenario-up` skill runs `otdf-sdk-mgr install scenario`, which records the resolved dist directory names in `xtest/scenarios/<id>.installed.json`; the bridge layers (`otdf-local scenario run` and pytest's `--scenario` default in `xtest/conftest.py`) read that file to emit the right `sdk@<dist>` tokens. If you forget the install step, those commands fail with `<id>.installed.json not found — run otdf-sdk-mgr install scenario first`.
+- List the same SDK in both `encrypt` and `decrypt` maps to reproduce xtest's legacy "all pairs" mode. Listing it on only one side keeps the scenario focused (a→b without b→a).
+- `instance.platform.dist` and each `kas.<name>.dist` need `otdf-sdk-mgr install scenario <path>` (or `install release platform:<dist>`) to have built the binary first. `scenario-up` handles that downstream.
+- One-line summary when done: report the scenario path, the new test file (if any), and the Jira link `https://virtru.atlassian.net/browse/<JIRA-KEY>` so the user can cross-reference.
diff --git a/.claude/skills/scenario-run/SKILL.md b/.claude/skills/scenario-run/SKILL.md
new file mode 100644
index 000000000..633846cf4
--- /dev/null
+++ b/.claude/skills/scenario-run/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: scenario-run
+description: Execute the pytest suite declared by a scenarios.yaml against the running instance, then classify the result as "bug reproduced", "not reproduced", or "unrelated failure". Use after `scenario-up` has confirmed the instance is healthy.
+allowed-tools: Bash, Read
+---
+
+# scenario-run
+
+You run the pytest selection declared by the scenario's `suite` block against the running instance and interpret the result in terms of the bug being investigated.
+
+## Inputs
+
+- Path to the scenario YAML (`xtest/scenarios/<id>.yaml`).
+- (Optional) the user's expected outcome, if the scenario's `expected:` field is sparse.
+
+## Process
+
+1. **Invoke the runner**:
+
+   ```bash
+   uv run otdf-local scenario run xtest/scenarios/<id>.yaml
+   ```
+
+   This translates the scenario's `suite.select`, `suite.containers`, `suite.markers`, and `sdks.{encrypt,decrypt}` into the equivalent `pytest --sdks-encrypt ... --sdks-decrypt ... --containers ...` invocation under `xtest/` with `OTDF_LOCAL_INSTANCE_NAME` set. SDK tokens are emitted in xtest's `sdk@version` form (see PR #446) — the resolved version names come from the sibling `<scenario>.installed.json` that `otdf-sdk-mgr install scenario` writes.
+
+   If `scenario run` exits with `Error: <path>.installed.json not found`, the user skipped the install step. Tell them to run `uv run otdf-sdk-mgr install scenario <path>` (or re-run `scenario-up`) before retrying.
+
+2. **Capture exit code and tail of output**. The pytest output is the source of truth; don't re-interpret.
+
+3. **Classify**:
+   - **Bug reproduced** — the test failed with an assertion or stderr that matches the scenario's `actual:` field. Cite the matching line.
+   - **Bug NOT reproduced** — the test passed. This is meaningful: either the bug is fixed at this version combination, or the scenario doesn't capture it precisely yet. Suggest the user widen the assertion or pick a different version pin.
+   - **Unrelated failure** — pytest errored out (collection error, environment issue, import error, timeout). Don't claim repro success or failure; report the error and recommend a next diagnostic step.
+
+4. **Record artifacts**. The pytest run leaves logs under `tests/instances/<id>/logs/`. List the relevant log files in your reply so the user can attach them to the Jira ticket.
+
+## Output format
+
+One-line headline (`bug reproduced` / `not reproduced` / `unrelated failure`), then a short bulleted summary:
+- `select:` the pytest selector
+- `exit_code:` the return value
+- `evidence:` 1-2 lines from the output that justify the classification
+- `logs:` paths to the relevant per-service logs
diff --git a/.claude/skills/scenario-tear-down/SKILL.md b/.claude/skills/scenario-tear-down/SKILL.md
new file mode 100644
index 000000000..39398c766
--- /dev/null
+++ b/.claude/skills/scenario-tear-down/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: scenario-tear-down
+description: Stop the services for a scenario's instance and optionally delete the instance directory. Use when the user is done with a reproduction or wants to free ports/disk for a different scenario.
+allowed-tools: Bash, Read
+---
+
+# scenario-tear-down
+
+You stop a running scenario cleanly and optionally remove its on-disk state.
+
+## Inputs
+
+- The instance name (typically the lowercased Jira key, e.g. `dspx-3302`). If the user passes the scenario YAML path instead, read its `instance.metadata.name`.
+- Whether the user wants the instance directory preserved (default: yes — keep it for re-runs).
+
+## Process
+
+1. **Stop services**:
+
+   ```bash
+   uv run otdf-local --instance <name> down
+   ```
+
+   The `down` command halts the platform process, all KAS instances under management, and the docker dependencies (keycloak, postgres) — unless another instance is still using them, in which case docker is left running.
+
+2. **Optionally clean state**. Only if the user explicitly asked to remove:
+
+   ```bash
+   uv run otdf-local instance rm <name> -y
+   ```
+
+   This deletes `tests/instances/<name>/` including its `logs/`, `keys/`, and per-KAS configs. The platform binary at `xtest/platform/dist/<version>/service` is shared and is NOT removed (`otdf-sdk-mgr clean --dist-only` is the right command if the user wants to free that too).
+
+3. **Confirm port range is free** (useful if the user is about to bring up another scenario on the same base):
+
+   ```bash
+   uv run otdf-local instance ls --json
+   ```
+
+## Caution
+
+Never remove an instance without explicit user confirmation. The directory may contain golden keys or generated configs that took time to assemble. If unsure, leave it.
diff --git a/.claude/skills/scenario-up/SKILL.md b/.claude/skills/scenario-up/SKILL.md
new file mode 100644
index 000000000..955fce8b9
--- /dev/null
+++ b/.claude/skills/scenario-up/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: scenario-up
+description: Provision artifacts, scaffold the instance directory, and start the test environment for a given xtest/scenarios/<id>.yaml. Use after `scenario-from-bug-report` (or when the user already has a scenario YAML) and wants the environment running.
+allowed-tools: Bash, Read
+---
+
+# scenario-up
+
+You bring the environment described by a `scenarios.yaml` up and confirm it's healthy. The three steps are non-negotiable; do them in order.
+
+## Inputs
+
+- Path to a validated `xtest/scenarios/<id>.yaml`. If the user doesn't provide one, ask.
+
+## Process
+
+1. **Install artifacts** — platform binary, per-KAS binaries, helper scripts, and the encrypt+decrypt SDKs declared in the scenario:
+
+   ```bash
+   uv run otdf-sdk-mgr install scenario xtest/scenarios/<id>.yaml
+   ```
+
+   This writes `xtest/scenarios/<id>.installed.json` next to the scenario with the resolved dist paths. The first `go build` per platform version takes ~30-60s; subsequent runs reuse the cached binary.
+
+2. **Scaffold the instance directory** (creates `tests/instances/<id>/`):
+
+   ```bash
+   uv run otdf-local instance init <id> --from-scenario xtest/scenarios/<id>.yaml
+   ```
+
+   If the instance already exists, this is a no-op for the existing files; double-check with `uv run otdf-local instance ls` first to avoid surprising the user.
+
+3. **Bring it up**:
+
+   ```bash
+   uv run otdf-local --instance <id> up
+   ```
+
+   Then poll status until everything is healthy (don't proceed before this succeeds):
+
+   ```bash
+   uv run otdf-local --instance <id> status --json
+   ```
+
+   If any service stays unhealthy after ~60 seconds, surface the relevant log via `uv run otdf-local --instance <id> logs <service> -n 50` and report the failure mode rather than retrying blindly.
+
+## Output
+
+Once healthy, report:
+- The instance name and which ports it occupies (look at `instance.yaml`'s `ports.base`).
+- The next command the user is likely to run (`scenario-run`).

From b9b814a45b7ab64db666b4cb9937ea09405b3024 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 15 May 2026 15:24:16 -0400
Subject: [PATCH 18/64] =?UTF-8?q?refactor(.claude):=20generalize=20scenari?=
 =?UTF-8?q?o-from-bug-report=20=E2=86=92=20scenario-from-ticket=20(DSPX-33?=
 =?UTF-8?q?02)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Headless dogfooding (run-1 on DSPX-2719) showed the bug-only framing
was too narrow — the common workflow is writing tests for new features
first (TDD), not reproducing version-pinned bugs.

- Rename and rewrite the skill to branch on Jira Issue Type. Bug
  follows the old expected/actual flow; Story/Task uses ref pins
  (`main`, feature branch, PR SHA via `gh pr view --json headRefOid`)
  for forward-looking regression gates; Spike bails out rather than
  fabricating. Mandates `acli workitem comment list` and steers away
  from cli.sh greps (both were run-1 gaps).
- New `scenario-matrix` sibling skill: write N scenario files from a
  base × N refs (PRs/branches/releases). Schema/installer support was
  already there via `PlatformPin.source.ref` and
  `install_platform_source(ref)` — no other changes needed.
- `scenario-run` output classification generalized from "bug
  reproduced / not reproduced" to "expected / unexpected outcome",
  with explicit branches for bug-repro vs TDD interpretations.
- `scenario-up` description and `plugin.json` (description, skills
  array, requirements) updated to match.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/plugin/plugin.json                    |   8 +-
 .../skills/scenario-from-bug-report/SKILL.md  | 111 ------------
 .claude/skills/scenario-from-ticket/SKILL.md  | 159 ++++++++++++++++++
 .claude/skills/scenario-matrix/SKILL.md       |  91 ++++++++++
 .claude/skills/scenario-run/SKILL.md          |  19 ++-
 .claude/skills/scenario-up/SKILL.md           |   2 +-
 6 files changed, 268 insertions(+), 122 deletions(-)
 delete mode 100644 .claude/skills/scenario-from-bug-report/SKILL.md
 create mode 100644 .claude/skills/scenario-from-ticket/SKILL.md
 create mode 100644 .claude/skills/scenario-matrix/SKILL.md

diff --git a/.claude/plugin/plugin.json b/.claude/plugin/plugin.json
index fce6cee4c..bb4c1311f 100644
--- a/.claude/plugin/plugin.json
+++ b/.claude/plugin/plugin.json
@@ -1,10 +1,11 @@
 {
   "name": "opentdf-test-harness",
   "version": "0.1.0",
-  "description": "Skills for reproducing OpenTDF bugs locally via otdf-local and otdf-sdk-mgr. Pulls bug context from Jira (acli), provisions pinned platform/KAS/SDK versions, runs the xtest pytest suite, and tears down. Useful for QA, platform/SDK developers, and downstream first/third-party integrators.",
+  "description": "Jira-ticket-driven scenarios for the OpenTDF test harness. Pulls ticket context from Jira (acli) — any ticket type, including bugs, feature stories, and PR-driven work — provisions pinned platform/KAS/SDK versions or refs (released versions, main, feature branches, PR SHAs), runs the xtest pytest suite, and tears down. Useful for QA, platform/SDK developers writing tests for new features first, and downstream first/third-party integrators.",
   "skills_dir": "../skills",
   "skills": [
-    "scenario-from-bug-report",
+    "scenario-from-ticket",
+    "scenario-matrix",
     "scenario-up",
     "scenario-run",
     "scenario-tear-down",
@@ -15,7 +16,8 @@
     "go toolchain (platform binaries are built from source)",
     "git (for worktrees of opentdf/platform)",
     "docker (for keycloak/postgres dependencies)",
-    "acli (Atlassian CLI; needed for the scenario-from-bug-report skill)"
+    "acli (Atlassian CLI; needed for the scenario-from-ticket skill)",
+    "gh (GitHub CLI; needed for scenario-matrix to resolve PR refs)"
   ],
   "permissions": {
     "allow": [
diff --git a/.claude/skills/scenario-from-bug-report/SKILL.md b/.claude/skills/scenario-from-bug-report/SKILL.md
deleted file mode 100644
index 3c28144ff..000000000
--- a/.claude/skills/scenario-from-bug-report/SKILL.md
+++ /dev/null
@@ -1,111 +0,0 @@
----
-name: scenario-from-bug-report
-description: Pull a Jira bug into context (via `acli jira workitem view`) and turn it into an xtest/scenarios/<JIRA-KEY>.yaml manifest, optionally drafting xtest/bug_<jira_key>_test.py when no existing pytest covers it. Use when the user mentions a Jira issue key like DSPX-1234 (or another [PROJECT]-[NUMBER] format) and asks for a reproducer.
-allowed-tools: Bash, Read, Write, Grep, Glob
----
-
-# scenario-from-bug-report
-
-Bugs are tracked in Jira. The user will reference an issue by its key in the form `[PROJECT]-[NUMBER]` — examples: `DSPX-3302`, `DSPX-1234`. `DSPX` is the current project's prefix but the prefix can change (e.g. `OPS-`, `SDK-`); accept any short uppercase prefix.
-
-You produce two artifacts the rest of the toolchain consumes:
-
-1. `xtest/scenarios/<jira-key-lowercased>.yaml` — validated against `otdf_sdk_mgr.schema.Scenario`.
-2. (Optional) `xtest/bug_<jira_key_lowercased>_test.py` — only if no existing xtest pytest already exercises the bug.
-
-The Jira key also becomes the working **branch name** (`<JIRA-KEY>-repro` if a fresh branch is needed) and the scenario file's `metadata.id`.
-
-## Step 1 — Pull the Jira issue into context
-
-Always start by fetching the full issue content. Don't proceed on the user's free-text summary alone — the issue body has the version pins and reproduction details you need.
-
-```bash
-acli jira workitem view <JIRA-KEY> --fields '*all' --json
-acli jira workitem comment list <JIRA-KEY>
-```
-
-The first command's JSON output includes `summary`, `description`, `status`, and labels. The second lists comments. Extract:
-
-- The **summary** (becomes scenario `metadata.title`).
-- The **description** (read carefully — version numbers, KAS topology, container types, and feature flags typically live here).
-- Recent **comments** — reproductions and "what changed" notes often appear in comments rather than the original description.
-
-If the issue references attached logs, screenshots, or linked PRs, list them via `acli jira workitem attachment list <JIRA-KEY>` and `acli jira workitem link list <JIRA-KEY>` and mention them in your reply.
-
-**Permitted Jira writes**: only `acli jira workitem comment create <JIRA-KEY> ...` (to post a reproduction-status update if the user asks). Everything else — `edit`, `transition`, `assign`, `archive`, `delete`, `link create`, `watcher add` — is explicitly disallowed by the plugin's permissions; if the user wants those actions, instruct them to run the command themselves.
-
-## Step 2 — Identify the scenario inputs
-
-From the issue text, extract:
-
-- **Encrypt-side SDKs** — which SDKs *create* the TDF? (`go`, `java`, `js`). Pin versions.
-- **Decrypt-side SDKs** — which SDKs *consume* the TDF? Pin versions.
-- **Platform version** — git tag like `v0.9.0` (resolves to the `service/v0.9.0` tag in `opentdf/platform`).
-- **KAS topology** — which KAS instances must be running (`alpha`, `beta`, `gamma`, `delta`, `km1`, `km2`) and whether any need a different pinned version than the platform.
-- **Container type** — `ztdf`, `ztdf-ecwrap`, `nano`, or `nano-with-policy`.
-- **Feature flags** — e.g. `ec_tdf_enabled`.
-- **Expected vs actual behavior** — copy concise prose from the issue.
-
-If anything is ambiguous in the Jira issue, ask the user — don't guess at versions.
-
-## Step 3 — Pick the id and (optionally) the branch
-
-- `metadata.id = <jira-key-lowercased>` — e.g. `DSPX-3302` → `dspx-3302`.
-- Scenario file path: `xtest/scenarios/<jira-key-lowercased>.yaml`.
-- If you need a new git branch, propose `<JIRA-KEY>-repro` (e.g. `DSPX-3302-repro`) and let the user confirm before switching.
-
-## Step 4 — Search for an existing pytest
-
-```bash
-grep -rn "<key_term>" xtest/test_*.py
-```
-
-Likely candidates: `test_tdfs.py` (roundtrip), `test_abac.py` (ABAC), `test_legacy.py` (golden), `test_pqc.py`. If a test already asserts the relevant behavior, reuse it — only the scenario changes, not the code.
-
-## Step 5 — Write `xtest/scenarios/<id>.yaml`
-
-Exact field shape (the schema rejects unknown fields):
-
-```yaml
-apiVersion: opentdf.io/v1alpha1
-kind: Scenario
-metadata:
-  id: <jira-key-lowercased>
-  title: "<Jira summary>"
-  created: <YYYY-MM-DD>
-instance:
-  metadata: { name: <jira-key-lowercased> }
-  platform: { dist: <platform_version> }
-  ports: { base: <pick free base; 8080 if first, +1000 per concurrent scenario> }
-  kas:
-    <name>: { dist: <version>, mode: standard }   # or mode: key_management
-sdks:
-  encrypt:
-    <sdk>: { version: <version> }
-  decrypt:
-    <sdk>: { version: <version> }
-suite:
-  select: "<pytest selector, e.g. xtest/test_tdfs.py::test_tdf_roundtrip>"
-  containers: <ztdf|ztdf-ecwrap|nano|nano-with-policy>
-  # markers: "not slow"
-  # extra_args: ["--no-audit-logs"]
-expected: "<expected behavior copied from Jira>"
-actual:   "<actual behavior copied from Jira>"
-```
-
-Validate before reporting success:
-
-```bash
-uv run python -m otdf_sdk_mgr.schema validate xtest/scenarios/<id>.yaml
-```
-
-## Step 6 — If no existing test fits
-
-Draft `xtest/bug_<id>_test.py` using the `encrypt_sdk` / `decrypt_sdk` fixtures (pattern: `xtest/test_tdfs.py`). Surface the new file in your reply for the user to review — never silently land assertions.
-
-## Notes
-
-- `sdks.encrypt` and `sdks.decrypt` map to xtest's `--sdks-encrypt` / `--sdks-decrypt`. After PR #446 those pytest options take `sdk@version` specifiers like `go@v0.24.0`, `go@main`, or `go@*`. **Do NOT write those tokens in the YAML** — write a normal `{ version: lts }` (or any version string `otdf-sdk-mgr resolve` accepts: `v0.24.0`, `main`, an SDK-specific SHA, etc.). The `scenario-up` skill runs `otdf-sdk-mgr install scenario`, which records the resolved dist directory names in `xtest/scenarios/<id>.installed.json`; the bridge layers (`otdf-local scenario run` and pytest's `--scenario` default in `xtest/conftest.py`) read that file to emit the right `sdk@<dist>` tokens. If you forget the install step, those commands fail with `<id>.installed.json not found — run otdf-sdk-mgr install scenario first`.
-- List the same SDK in both `encrypt` and `decrypt` maps to reproduce xtest's legacy "all pairs" mode. Listing it on only one side keeps the scenario focused (a→b without b→a).
-- `instance.platform.dist` and each `kas.<name>.dist` need `otdf-sdk-mgr install scenario <path>` (or `install release platform:<dist>`) to have built the binary first. `scenario-up` handles that downstream.
-- One-line summary when done: report the scenario path, the new test file (if any), and the Jira link `https://virtru.atlassian.net/browse/<JIRA-KEY>` so the user can cross-reference.
diff --git a/.claude/skills/scenario-from-ticket/SKILL.md b/.claude/skills/scenario-from-ticket/SKILL.md
new file mode 100644
index 000000000..1f573b592
--- /dev/null
+++ b/.claude/skills/scenario-from-ticket/SKILL.md
@@ -0,0 +1,159 @@
+---
+name: scenario-from-ticket
+description: Pull a Jira ticket of any type (Bug, Story, Task, Spike) into context via `acli jira workitem view` + `acli jira workitem comment list`, then turn it into an xtest/scenarios/<JIRA-KEY>.yaml manifest. Pins platform/KAS/SDKs to a released version (`dist:`), a branch or SHA (`source.ref:`), or the head of a PR — whichever matches the ticket. Optionally drafts xtest/bug_<jira_key>_test.py when no existing pytest covers the behavior. Use when the user mentions a Jira key like DSPX-1234 (or any [PROJECT]-[NUMBER]) and wants a runnable scenario — reproducing a bug, writing a TDD test for a new feature, or validating behavior at a specific ref.
+allowed-tools: Bash, Read, Write, Grep, Glob
+---
+
+# scenario-from-ticket
+
+You produce a `xtest/scenarios/<jira-key-lowercased>.yaml` manifest from a Jira ticket. The same skill handles bugs, features (TDD), and exploratory work — the *Issue Type* field on the ticket selects which way the rest of this skill behaves.
+
+Two artifacts:
+
+1. `xtest/scenarios/<jira-key-lowercased>.yaml` — validated against `otdf_sdk_mgr.schema.Scenario`.
+2. (Optional) `xtest/bug_<jira_key_lowercased>_test.py` — only if no existing xtest pytest already exercises the behavior. The `bug_` prefix is a slug, not a type marker: feature-driven tests use it too.
+
+The Jira key also becomes the working **branch name** (`<JIRA-KEY>-repro` for Bugs, `<JIRA-KEY>-tdd` for Stories/Tasks) and the scenario file's `metadata.id`.
+
+## Step 1 — Pull the Jira ticket into context
+
+**Always run BOTH commands**. Don't skip the comment list — comments often carry the most recent reproduction status, "what changed" notes, or "fixed by PR #N" pointers that aren't in the original description:
+
+```bash
+acli jira workitem view <JIRA-KEY> --fields '*all' --json
+acli jira workitem comment list <JIRA-KEY>
+```
+
+From the JSON output of the first command, extract:
+
+- **Issue Type** (Bug, Story, Task, Spike) — load-bearing; selects which Step 2 branch to follow.
+- **Summary** — becomes scenario `metadata.title`.
+- **Description** — version numbers, KAS topology, container types, feature flags, acceptance criteria typically live here.
+- **Status** — Backlog / In Progress / Done affects whether the scenario is forward-looking (TDD on Backlog) or retroactive (regression gate on Done).
+
+From the comments, pull any "tested at version X" / "reproduces on platform Y" / "fixed by PR #N" annotations into your mental model.
+
+If the ticket references attached logs, screenshots, or linked PRs, list them via `acli jira workitem attachment list <JIRA-KEY>` and `acli jira workitem link list <JIRA-KEY>` and call them out in your reply.
+
+**Permitted Jira writes**: only `acli jira workitem comment create <JIRA-KEY> ...` (to post a reproduction-status update if the user asks). Everything else — `edit`, `transition`, `assign`, `archive`, `delete`, `link create`, `watcher add` — is explicitly disallowed by the plugin's permissions; if the user wants those actions, instruct them to run the command themselves.
+
+## Step 2 — Branch on Issue Type
+
+### Bug
+
+The ticket describes a behavior that should work but doesn't.
+
+- `expected:` — what should happen (copy from the description's "expected behavior" section or rephrase the summary).
+- `actual:` — what actually happens, including the exact error message if the ticket quotes one.
+- Pin platform / KAS / SDKs to the **versions where the bug reproduces**. Usually `dist:` against a released version. Mixed-version topologies (e.g. platform `v0.9.0` + km1 `v0.9.0-rc.2`) are common and the schema supports them.
+
+If the description doesn't name versions, ask the user. (A headless agent has no user — in that case default to `dist: lts` everywhere and call out the assumption in `actual:`.)
+
+### Story / Task (feature work, TDD-style)
+
+The ticket describes a behavior the user wants to *add*. The scenario you produce is a forward-looking regression gate, not a bug reproducer.
+
+- `expected:` — the new behavior the feature should provide, paraphrased from acceptance criteria.
+- `actual:` — the current state, e.g. "feature not implemented; tests skip via `<SDK>.supports('<feature>')` until the supports entry lands." The scenario's `actual:` is what `scenario-run`'s "expected outcome" classifier compares against: a real failure means progress was made; a uniform skip means the prereq SDK plumbing is still pending.
+- Pin platform / KAS / SDKs to the **ref where the feature will land**:
+  - HEAD of mainline: `platform: { source: { ref: main } }`, `sdks.<lang>.version: main`.
+  - Feature branch: `platform: { source: { ref: feature/ecdsa-binding } }`.
+  - Draft PR under review: resolve to its head SHA with `gh pr view <N> --json headRefOid` and pin `platform: { source: { ref: <40-char-SHA> } }`. SHAs are reproducible; branch names move every push.
+- Only pin the component(s) the feature actually touches. Leave the rest on `lts` / `stable`.
+
+### Spike / unclear
+
+The ticket asks an open question or lacks enough concrete behavior to encode. Don't fabricate a scenario. Emit:
+
+```
+<JIRA-KEY> is a Spike (or has no specific behavior / version pins yet). Add either:
+  (a) the version or ref where you want behavior exercised, or
+  (b) a concrete pass/fail criterion (what should the test assert?)
+…and re-invoke this skill.
+```
+
+…and stop.
+
+## Step 3 — Pick the id and (optionally) the branch
+
+- `metadata.id = <jira-key-lowercased>` — e.g. `DSPX-3302` → `dspx-3302`.
+- Scenario file path: `xtest/scenarios/<jira-key-lowercased>.yaml`.
+- If you need a new git branch, propose `<JIRA-KEY>-repro` for Bugs and `<JIRA-KEY>-tdd` for Stories/Tasks; let the user confirm before switching.
+
+## Step 4 — Search for an existing pytest
+
+```bash
+grep -rn "<key_term>" xtest/test_*.py xtest/tdfs.py
+```
+
+Likely candidates: `test_tdfs.py` (roundtrip), `test_abac.py` (ABAC), `test_legacy.py` (golden), `test_pqc.py`. If a test already asserts the relevant behavior, reuse it via `suite.select` — no draft test needed.
+
+**Don't grep `xtest/sdk/<lang>/cli.sh`.** Those wrappers are reusable infrastructure (versioned alongside each SDK dist) and their contents have nothing to do with scenario YAML fields. The scenario YAML doesn't need to know HOW a feature is plumbed — only WHICH pytest suite exercises it. Reading the wrappers is a waste of turns. If a feature's `supports("<name>")` gate isn't in `tdfs.py` yet, that's a signal that supporting infrastructure has to land separately from the scenario — note it in `actual:` and move on.
+
+## Step 5 — Write `xtest/scenarios/<id>.yaml`
+
+The schema (`otdf_sdk_mgr.schema.Scenario`) rejects unknown fields. Each pin (`PlatformPin`, `KasPin`) requires **exactly one** of `dist:`, `source:`, or `image:`. `image:` is reserved for forward-compat and rejected today — pick `dist:` or `source:`.
+
+Released-version pin (typical Bug scenario):
+
+```yaml
+apiVersion: opentdf.io/v1alpha1
+kind: Scenario
+metadata:
+  id: <jira-key-lowercased>
+  title: "<Jira summary>"
+  created: <YYYY-MM-DD>
+instance:
+  metadata: { name: <jira-key-lowercased> }
+  platform: { dist: v0.9.0 }
+  ports: { base: <free base; 8080 if first, +1000 per concurrent scenario> }
+  kas:
+    alpha: { dist: v0.9.0, mode: standard }
+sdks:
+  encrypt:
+    go: { version: lts }
+  decrypt:
+    java: { version: "0.7.8" }
+suite:
+  select: "xtest/test_tdfs.py::test_tdf_roundtrip"
+  containers: ztdf
+expected: "..."
+actual:   "..."
+```
+
+Ref pin (TDD / HEAD / branch / PR):
+
+```yaml
+instance:
+  platform:
+    source: { ref: main }                  # branch, tag, or 40-char SHA
+  kas:
+    alpha:
+      source: { ref: feature/ecdsa-binding }
+      mode: standard
+sdks:
+  encrypt:
+    go: { version: main }                  # SdkPin.version accepts the same range of strings
+```
+
+Mix-and-match is fine — `platform` on `main`, `kas.alpha` on a released `dist:`, SDKs on different refs.
+
+Validate before reporting success:
+
+```bash
+uv run python -m otdf_sdk_mgr.schema validate xtest/scenarios/<id>.yaml
+```
+
+## Step 6 — If no existing test fits
+
+Draft `xtest/bug_<id>_test.py` using the `encrypt_sdk` / `decrypt_sdk` fixtures (pattern: `xtest/test_tdfs.py`). The `bug_` prefix is a historical slug applied to every scenario-tied test — feature/TDD ones use it too; don't let the name confuse you. Surface the new file in your reply for the user to review — never silently land assertions.
+
+For TDD tests where the underlying feature isn't yet implemented, gate participation behind `<sdk>.supports("<feature>")` and call `pytest.skip(...)` when the gate fails. The scenario then runs as "all skipped" until the SDK supports entry lands, at which point the test becomes a real assertion.
+
+## Notes
+
+- `sdks.encrypt` and `sdks.decrypt` map to xtest's `--sdks-encrypt` / `--sdks-decrypt`. After PR #446 those pytest options take `sdk@version` specifiers like `go@v0.24.0`, `go@main`, or `go@*`. **Do NOT write those tokens in the YAML** — write a normal `{ version: lts }` (or any version string `otdf-sdk-mgr resolve` accepts: `v0.24.0`, `main`, an SDK-specific SHA, etc.). The `scenario-up` skill runs `otdf-sdk-mgr install scenario`, which records the resolved dist directory names in `xtest/scenarios/<id>.installed.json`; the bridge layers (`otdf-local scenario run` and pytest's `--scenario` default in `xtest/conftest.py`) read that file to emit the right `sdk@<dist>` tokens. If you forget the install step, those commands fail with `<id>.installed.json not found — run otdf-sdk-mgr install scenario first`.
+- List the same SDK in both `encrypt` and `decrypt` maps to reproduce xtest's legacy "all pairs" mode. Listing it on only one side keeps the scenario focused (a→b without b→a).
+- `instance.platform.dist` / `source.ref` and each `kas.<name>.dist` / `source.ref` need `otdf-sdk-mgr install scenario <path>` to have built the binary first. `scenario-up` handles that downstream.
+- For matrix runs (same suite × N refs), don't author N scenarios by hand — invoke the `scenario-matrix` skill against this scenario as the base.
+- One-line summary when done: report the scenario path, the new test file (if any), and the Jira link `https://virtru.atlassian.net/browse/<JIRA-KEY>` so the user can cross-reference.
diff --git a/.claude/skills/scenario-matrix/SKILL.md b/.claude/skills/scenario-matrix/SKILL.md
new file mode 100644
index 000000000..d28637495
--- /dev/null
+++ b/.claude/skills/scenario-matrix/SKILL.md
@@ -0,0 +1,91 @@
+---
+name: scenario-matrix
+description: Given a base scenario (or a Jira ticket) plus a list of refs (PRs, branches, released versions), write one scenario file per ref so the same pytest suite runs across all of them. Use to bisect a regression across releases, validate a fix across multiple PRs, or check feature compatibility between versions. Generates files only — does not install or run them.
+allowed-tools: Bash, Read, Write, Grep, Glob
+---
+
+# scenario-matrix
+
+You produce N scenario files from one base scenario, where N = the number of refs the user wants exercised. Each output scenario differs only in `instance.platform` (and optionally any KAS pins the user says should track the same ref). SDK pins are preserved unless explicitly told to vary.
+
+## Inputs
+
+- A **base**, either:
+  - Path to an existing `xtest/scenarios/<id>.yaml`, OR
+  - A Jira ticket key — in which case invoke `scenario-from-ticket` first to produce the base, then proceed.
+- A **ref list** — any combination of:
+  - Released versions: `v0.9.0`, `v0.8.5`
+  - Branch names: `main`, `feature/ecdsa-binding`
+  - PR numbers: `1234`, `1235` (resolved to head SHAs for reproducibility)
+- (Optional) which KAS instances should track the same ref as `platform`. Default: every KAS instance in the base also tracks the ref.
+
+## Process
+
+### Step 1 — Resolve the base scenario
+
+- If given a path: `Read` it.
+- If given a ticket key: invoke `scenario-from-ticket` against the ticket first, then `Read` the produced file.
+
+The base scenario provides everything except `instance.platform` (and tracked KAS pins): metadata.title becomes the title prefix, `suite` is shared across all cells, `sdks` is preserved.
+
+### Step 2 — Resolve each ref to a concrete value
+
+- Released version → use verbatim under `dist:`. Example: `v0.9.0` → `platform: { dist: v0.9.0 }`.
+- Branch name → use under `source.ref:`. Example: `main` → `platform: { source: { ref: main } }`.
+- PR number `N` → fetch:
+
+  ```bash
+  gh pr view <N> --json number,headRefName,headRefOid
+  ```
+
+  …and pin under `source.ref:` to the **`headRefOid`** (40-char SHA), **not** `headRefName`. Reason: branch names move on every push, SHAs don't. Record `headRefName` in the scenario title for human readability.
+
+### Step 3 — Emit one scenario file per ref
+
+Naming: `xtest/scenarios/<base-id>-<short-token>.yaml`. Tokens:
+
+- Released version: strip `v` and dots — `v0.9.0` → `v090`.
+- Branch: replace `/` with `-` — `feature/ecdsa-binding` → `feature-ecdsa-binding`.
+- PR: `pr<N>` — `1234` → `pr1234`. The SHA still lives inside the file.
+
+Each cell scenario gets:
+
+- A unique `metadata.id` (`<base-id>-<token>`) matching the file basename.
+- A unique `instance.metadata.name` (same as `metadata.id`).
+- A unique `instance.ports.base` — start from the base's value and add `+1000` per additional cell. `scenario-up` rejects overlapping port bases between concurrent instances.
+- `metadata.title` gets a ` [<token>]` suffix for at-a-glance identification.
+- `instance.platform` rewritten to the resolved ref. For KAS pins that should track the same ref (default: all of them), rewrite their pin too. KAS pins the user explicitly excluded keep the base's value.
+- `suite`, `sdks`, `expected`, `actual` — unchanged from the base.
+
+### Step 4 — Validate every file
+
+```bash
+for f in xtest/scenarios/<base-id>-*.yaml; do
+  uv run python -m otdf_sdk_mgr.schema validate "$f"
+done
+```
+
+Bail (delete the just-written files) if any cell fails validation — partial matrices are confusing.
+
+### Step 5 — Report
+
+- The list of files written.
+- The exact `scenario-up` / `scenario-run` chain the user can run per cell (or in a loop):
+
+  ```bash
+  for f in xtest/scenarios/<base-id>-*.yaml; do
+    name="$(basename "$f" .yaml)"
+    uv run otdf-sdk-mgr install scenario "$f"
+    uv run otdf-local instance init "$name" --from-scenario "$f"
+    uv run otdf-local --instance "$name" up
+    uv run otdf-local scenario run "$f"
+    uv run otdf-local --instance "$name" down
+  done
+  ```
+
+## Notes
+
+- This skill **writes scenario files only**. It does not install artifacts, scaffold instances, or run pytest. Hand the resulting files to `scenario-up` and `scenario-run` per cell.
+- For two PRs that differ in *SDK* (not platform), vary `sdks.<encrypt|decrypt>.<lang>.version` instead of `platform`. Same pattern, different field — `SdkPin.version` accepts the same range of refs (`v0.24.0`, `main`, SHA).
+- For a full platform × SDK matrix, generate N×M scenarios. Be prepared for long install times — each new platform ref triggers a `go build` (~30-60s first time per version); subsequent runs reuse the cached binary.
+- Don't update `expected:` / `actual:` per cell unless the user specifies that one of the refs is the "known good" or "known broken" baseline.
diff --git a/.claude/skills/scenario-run/SKILL.md b/.claude/skills/scenario-run/SKILL.md
index 633846cf4..c9a73eef5 100644
--- a/.claude/skills/scenario-run/SKILL.md
+++ b/.claude/skills/scenario-run/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: scenario-run
-description: Execute the pytest suite declared by a scenarios.yaml against the running instance, then classify the result as "bug reproduced", "not reproduced", or "unrelated failure". Use after `scenario-up` has confirmed the instance is healthy.
+description: Execute the pytest suite declared by a scenarios.yaml against the running instance, then classify the result as "expected outcome", "unexpected outcome", or "unrelated failure" against the scenario's `expected:` / `actual:` fields. Works for bug-repro scenarios, TDD/feature scenarios, and matrix runs. Use after `scenario-up` has confirmed the instance is healthy.
 allowed-tools: Bash, Read
 ---
 
 # scenario-run
 
-You run the pytest selection declared by the scenario's `suite` block against the running instance and interpret the result in terms of the bug being investigated.
+You run the pytest selection declared by the scenario's `suite` block against the running instance and interpret the result in terms of the ticket the scenario was authored for. The same three-bucket classification works for bug-repros (where "expected" means *failure that matches `actual:`*) and for TDD scenarios (where "expected" means *skip-until-feature-lands*).
 
 ## Inputs
 
@@ -27,16 +27,21 @@ You run the pytest selection declared by the scenario's `suite` block against th
 
 2. **Capture exit code and tail of output**. The pytest output is the source of truth; don't re-interpret.
 
-3. **Classify**:
-   - **Bug reproduced** — the test failed with an assertion or stderr that matches the scenario's `actual:` field. Cite the matching line.
-   - **Bug NOT reproduced** — the test passed. This is meaningful: either the bug is fixed at this version combination, or the scenario doesn't capture it precisely yet. Suggest the user widen the assertion or pick a different version pin.
-   - **Unrelated failure** — pytest errored out (collection error, environment issue, import error, timeout). Don't claim repro success or failure; report the error and recommend a next diagnostic step.
+3. **Classify** against the scenario's `expected:` and `actual:` fields:
+   - **Expected outcome** — the test result matches what `expected:` (or, for a bug, `actual:`) predicts.
+     - Bug scenario: pytest FAILED with an assertion/stderr matching `actual:`. Bug reproduced. Cite the matching line.
+     - TDD/feature scenario on a ref where the feature isn't landed yet: tests SKIPPED via `supports("<feature>")`. Feature gate is still pending as predicted.
+     - TDD/feature scenario on a ref where the feature is landed: tests PASSED. Feature works; the scenario is now a regression gate.
+   - **Unexpected outcome** — the test result is *not* what the scenario predicted.
+     - Bug scenario: pytest PASSED. Either the bug is fixed at this pin, or the scenario doesn't capture it tightly enough. Suggest widening the assertion, pinning a different ref, or marking the bug closed.
+     - TDD/feature scenario: tests FAILED for a reason that doesn't match `actual:`. A real bug surfaced, OR the prereq implementation work landed and the test now needs a real assertion (not a skip). Surface the actual failure to the user.
+   - **Unrelated failure** — pytest errored out (collection error, environment issue, import error, timeout). Don't claim outcome match either way; report the error and recommend a next diagnostic step.
 
 4. **Record artifacts**. The pytest run leaves logs under `tests/instances/<id>/logs/`. List the relevant log files in your reply so the user can attach them to the Jira ticket.
 
 ## Output format
 
-One-line headline (`bug reproduced` / `not reproduced` / `unrelated failure`), then a short bulleted summary:
+One-line headline (`expected outcome` / `unexpected outcome` / `unrelated failure`), then a short bulleted summary:
 - `select:` the pytest selector
 - `exit_code:` the return value
 - `evidence:` 1-2 lines from the output that justify the classification
diff --git a/.claude/skills/scenario-up/SKILL.md b/.claude/skills/scenario-up/SKILL.md
index 955fce8b9..8254dd610 100644
--- a/.claude/skills/scenario-up/SKILL.md
+++ b/.claude/skills/scenario-up/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: scenario-up
-description: Provision artifacts, scaffold the instance directory, and start the test environment for a given xtest/scenarios/<id>.yaml. Use after `scenario-from-bug-report` (or when the user already has a scenario YAML) and wants the environment running.
+description: Provision artifacts, scaffold the instance directory, and start the test environment for a given xtest/scenarios/<id>.yaml. Use after `scenario-from-ticket` (or `scenario-matrix`, or when the user already has a scenario YAML) and wants the environment running.
 allowed-tools: Bash, Read
 ---
 

From 9a0a7fb6c3586892222a9ddd84fe1d59b683be85 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 15 May 2026 21:24:46 -0400
Subject: [PATCH 19/64] feat(.claude): feature-design skill for cross-repo
 features (DSPX-3302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

For features (or bugs) that touch more than one OpenTDF repo — platform
plus the Go / Java / JS SDKs — feature-design captures the work as a
single spec at xtest/features/<name>.yaml plus the tests-side artifacts
that land first (feature_type entry in tdfs.py, scenario, draft test).

The model matches the team's existing pattern: tests-side artifacts
merge first, dormant under a `supports("<feature>")` gate, and each
per-repo PR activates the gate by adding `supports <feature>` to its
cli.sh. PRs land async, in any order; no cross-PR lockstep needed.

- `feature-design` SKILL: propose-then-iterate authoring from a Jira
  ticket (or free-form description). Drafts a complete spec on the
  first pass, asks one composite redirect question, then writes the
  spec + patches tdfs.py + invokes scenario-from-ticket internally
  to produce the dormant scenario and draft test. Bails on Spike or
  unclear tickets rather than fabricating.
- `xtest/features/{README,CLAUDE}.md`: progressive-disclosure docs —
  human-facing README and agent-facing CLAUDE.md.
- `xtest/README.md` gains a brief "Test artifact directories" section
  pointing at scenarios/ and features/.
- `settings.json` + `plugin.json`: Write(xtest/features/**) allowlist,
  feature-design added to plugin skills array.

The complementary feature-orchestrate skill (fanning out per-repo
subagents to draft impl PRs in each touched repo) is a follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/plugin/plugin.json             |   2 +
 .claude/settings.json                  |   1 +
 .claude/skills/feature-design/SKILL.md | 118 +++++++++++++++++++++++++
 xtest/README.md                        |   7 ++
 xtest/features/CLAUDE.md               |  13 +++
 xtest/features/README.md               |  14 +++
 6 files changed, 155 insertions(+)
 create mode 100644 .claude/skills/feature-design/SKILL.md
 create mode 100644 xtest/features/CLAUDE.md
 create mode 100644 xtest/features/README.md

diff --git a/.claude/plugin/plugin.json b/.claude/plugin/plugin.json
index bb4c1311f..952feaea2 100644
--- a/.claude/plugin/plugin.json
+++ b/.claude/plugin/plugin.json
@@ -4,6 +4,7 @@
   "description": "Jira-ticket-driven scenarios for the OpenTDF test harness. Pulls ticket context from Jira (acli) — any ticket type, including bugs, feature stories, and PR-driven work — provisions pinned platform/KAS/SDK versions or refs (released versions, main, feature branches, PR SHAs), runs the xtest pytest suite, and tears down. Useful for QA, platform/SDK developers writing tests for new features first, and downstream first/third-party integrators.",
   "skills_dir": "../skills",
   "skills": [
+    "feature-design",
     "scenario-from-ticket",
     "scenario-matrix",
     "scenario-up",
@@ -32,6 +33,7 @@
       "Bash(acli jira workitem link list *)",
       "Bash(acli jira project view *)",
       "Write(xtest/scenarios/**)",
+      "Write(xtest/features/**)",
       "Write(xtest/bug_*_test.py)",
       "Write(tests/instances/**)"
     ]
diff --git a/.claude/settings.json b/.claude/settings.json
index a1dba2d80..9fd70f3c4 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -24,6 +24,7 @@
       "Bash(acli jira board view *)",
       "Bash(acli jira sprint view *)",
       "Write(xtest/scenarios/**)",
+      "Write(xtest/features/**)",
       "Write(xtest/bug_*_test.py)",
       "Write(tests/instances/**)",
       "Write(.claude/tmp/**)"
diff --git a/.claude/skills/feature-design/SKILL.md b/.claude/skills/feature-design/SKILL.md
new file mode 100644
index 000000000..ebb2eed96
--- /dev/null
+++ b/.claude/skills/feature-design/SKILL.md
@@ -0,0 +1,118 @@
+---
+name: feature-design
+description: Turn a multi-repo feature (or cross-repo bug fix) into a concrete spec at xtest/features/<name>.yaml plus the tests-side artifacts that have to land first (scenario, draft pytest, feature_type entry in tdfs.py). Pulls Jira context, drafts a complete spec from the ticket, then iterates with the user. Use when a feature touches more than one repo (e.g. platform + Go SDK + Java SDK + JS SDK) and you want to set up the cross-repo work in one go without manually authoring each piece.
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob, Skill
+---
+
+# feature-design
+
+You turn a fuzzy "let's build X across the OpenTDF repos" into a concrete bundle of artifacts that pin down the tests-side work first and stage the cross-repo work for handoff to `feature-orchestrate`.
+
+Two ideas to internalize before reading the steps:
+
+1. **Tests-side artifacts land first, dormant.** The scenario + draft test + `feature_type` entry merge to `tests/main` as a regular PR. They stay "all skipped" until each SDK opens its own PR adding a `supports <feature>` case to its `cli.sh` source — that PR's CI activates the test for that SDK. This means no cross-PR lockstep coordination; per-repo PRs land async, in any order.
+2. **Propose, don't ask.** Draft a complete spec from the Jira ticket on the first pass and let the user redirect what's wrong in a single revision. Only ask one composite question. If you're missing information you can't fill in (no Jira ticket, ambiguous scope, unclear feature name), bail — don't fabricate.
+
+## Inputs
+
+- Jira key (Story/Task usually; Bug works the same way), OR a free-text description of the feature.
+- (Optional) explicit list of repos to scope to, if the user wants something tighter than the default.
+
+## Steps
+
+### Step 1 — Pull the Jira context
+
+If a Jira key was given, run both — comments often carry scope refinements that aren't in the description:
+
+```bash
+acli jira workitem view <JIRA-KEY> --fields '*all' --json
+acli jira workitem comment list <JIRA-KEY>
+```
+
+Extract Issue Type, summary, description, status, and any comments about scope or implementation notes. If no Jira key, the user's description IS the spec input.
+
+### Step 2 — Propose a complete draft
+
+Draft the full spec body and the per-repo todo lists inline in your reply. Don't ask the user one field at a time — produce a complete first draft they can react to:
+
+- **Feature flag name** — snake_case identifier derived from the Jira summary. Becomes the `supports("<name>")` gate string AND the `feature_type` entry in `xtest/tdfs.py`. Validate it's a valid Python identifier and doesn't collide with an existing `feature_type` member.
+- **Touched repos** — default set is `tests, platform, sdk-go, sdk-java, sdk-web`. Trim or expand based on what the ticket says. Pure platform features skip the SDK repos; pure SDK-only features skip platform; `tests` is always present (the dormant scenario + tdfs.py entry has to live there).
+- **Per-repo todo lists** — 2-4 bullets per repo, derived from the description plus each repo's known role:
+  - `tests` — register the feature in `feature_type`, author the scenario, draft the test gated on `supports("<feature>")`.
+  - `platform` — service-side implementation (KAS path, policy plumbing, etc.) and any env-var handling in the dev harness (e.g. honoring `XT_WITH_<FEATURE>`).
+  - `sdk-go` / `sdk-java` / `sdk-web` — encrypt/decrypt path implementation, plus a `supports <feature>` case in that SDK's `cli.sh` source. **Don't pin the version bound in the spec** — the implementing engineer sets the `awk` predicate at PR time, since the bound depends on which release will ship the impl.
+- **Branch name** — `<JIRA-KEY>-<feature-slug>`, the same string across every touched repo so `feature-orchestrate` (and the user) can find each repo's PR by branch alone.
+
+Present the draft, then ask exactly one composite question: "Anything to redirect — feature name, touched repos, todo items, branch?" Apply edits in a single revision rather than turn-by-turn. The user can always drop into plain chat if they want to think out loud — just answer them and re-invoke this skill once the design firms up.
+
+If no Jira key was given AND the user's description doesn't pin down a clear scope (feature flag name, touched repos, intended behavior), bail rather than fabricate:
+
+```
+I need either (a) a Jira Story/Task/Bug key, or (b) a description that names
+the feature flag, the repos it touches, and the intended behavior. Add either
+and re-invoke this skill.
+```
+
+### Step 3 — Write the spec
+
+Write `xtest/features/<feature-name>.yaml`. Shape (still informal — no Pydantic model yet):
+
+```yaml
+apiVersion: opentdf.io/v1alpha1
+kind: Feature
+metadata:
+  name: <feature-name>                     # supports() string + feature_type entry, snake_case
+  jira: <JIRA-KEY>                         # omit if no ticket
+  title: "<one-line title>"
+  created: <YYYY-MM-DD>
+repos:
+  tests:
+    branch: <JIRA-KEY>-<feature-slug>
+    todo:
+      - Register "<feature-name>" in xtest/tdfs.py feature_type
+      - Author scenario + draft test (via scenario-from-ticket)
+  platform:
+    branch: <JIRA-KEY>-<feature-slug>
+    todo: [ ... ]
+  sdk-go:
+    branch: <JIRA-KEY>-<feature-slug>
+    todo:
+      - Implement <feature> in the encrypt/decrypt path
+      - Add `supports <feature>` case to cli.sh with version-bound awk predicate
+  sdk-java: { branch: ..., todo: [ ... ] }
+  sdk-web:  { branch: ..., todo: [ ... ] }
+scenarios:
+  - xtest/scenarios/<jira-key-lowercased>.yaml
+```
+
+PR status (open/merged/CI passing) deliberately is NOT in the spec — it's auto-discovered from `gh pr list --search "head:<branch>"` per repo whenever something asks "where are we?" The spec is a declaration of intent.
+
+### Step 4 — Drive the tests-side artifacts
+
+In this order, so each step's output feeds the next:
+
+1. **Add the feature flag to `xtest/tdfs.py`**. Find the `feature_type` Literal alias near the top of the file. Insert the new entry alphabetically. Don't touch any `cli.sh` files — `supports <feature>` cases land per-SDK in their own PRs.
+
+2. **Invoke `scenario-from-ticket`** via the Skill tool (`skill: scenario-from-ticket`, `args: <JIRA-KEY>`). It runs its Story/Task branch and produces the scenario + draft test gated on `supports("<feature>")` — pinning the feature-introducing components to `main` via `source.ref:`. If no Jira key was given, draft the scenario directly using the same shape (`xtest/scenarios/<feature-name>.yaml`).
+
+3. **Validate the scenario**:
+
+   ```bash
+   uv run python -m otdf_sdk_mgr.schema validate xtest/scenarios/<jira-key>.yaml
+   ```
+
+### Step 5 — Report
+
+One block summarizing:
+
+- The spec path (`xtest/features/<feature-name>.yaml`).
+- The scenario + draft test paths.
+- The line(s) added to `xtest/tdfs.py`.
+- A one-liner suggesting the next step: `feature-orchestrate xtest/features/<feature-name>.yaml`.
+
+## Notes
+
+- This skill produces **tests-side artifacts only**. It does NOT create branches in other repos, does NOT open PRs, does NOT install platform/SDK builds. That's `feature-orchestrate`'s job.
+- Bugs that span repos use the same shape — pass the Bug ticket key and `scenario-from-ticket`'s Bug branch fills `expected:` / `actual:` from the reproduction prose. The cross-repo gating still works: tests land dormant, each per-repo PR activates them by adding the supports case as part of the fix.
+- For an existing spec being revised, read it first and propose a diff rather than a full rewrite. The tests-side artifacts (scenario, tdfs.py entry) usually shouldn't be regenerated — just edit them surgically.
+- If the user starts the conversation by describing the feature in plain chat rather than invoking this skill, answer normally — re-invoke the skill once the scope firms up. Don't gatekeep.
diff --git a/xtest/README.md b/xtest/README.md
index 6bdfcc400..5de98942b 100644
--- a/xtest/README.md
+++ b/xtest/README.md
@@ -122,3 +122,10 @@ pytest
 rm -rf tmp
 pytest test_tdfs.py
 ```
+
+## Test artifact directories
+
+- **`scenarios/`** — Per-ticket scenario YAMLs that pin a platform / KAS / SDK topology to a specific pytest selection. Consumed by `otdf-local scenario run`.
+- **`features/`** — Multi-repo feature specs: features that touch more than one OpenTDF repo (platform + SDKs) authored as a single declaration of intent. See `features/README.md`.
+
+Both are produced by the Claude Code skills under `tests/.claude/skills/` (`scenario-from-ticket`, `feature-design`, etc.) and can also be hand-authored.
diff --git a/xtest/features/CLAUDE.md b/xtest/features/CLAUDE.md
new file mode 100644
index 000000000..9f5e9a7e3
--- /dev/null
+++ b/xtest/features/CLAUDE.md
@@ -0,0 +1,13 @@
+# Agent guidance for xtest/features
+
+This directory is owned by two skills:
+
+- **`feature-design`** drafts new spec files here from a Jira ticket (or free-form description) using propose-then-iterate authoring. It also writes the tests-side artifacts that have to land first: the `feature_type` entry in `xtest/tdfs.py`, the scenario under `xtest/scenarios/`, and (if needed) a draft pytest.
+- **`feature-orchestrate`** reads spec files and fans out per-repo subagents that implement the feature in each touched repo and open draft PRs.
+
+When you see a `xtest/features/<name>.yaml` referenced:
+
+- It is canonical for the feature's flag name, scope, and per-repo todos.
+- It is NOT canonical for status — query `gh pr list --search "head:<branch>"` per repo.
+
+Don't hand-author spec files in this directory unless you've also done what `feature-design` would do (add the entry to `feature_type` in `xtest/tdfs.py`, generate the scenario + draft test). Those side effects keep the spec consistent with the tests it depends on.
diff --git a/xtest/features/README.md b/xtest/features/README.md
new file mode 100644
index 000000000..2a1f55510
--- /dev/null
+++ b/xtest/features/README.md
@@ -0,0 +1,14 @@
+# xtest/features
+
+Specs for features that touch more than one OpenTDF repo (e.g. platform + Go SDK + Java SDK + JS SDK).
+
+Each `<feature-name>.yaml` captures:
+
+- The feature flag name — the `supports("<name>")` gate string in `xtest/tdfs.py`.
+- The Jira ticket driving the work, if any.
+- Per-repo todo lists and the shared branch name to use across them.
+- The scenario(s) under `xtest/scenarios/` that exercise the feature once each repo's PR lands.
+
+Specs are declarative — they describe intent, not status. PR state (open / merged / CI passing) is auto-discovered from `gh pr list --search "head:<branch>"` per repo, not stored here.
+
+See `CLAUDE.md` in this directory for how Claude Code skills produce and consume these files.

From cef6441eacca32454ec714706093546123644d3a Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 15 May 2026 21:45:00 -0400
Subject: [PATCH 20/64] fix(.claude): allow Skill tool + correct acli comment
 list syntax (DSPX-3302)

Headless dogfooding (runs 1 and 2 of scenario-from-ticket on DSPX-2719)
surfaced two real gaps:

- The `Skill` tool was denied on both runs because the allowlist didn't
  cover it, so the body of SKILL.md wasn't injected on invocation; the
  agent had to manually `Read` the skill file ~25 turns in, wasting time
  and biasing exploration toward grepping unrelated files first.
  Add `Skill(*)` to settings.json and per-skill `Skill(<name>)` entries
  to plugin.json (the latter enumerates exactly what downstream installs
  get, since they shouldn't inherit a wildcard).
- `acli jira workitem comment list` requires `--key <KEY>` (the
  subcommand differs from `view`, which takes the key positionally).
  Both scenario-from-ticket and feature-design had the wrong form;
  corrected, with a one-line note about the asymmetry so the next
  agent doesn't paraphrase.

Verified via run-3 on DSPX-2719: 41 turns / 5m16s / $1.07 (vs run-1's
48 turns / 6m44s / $1.27). Skill tool returned success on first call,
both acli commands ran cleanly, the Story/Task branch produced
`source.ref: main` pins correctly (no more incorrectly defaulting to
`dist: lts`), and the agent's `actual:` field correctly enumerated all
three test-infrastructure prerequisites including a `with_ecdsa_binding`
parameter that run-1's scenario missed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/plugin/plugin.json                   | 7 +++++++
 .claude/settings.json                        | 1 +
 .claude/skills/feature-design/SKILL.md       | 4 ++--
 .claude/skills/scenario-from-ticket/SKILL.md | 4 ++--
 4 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/.claude/plugin/plugin.json b/.claude/plugin/plugin.json
index 952feaea2..cbf554efa 100644
--- a/.claude/plugin/plugin.json
+++ b/.claude/plugin/plugin.json
@@ -32,6 +32,13 @@
       "Bash(acli jira workitem attachment list *)",
       "Bash(acli jira workitem link list *)",
       "Bash(acli jira project view *)",
+      "Skill(feature-design)",
+      "Skill(scenario-from-ticket)",
+      "Skill(scenario-matrix)",
+      "Skill(scenario-up)",
+      "Skill(scenario-run)",
+      "Skill(scenario-tear-down)",
+      "Skill(instance-status)",
       "Write(xtest/scenarios/**)",
       "Write(xtest/features/**)",
       "Write(xtest/bug_*_test.py)",
diff --git a/.claude/settings.json b/.claude/settings.json
index 9fd70f3c4..0f4e65da3 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -23,6 +23,7 @@
       "Bash(acli jira project view *)",
       "Bash(acli jira board view *)",
       "Bash(acli jira sprint view *)",
+      "Skill(*)",
       "Write(xtest/scenarios/**)",
       "Write(xtest/features/**)",
       "Write(xtest/bug_*_test.py)",
diff --git a/.claude/skills/feature-design/SKILL.md b/.claude/skills/feature-design/SKILL.md
index ebb2eed96..170e650ab 100644
--- a/.claude/skills/feature-design/SKILL.md
+++ b/.claude/skills/feature-design/SKILL.md
@@ -22,11 +22,11 @@ Two ideas to internalize before reading the steps:
 
 ### Step 1 — Pull the Jira context
 
-If a Jira key was given, run both — comments often carry scope refinements that aren't in the description:
+If a Jira key was given, run both — `view` takes the key positionally, `comment list` requires `--key`; comments often carry scope refinements that aren't in the description:
 
 ```bash
 acli jira workitem view <JIRA-KEY> --fields '*all' --json
-acli jira workitem comment list <JIRA-KEY>
+acli jira workitem comment list --key <JIRA-KEY>
 ```
 
 Extract Issue Type, summary, description, status, and any comments about scope or implementation notes. If no Jira key, the user's description IS the spec input.
diff --git a/.claude/skills/scenario-from-ticket/SKILL.md b/.claude/skills/scenario-from-ticket/SKILL.md
index 1f573b592..7f154ded9 100644
--- a/.claude/skills/scenario-from-ticket/SKILL.md
+++ b/.claude/skills/scenario-from-ticket/SKILL.md
@@ -17,11 +17,11 @@ The Jira key also becomes the working **branch name** (`<JIRA-KEY>-repro` for Bu
 
 ## Step 1 — Pull the Jira ticket into context
 
-**Always run BOTH commands**. Don't skip the comment list — comments often carry the most recent reproduction status, "what changed" notes, or "fixed by PR #N" pointers that aren't in the original description:
+**Always run BOTH commands** — exactly as shown; the two subcommands take the key differently (`view` is positional, `comment list` requires `--key`). Don't skip the comment list — comments often carry the most recent reproduction status, "what changed" notes, or "fixed by PR #N" pointers that aren't in the original description:
 
 ```bash
 acli jira workitem view <JIRA-KEY> --fields '*all' --json
-acli jira workitem comment list <JIRA-KEY>
+acli jira workitem comment list --key <JIRA-KEY>
 ```
 
 From the JSON output of the first command, extract:

From d7ceddd1d2534492b520a1d1f38289ff02ded2a1 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 15 May 2026 21:53:41 -0400
Subject: [PATCH 21/64] feat(otdf-sdk-mgr): schema dump CLI + xtest/schema
 canonical JSON Schemas (DSPX-3302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Headless runs of scenario-from-ticket kept trying `python3 -c "from
otdf_sdk_mgr.schema import Scenario; ..."` to introspect Pydantic model
shape while authoring scenarios. That form isn't in the plugin's Bash
allowlist (deliberately — it's arbitrary code execution), so the agent
fell back to Reading schema.py source. Static, committed JSON Schemas
give the same information declaratively without needing a python verb
in the allowlist at all.

- `otdf-sdk-mgr schema dump [--out-dir]`: writes
  `xtest/schema/{scenario,instance}.schema.json` from
  `Model.model_json_schema()`, sorted-keys + trailing newline so output
  is byte-stable. Add new models to `SCHEMAS` in cli_schema.py and they
  get picked up automatically.
- `xtest/schema/` is committed with the generated files plus brief
  README/CLAUDE.md (progressive-disclosure, mirroring xtest/features/).
- `test_schema_sync.py` parametrizes over `SCHEMAS` and fails if any
  committed file drifts from the live model — the safety net for
  "someone edited a Pydantic model without regenerating."
- `scenario-from-ticket` SKILL.md Step 5 now points at
  `xtest/schema/scenario.schema.json` as the canonical field list.
- `xtest/README.md` lists the new directory alongside `scenarios/` and
  `features/`.

No allowlist changes needed — `Bash(uv run otdf-sdk-mgr *)` already
covers the dump subcommand, and `Read` is unrestricted.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/skills/scenario-from-ticket/SKILL.md |   2 +-
 otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py         |   2 +
 otdf-sdk-mgr/src/otdf_sdk_mgr/cli_schema.py  |  57 +++
 otdf-sdk-mgr/tests/test_schema_sync.py       |  38 ++
 xtest/README.md                              |   3 +-
 xtest/schema/CLAUDE.md                       |   8 +
 xtest/schema/README.md                       |  16 +
 xtest/schema/instance.schema.json            | 261 +++++++++++
 xtest/schema/scenario.schema.json            | 443 +++++++++++++++++++
 9 files changed, 828 insertions(+), 2 deletions(-)
 create mode 100644 otdf-sdk-mgr/src/otdf_sdk_mgr/cli_schema.py
 create mode 100644 otdf-sdk-mgr/tests/test_schema_sync.py
 create mode 100644 xtest/schema/CLAUDE.md
 create mode 100644 xtest/schema/README.md
 create mode 100644 xtest/schema/instance.schema.json
 create mode 100644 xtest/schema/scenario.schema.json

diff --git a/.claude/skills/scenario-from-ticket/SKILL.md b/.claude/skills/scenario-from-ticket/SKILL.md
index 7f154ded9..12e960674 100644
--- a/.claude/skills/scenario-from-ticket/SKILL.md
+++ b/.claude/skills/scenario-from-ticket/SKILL.md
@@ -92,7 +92,7 @@ Likely candidates: `test_tdfs.py` (roundtrip), `test_abac.py` (ABAC), `test_lega
 
 ## Step 5 — Write `xtest/scenarios/<id>.yaml`
 
-The schema (`otdf_sdk_mgr.schema.Scenario`) rejects unknown fields. Each pin (`PlatformPin`, `KasPin`) requires **exactly one** of `dist:`, `source:`, or `image:`. `image:` is reserved for forward-compat and rejected today — pick `dist:` or `source:`.
+The canonical field list (titles, types, defaults, `anyOf` branches) lives in `xtest/schema/scenario.schema.json` — `Read` it whenever you need to know what's allowed. Each pin (`PlatformPin`, `KasPin`) requires **exactly one** of `dist:`, `source:`, or `image:`. `image:` is reserved for forward-compat and rejected today — pick `dist:` or `source:`.
 
 Released-version pin (typical Bug scenario):
 
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py
index 24148bdd7..78b137c95 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py
@@ -10,6 +10,7 @@
 import typer
 
 from otdf_sdk_mgr.cli_install import install_app
+from otdf_sdk_mgr.cli_schema import schema_app
 from otdf_sdk_mgr.cli_versions import versions_app
 from otdf_sdk_mgr.config import ALL_SDKS, get_sdk_dirs
 
@@ -20,6 +21,7 @@
 )
 
 app.add_typer(install_app, name="install")
+app.add_typer(schema_app, name="schema")
 app.add_typer(versions_app, name="versions")
 
 
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_schema.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_schema.py
new file mode 100644
index 000000000..b3fb17b7d
--- /dev/null
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_schema.py
@@ -0,0 +1,57 @@
+"""`otdf-sdk-mgr schema` subcommands.
+
+Emit canonical JSON Schemas for the Pydantic models in `otdf_sdk_mgr.schema`
+so agents (and humans) can introspect the on-disk YAML formats without
+running `python -c` against the package. The generated files live under
+`xtest/schema/` and are kept in sync via `tests/test_schema_sync.py`.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from otdf_sdk_mgr.schema import Instance, Scenario
+
+schema_app = typer.Typer(help="Emit JSON Schemas for the scenario/instance models.")
+
+# (model_class, output_filename). Add new models here and `schema dump`
+# will pick them up automatically.
+SCHEMAS: tuple[tuple[type, str], ...] = (
+    (Scenario, "scenario.schema.json"),
+    (Instance, "instance.schema.json"),
+)
+
+
+def render(model: type) -> str:
+    """Render `model.model_json_schema()` as a deterministic JSON string.
+
+    Sorted keys and a trailing newline so byte-equality comparisons in the
+    sync test are stable.
+    """
+    return json.dumps(model.model_json_schema(), indent=2, sort_keys=True) + "\n"
+
+
+@schema_app.command("dump")
+def dump(
+    out_dir: Annotated[
+        Path,
+        typer.Option(
+            "--out-dir",
+            help="Directory to write *.schema.json files into.",
+        ),
+    ] = Path("xtest/schema"),
+) -> None:
+    """Write JSON Schemas for every canonical scenario/instance model.
+
+    Overwrites existing files. Re-run whenever a Pydantic model changes;
+    the committed schemas in xtest/schema/ are otherwise the source of
+    truth that the scenario-authoring skills read.
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for model, filename in SCHEMAS:
+        path = out_dir / filename
+        path.write_text(render(model), encoding="utf-8")
+        typer.echo(f"  wrote {path}")
diff --git a/otdf-sdk-mgr/tests/test_schema_sync.py b/otdf-sdk-mgr/tests/test_schema_sync.py
new file mode 100644
index 000000000..addeaf8ad
--- /dev/null
+++ b/otdf-sdk-mgr/tests/test_schema_sync.py
@@ -0,0 +1,38 @@
+"""Guard that the committed JSON Schemas under xtest/schema/ stay in sync
+with the live Pydantic models.
+
+The skills authoring scenarios read those JSON files directly to know what
+fields are allowed; if a Pydantic model gains, loses, or renames a field
+without a corresponding `uv run otdf-sdk-mgr schema dump`, the skills will
+silently rely on a stale schema. This test makes that drift loud.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from otdf_sdk_mgr.cli_schema import SCHEMAS, render
+
+
+def _xtest_schema_dir() -> Path:
+    """Locate xtest/schema/ relative to this test file.
+
+    The repo layout puts otdf-sdk-mgr/tests/ next to xtest/, so two parents
+    up from this file is the tests/ root.
+    """
+    return Path(__file__).resolve().parents[2] / "xtest" / "schema"
+
+
+@pytest.mark.parametrize(("model", "filename"), SCHEMAS, ids=lambda v: getattr(v, "__name__", v))
+def test_committed_schema_matches_model(model: type, filename: str) -> None:
+    path = _xtest_schema_dir() / filename
+    assert path.is_file(), (
+        f"Missing {path}. Run `uv run otdf-sdk-mgr schema dump` to regenerate."
+    )
+    expected = render(model)
+    actual = path.read_text(encoding="utf-8")
+    assert actual == expected, (
+        f"{path} is out of sync with {model.__name__}. "
+        f"Run `uv run otdf-sdk-mgr schema dump` to regenerate."
+    )
diff --git a/xtest/README.md b/xtest/README.md
index 5de98942b..0c7400fac 100644
--- a/xtest/README.md
+++ b/xtest/README.md
@@ -127,5 +127,6 @@ pytest test_tdfs.py
 
 - **`scenarios/`** — Per-ticket scenario YAMLs that pin a platform / KAS / SDK topology to a specific pytest selection. Consumed by `otdf-local scenario run`.
 - **`features/`** — Multi-repo feature specs: features that touch more than one OpenTDF repo (platform + SDKs) authored as a single declaration of intent. See `features/README.md`.
+- **`schema/`** — Generated JSON Schemas for the canonical scenario / instance models. Regenerate via `uv run otdf-sdk-mgr schema dump` after editing the Pydantic models in `otdf-sdk-mgr/src/otdf_sdk_mgr/schema.py`. See `schema/README.md`.
 
-Both are produced by the Claude Code skills under `tests/.claude/skills/` (`scenario-from-ticket`, `feature-design`, etc.) and can also be hand-authored.
+The first two are produced by the Claude Code skills under `tests/.claude/skills/` (`scenario-from-ticket`, `feature-design`, etc.) and can also be hand-authored.
diff --git a/xtest/schema/CLAUDE.md b/xtest/schema/CLAUDE.md
new file mode 100644
index 000000000..7b2154591
--- /dev/null
+++ b/xtest/schema/CLAUDE.md
@@ -0,0 +1,8 @@
+# Agent guidance for xtest/schema
+
+These JSON Schemas are the canonical reference for the on-disk YAML formats. When you need to know what fields a scenario or instance accepts:
+
+- **Read these files**. Don't run `python -c "from otdf_sdk_mgr.schema import ..."` to introspect — those forms aren't in the plugin's allowlist, and the JSON Schemas have the same information in declarative form (titles, types, `anyOf` for ref-vs-version pins, `additionalProperties: false`, default values, etc.).
+- The files are byte-stable and sorted; safe to grep, diff, or quote.
+
+If a Pydantic model changes and these files drift, the user (or CI) will regenerate them via `uv run otdf-sdk-mgr schema dump`. Don't try to regenerate them yourself unless you're explicitly fixing the drift in a schema-editing PR.
diff --git a/xtest/schema/README.md b/xtest/schema/README.md
new file mode 100644
index 000000000..c292457a6
--- /dev/null
+++ b/xtest/schema/README.md
@@ -0,0 +1,16 @@
+# xtest/schema
+
+JSON Schemas for the canonical scenario / instance YAML formats. One file per Pydantic model in `otdf-sdk-mgr/src/otdf_sdk_mgr/schema.py`:
+
+- `scenario.schema.json` — the shape that `xtest/scenarios/<id>.yaml` validates against.
+- `instance.schema.json` — the shape of `tests/instances/<name>/instance.yaml`.
+
+These files are generated artifacts. To refresh them after editing a Pydantic model:
+
+```bash
+uv run --project otdf-sdk-mgr otdf-sdk-mgr schema dump
+```
+
+A pytest in `otdf-sdk-mgr/tests/test_schema_sync.py` fails CI if the committed files drift from what the live models would produce.
+
+See `CLAUDE.md` for how Claude Code skills consume these files.
diff --git a/xtest/schema/instance.schema.json b/xtest/schema/instance.schema.json
new file mode 100644
index 000000000..cdf172db0
--- /dev/null
+++ b/xtest/schema/instance.schema.json
@@ -0,0 +1,261 @@
+{
+  "$defs": {
+    "Fixtures": {
+      "additionalProperties": false,
+      "properties": {
+        "attributes": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Attributes"
+        },
+        "policy": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Policy"
+        }
+      },
+      "title": "Fixtures",
+      "type": "object"
+    },
+    "KasPin": {
+      "additionalProperties": false,
+      "description": "Per-KAS-instance version + mode pin.",
+      "properties": {
+        "dist": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Dist"
+        },
+        "features": {
+          "additionalProperties": {
+            "type": "boolean"
+          },
+          "title": "Features",
+          "type": "object"
+        },
+        "mode": {
+          "default": "standard",
+          "enum": [
+            "standard",
+            "key_management"
+          ],
+          "title": "Mode",
+          "type": "string"
+        },
+        "source": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SourceRef"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        }
+      },
+      "title": "KasPin",
+      "type": "object"
+    },
+    "Metadata": {
+      "additionalProperties": false,
+      "properties": {
+        "created": {
+          "anyOf": [
+            {
+              "format": "date",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Created"
+        },
+        "id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Id"
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Name"
+        },
+        "title": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Title"
+        }
+      },
+      "title": "Metadata",
+      "type": "object"
+    },
+    "PlatformPin": {
+      "additionalProperties": false,
+      "description": "Version pin for the platform service.\n\n`dist` references a built binary at `xtest/platform/dist/<dist>/service`\nproduced by `otdf-sdk-mgr install platform:<version>`.\n`source.ref` is a git ref to build from on demand.",
+      "properties": {
+        "dist": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Dist"
+        },
+        "source": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SourceRef"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        }
+      },
+      "title": "PlatformPin",
+      "type": "object"
+    },
+    "PortsConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "base": {
+          "default": 8080,
+          "maximum": 60000,
+          "minimum": 1024,
+          "title": "Base",
+          "type": "integer"
+        }
+      },
+      "title": "PortsConfig",
+      "type": "object"
+    },
+    "SourceRef": {
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Optional local checkout path",
+          "title": "Path"
+        },
+        "ref": {
+          "description": "Git tag, branch, or SHA",
+          "title": "Ref",
+          "type": "string"
+        }
+      },
+      "required": [
+        "ref"
+      ],
+      "title": "SourceRef",
+      "type": "object"
+    }
+  },
+  "additionalProperties": false,
+  "description": "Standalone instance definition (one platform + N KAS).\n\nPersisted to `tests/instances/<name>/instance.yaml`. Also embedded inside\nScenario to keep the \"describe a bug-repro environment\" entry point a\nsingle file.",
+  "properties": {
+    "apiVersion": {
+      "const": "opentdf.io/v1alpha1",
+      "default": "opentdf.io/v1alpha1",
+      "title": "Apiversion",
+      "type": "string"
+    },
+    "features": {
+      "additionalProperties": {
+        "type": "boolean"
+      },
+      "title": "Features",
+      "type": "object"
+    },
+    "fixtures": {
+      "$ref": "#/$defs/Fixtures"
+    },
+    "kas": {
+      "additionalProperties": {
+        "$ref": "#/$defs/KasPin"
+      },
+      "title": "Kas",
+      "type": "object"
+    },
+    "kind": {
+      "const": "Instance",
+      "default": "Instance",
+      "title": "Kind",
+      "type": "string"
+    },
+    "metadata": {
+      "$ref": "#/$defs/Metadata"
+    },
+    "platform": {
+      "$ref": "#/$defs/PlatformPin"
+    },
+    "ports": {
+      "$ref": "#/$defs/PortsConfig"
+    }
+  },
+  "required": [
+    "platform"
+  ],
+  "title": "Instance",
+  "type": "object"
+}
diff --git a/xtest/schema/scenario.schema.json b/xtest/schema/scenario.schema.json
new file mode 100644
index 000000000..426e11c51
--- /dev/null
+++ b/xtest/schema/scenario.schema.json
@@ -0,0 +1,443 @@
+{
+  "$defs": {
+    "Fixtures": {
+      "additionalProperties": false,
+      "properties": {
+        "attributes": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Attributes"
+        },
+        "policy": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Policy"
+        }
+      },
+      "title": "Fixtures",
+      "type": "object"
+    },
+    "Instance": {
+      "additionalProperties": false,
+      "description": "Standalone instance definition (one platform + N KAS).\n\nPersisted to `tests/instances/<name>/instance.yaml`. Also embedded inside\nScenario to keep the \"describe a bug-repro environment\" entry point a\nsingle file.",
+      "properties": {
+        "apiVersion": {
+          "const": "opentdf.io/v1alpha1",
+          "default": "opentdf.io/v1alpha1",
+          "title": "Apiversion",
+          "type": "string"
+        },
+        "features": {
+          "additionalProperties": {
+            "type": "boolean"
+          },
+          "title": "Features",
+          "type": "object"
+        },
+        "fixtures": {
+          "$ref": "#/$defs/Fixtures"
+        },
+        "kas": {
+          "additionalProperties": {
+            "$ref": "#/$defs/KasPin"
+          },
+          "title": "Kas",
+          "type": "object"
+        },
+        "kind": {
+          "const": "Instance",
+          "default": "Instance",
+          "title": "Kind",
+          "type": "string"
+        },
+        "metadata": {
+          "$ref": "#/$defs/Metadata"
+        },
+        "platform": {
+          "$ref": "#/$defs/PlatformPin"
+        },
+        "ports": {
+          "$ref": "#/$defs/PortsConfig"
+        }
+      },
+      "required": [
+        "platform"
+      ],
+      "title": "Instance",
+      "type": "object"
+    },
+    "KasPin": {
+      "additionalProperties": false,
+      "description": "Per-KAS-instance version + mode pin.",
+      "properties": {
+        "dist": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Dist"
+        },
+        "features": {
+          "additionalProperties": {
+            "type": "boolean"
+          },
+          "title": "Features",
+          "type": "object"
+        },
+        "mode": {
+          "default": "standard",
+          "enum": [
+            "standard",
+            "key_management"
+          ],
+          "title": "Mode",
+          "type": "string"
+        },
+        "source": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SourceRef"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        }
+      },
+      "title": "KasPin",
+      "type": "object"
+    },
+    "Metadata": {
+      "additionalProperties": false,
+      "properties": {
+        "created": {
+          "anyOf": [
+            {
+              "format": "date",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Created"
+        },
+        "id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Id"
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Name"
+        },
+        "title": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Title"
+        }
+      },
+      "title": "Metadata",
+      "type": "object"
+    },
+    "PlatformPin": {
+      "additionalProperties": false,
+      "description": "Version pin for the platform service.\n\n`dist` references a built binary at `xtest/platform/dist/<dist>/service`\nproduced by `otdf-sdk-mgr install platform:<version>`.\n`source.ref` is a git ref to build from on demand.",
+      "properties": {
+        "dist": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Dist"
+        },
+        "source": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SourceRef"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        }
+      },
+      "title": "PlatformPin",
+      "type": "object"
+    },
+    "PortsConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "base": {
+          "default": 8080,
+          "maximum": 60000,
+          "minimum": 1024,
+          "title": "Base",
+          "type": "integer"
+        }
+      },
+      "title": "PortsConfig",
+      "type": "object"
+    },
+    "ScenarioSdk": {
+      "additionalProperties": false,
+      "description": "One ordered SDK selection within a scenario role.",
+      "properties": {
+        "sdk": {
+          "enum": [
+            "go",
+            "java",
+            "js"
+          ],
+          "title": "Sdk",
+          "type": "string"
+        },
+        "source": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "For Go: \"platform\" to use the monorepo module path",
+          "title": "Source"
+        },
+        "version": {
+          "title": "Version",
+          "type": "string"
+        }
+      },
+      "required": [
+        "sdk",
+        "version"
+      ],
+      "title": "ScenarioSdk",
+      "type": "object"
+    },
+    "ScenarioSdks": {
+      "additionalProperties": false,
+      "description": "Encrypt/decrypt split mirrors xtest's --sdks-encrypt/--sdks-decrypt.\n\nSelections are ordered to preserve the eventual argv order, and are\nde-duplicated within each role by (sdk, version, source).",
+      "properties": {
+        "decrypt": {
+          "items": {
+            "$ref": "#/$defs/ScenarioSdk"
+          },
+          "title": "Decrypt",
+          "type": "array"
+        },
+        "encrypt": {
+          "items": {
+            "$ref": "#/$defs/ScenarioSdk"
+          },
+          "title": "Encrypt",
+          "type": "array"
+        }
+      },
+      "title": "ScenarioSdks",
+      "type": "object"
+    },
+    "SourceRef": {
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Optional local checkout path",
+          "title": "Path"
+        },
+        "ref": {
+          "description": "Git tag, branch, or SHA",
+          "title": "Ref",
+          "type": "string"
+        }
+      },
+      "required": [
+        "ref"
+      ],
+      "title": "SourceRef",
+      "type": "object"
+    },
+    "Suite": {
+      "additionalProperties": false,
+      "description": "Pytest selection + flags.",
+      "properties": {
+        "containers": {
+          "description": "Forwarded to --containers as a whitespace-separated list",
+          "items": {
+            "enum": [
+              "ztdf",
+              "ztdf-ecwrap"
+            ],
+            "type": "string"
+          },
+          "title": "Containers",
+          "type": "array"
+        },
+        "extra_args": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Extra Args",
+          "type": "array"
+        },
+        "kexpr": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Forwarded to pytest -k",
+          "title": "Kexpr"
+        },
+        "markers": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Forwarded to -m",
+          "title": "Markers"
+        },
+        "targets": {
+          "description": "Positional pytest targets, e.g. test files or path::node ids",
+          "items": {
+            "type": "string"
+          },
+          "title": "Targets",
+          "type": "array"
+        }
+      },
+      "title": "Suite",
+      "type": "object"
+    }
+  },
+  "additionalProperties": false,
+  "description": "Top-level scenarios.yaml model.\n\nComposes an Instance with SDK pins and a pytest Suite selection.",
+  "properties": {
+    "actual": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Actual"
+    },
+    "apiVersion": {
+      "const": "opentdf.io/v1alpha1",
+      "default": "opentdf.io/v1alpha1",
+      "title": "Apiversion",
+      "type": "string"
+    },
+    "expected": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Expected"
+    },
+    "instance": {
+      "$ref": "#/$defs/Instance",
+      "description": "Inline instance definition"
+    },
+    "kind": {
+      "const": "Scenario",
+      "default": "Scenario",
+      "title": "Kind",
+      "type": "string"
+    },
+    "metadata": {
+      "$ref": "#/$defs/Metadata"
+    },
+    "sdks": {
+      "$ref": "#/$defs/ScenarioSdks"
+    },
+    "suite": {
+      "$ref": "#/$defs/Suite"
+    }
+  },
+  "required": [
+    "instance",
+    "suite"
+  ],
+  "title": "Scenario",
+  "type": "object"
+}

From a36ee42e6bfcc284826a6ce359aab37dc4a3f395 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 22 May 2026 10:15:16 -0400
Subject: [PATCH 22/64] fixup play nicer with claude code permissions model

---
 .claude/plugin/plugin.json                   | 2 +-
 .claude/settings.json                        | 2 +-
 .claude/skills/scenario-from-ticket/SKILL.md | 6 +++---
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.claude/plugin/plugin.json b/.claude/plugin/plugin.json
index cbf554efa..906d0d240 100644
--- a/.claude/plugin/plugin.json
+++ b/.claude/plugin/plugin.json
@@ -41,7 +41,7 @@
       "Skill(instance-status)",
       "Write(xtest/scenarios/**)",
       "Write(xtest/features/**)",
-      "Write(xtest/bug_*_test.py)",
+      "Write(xtest/bugs/*_test.py)",
       "Write(tests/instances/**)"
     ]
   },
diff --git a/.claude/settings.json b/.claude/settings.json
index 0f4e65da3..a14484c31 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -26,7 +26,7 @@
       "Skill(*)",
       "Write(xtest/scenarios/**)",
       "Write(xtest/features/**)",
-      "Write(xtest/bug_*_test.py)",
+      "Write(xtest/bugs/*_test.py)",
       "Write(tests/instances/**)",
       "Write(.claude/tmp/**)"
     ]
diff --git a/.claude/skills/scenario-from-ticket/SKILL.md b/.claude/skills/scenario-from-ticket/SKILL.md
index 12e960674..21db97f88 100644
--- a/.claude/skills/scenario-from-ticket/SKILL.md
+++ b/.claude/skills/scenario-from-ticket/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: scenario-from-ticket
-description: Pull a Jira ticket of any type (Bug, Story, Task, Spike) into context via `acli jira workitem view` + `acli jira workitem comment list`, then turn it into an xtest/scenarios/<JIRA-KEY>.yaml manifest. Pins platform/KAS/SDKs to a released version (`dist:`), a branch or SHA (`source.ref:`), or the head of a PR — whichever matches the ticket. Optionally drafts xtest/bug_<jira_key>_test.py when no existing pytest covers the behavior. Use when the user mentions a Jira key like DSPX-1234 (or any [PROJECT]-[NUMBER]) and wants a runnable scenario — reproducing a bug, writing a TDD test for a new feature, or validating behavior at a specific ref.
+description: Pull a Jira ticket of any type (Bug, Story, Task, Spike) into context via `acli jira workitem view` + `acli jira workitem comment list`, then turn it into an xtest/scenarios/<JIRA-KEY>.yaml manifest. Pins platform/KAS/SDKs to a released version (`dist:`), a branch or SHA (`source.ref:`), or the head of a PR — whichever matches the ticket. Optionally drafts xtest/bugs/<jira_key>_test.py when no existing pytest covers the behavior. Use when the user mentions a Jira key like DSPX-1234 (or any [PROJECT]-[NUMBER]) and wants a runnable scenario — reproducing a bug, writing a TDD test for a new feature, or validating behavior at a specific ref.
 allowed-tools: Bash, Read, Write, Grep, Glob
 ---
 
@@ -11,7 +11,7 @@ You produce a `xtest/scenarios/<jira-key-lowercased>.yaml` manifest from a Jira
 Two artifacts:
 
 1. `xtest/scenarios/<jira-key-lowercased>.yaml` — validated against `otdf_sdk_mgr.schema.Scenario`.
-2. (Optional) `xtest/bug_<jira_key_lowercased>_test.py` — only if no existing xtest pytest already exercises the behavior. The `bug_` prefix is a slug, not a type marker: feature-driven tests use it too.
+2. (Optional) `xtest/bugs/<jira_key_lowercased>_test.py` — only if no existing xtest pytest already exercises the behavior.
 
 The Jira key also becomes the working **branch name** (`<JIRA-KEY>-repro` for Bugs, `<JIRA-KEY>-tdd` for Stories/Tasks) and the scenario file's `metadata.id`.
 
@@ -146,7 +146,7 @@ uv run python -m otdf_sdk_mgr.schema validate xtest/scenarios/<id>.yaml
 
 ## Step 6 — If no existing test fits
 
-Draft `xtest/bug_<id>_test.py` using the `encrypt_sdk` / `decrypt_sdk` fixtures (pattern: `xtest/test_tdfs.py`). The `bug_` prefix is a historical slug applied to every scenario-tied test — feature/TDD ones use it too; don't let the name confuse you. Surface the new file in your reply for the user to review — never silently land assertions.
+Draft `xtest/bugs/<id>_test.py` using the `encrypt_sdk` / `decrypt_sdk` fixtures (pattern: `xtest/test_tdfs.py`). Surface the new file in your reply for the user to review — never silently land assertions.
 
 For TDD tests where the underlying feature isn't yet implemented, gate participation behind `<sdk>.supports("<feature>")` and call `pytest.skip(...)` when the gate fails. The scenario then runs as "all skipped" until the SDK supports entry lands, at which point the test becomes a real assertion.
 

From 844a033f8e38fd5e97163478efa7076575a8024a Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 22 May 2026 10:31:58 -0400
Subject: [PATCH 23/64] fixup better skill descriptions

---
 .claude/skills/feature-design/SKILL.md     | 2 +-
 .claude/skills/instance-status/SKILL.md    | 2 +-
 .claude/skills/scenario-matrix/SKILL.md    | 2 +-
 .claude/skills/scenario-run/SKILL.md       | 2 +-
 .claude/skills/scenario-tear-down/SKILL.md | 2 +-
 .claude/skills/scenario-up/SKILL.md        | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.claude/skills/feature-design/SKILL.md b/.claude/skills/feature-design/SKILL.md
index 170e650ab..bf3854aa6 100644
--- a/.claude/skills/feature-design/SKILL.md
+++ b/.claude/skills/feature-design/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: feature-design
-description: Turn a multi-repo feature (or cross-repo bug fix) into a concrete spec at xtest/features/<name>.yaml plus the tests-side artifacts that have to land first (scenario, draft pytest, feature_type entry in tdfs.py). Pulls Jira context, drafts a complete spec from the ticket, then iterates with the user. Use when a feature touches more than one repo (e.g. platform + Go SDK + Java SDK + JS SDK) and you want to set up the cross-repo work in one go without manually authoring each piece.
+description: Use when a feature or bug fix spans multiple repos (platform + Go/Java/JS SDKs) and you want the cross-repo spec and test artifacts set up in one pass.
 allowed-tools: Bash, Read, Write, Edit, Grep, Glob, Skill
 ---
 
diff --git a/.claude/skills/instance-status/SKILL.md b/.claude/skills/instance-status/SKILL.md
index 64bd545a0..cef888d2a 100644
--- a/.claude/skills/instance-status/SKILL.md
+++ b/.claude/skills/instance-status/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: instance-status
-description: Report which test instances exist on disk, which are running, and the health of each service. Use when the user asks "what's running" or before bringing up another scenario to avoid port collisions.
+description: Use when the user asks what's running, or before starting a scenario to check for port collisions.
 allowed-tools: Bash, Read
 ---
 
diff --git a/.claude/skills/scenario-matrix/SKILL.md b/.claude/skills/scenario-matrix/SKILL.md
index d28637495..ee01aba54 100644
--- a/.claude/skills/scenario-matrix/SKILL.md
+++ b/.claude/skills/scenario-matrix/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: scenario-matrix
-description: Given a base scenario (or a Jira ticket) plus a list of refs (PRs, branches, released versions), write one scenario file per ref so the same pytest suite runs across all of them. Use to bisect a regression across releases, validate a fix across multiple PRs, or check feature compatibility between versions. Generates files only — does not install or run them.
+description: Use when running the same test suite across multiple refs, branches, PRs, or releases — bisecting regressions or validating a fix across versions. Generates scenario files only; does not run them.
 allowed-tools: Bash, Read, Write, Grep, Glob
 ---
 
diff --git a/.claude/skills/scenario-run/SKILL.md b/.claude/skills/scenario-run/SKILL.md
index c9a73eef5..c127ecee4 100644
--- a/.claude/skills/scenario-run/SKILL.md
+++ b/.claude/skills/scenario-run/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: scenario-run
-description: Execute the pytest suite declared by a scenarios.yaml against the running instance, then classify the result as "expected outcome", "unexpected outcome", or "unrelated failure" against the scenario's `expected:` / `actual:` fields. Works for bug-repro scenarios, TDD/feature scenarios, and matrix runs. Use after `scenario-up` has confirmed the instance is healthy.
+description: Use after `scenario-up` to run the scenario's test suite and classify results against its expected/actual fields.
 allowed-tools: Bash, Read
 ---
 
diff --git a/.claude/skills/scenario-tear-down/SKILL.md b/.claude/skills/scenario-tear-down/SKILL.md
index 39398c766..0838e9585 100644
--- a/.claude/skills/scenario-tear-down/SKILL.md
+++ b/.claude/skills/scenario-tear-down/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: scenario-tear-down
-description: Stop the services for a scenario's instance and optionally delete the instance directory. Use when the user is done with a reproduction or wants to free ports/disk for a different scenario.
+description: Use when the user is done with a scenario or wants to stop, clean up, or free ports/disk.
 allowed-tools: Bash, Read
 ---
 
diff --git a/.claude/skills/scenario-up/SKILL.md b/.claude/skills/scenario-up/SKILL.md
index 8254dd610..dcf1ea357 100644
--- a/.claude/skills/scenario-up/SKILL.md
+++ b/.claude/skills/scenario-up/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: scenario-up
-description: Provision artifacts, scaffold the instance directory, and start the test environment for a given xtest/scenarios/<id>.yaml. Use after `scenario-from-ticket` (or `scenario-matrix`, or when the user already has a scenario YAML) and wants the environment running.
+description: Use when the user has a scenario YAML and wants the environment started (before running tests).
 allowed-tools: Bash, Read
 ---
 

From 0fbed4a068029f69ffaf5f39f2a80fd11f410906 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 22 May 2026 10:48:59 -0400
Subject: [PATCH 24/64] fixup(scenario-from-ticket): shorten description to
 trigger condition only

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/skills/scenario-from-ticket/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/skills/scenario-from-ticket/SKILL.md b/.claude/skills/scenario-from-ticket/SKILL.md
index 21db97f88..5c8693e8a 100644
--- a/.claude/skills/scenario-from-ticket/SKILL.md
+++ b/.claude/skills/scenario-from-ticket/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: scenario-from-ticket
-description: Pull a Jira ticket of any type (Bug, Story, Task, Spike) into context via `acli jira workitem view` + `acli jira workitem comment list`, then turn it into an xtest/scenarios/<JIRA-KEY>.yaml manifest. Pins platform/KAS/SDKs to a released version (`dist:`), a branch or SHA (`source.ref:`), or the head of a PR — whichever matches the ticket. Optionally drafts xtest/bugs/<jira_key>_test.py when no existing pytest covers the behavior. Use when the user mentions a Jira key like DSPX-1234 (or any [PROJECT]-[NUMBER]) and wants a runnable scenario — reproducing a bug, writing a TDD test for a new feature, or validating behavior at a specific ref.
+description: Use when the user mentions a Jira key ([PROJECT]-[NUMBER]) and wants a scenario — bug repro, TDD test, or behavior validation at a specific ref.
 allowed-tools: Bash, Read, Write, Grep, Glob
 ---
 

From a681c52b80145a5aa5856f13fd87b782554cab02 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Fri, 29 May 2026 17:15:03 -0400
Subject: [PATCH 25/64] feat(.claude/skills): full overhaul + new
 scenario-doctor (DSPX-3302)

Rewrite all seven scenario/instance skills to follow plugin-dev's
skill-development conventions (third-person trigger descriptions,
imperative body voice, progressive disclosure into references/ and
scripts/), and close the friction items surfaced during the
pure-mlkem session:

- instance-status: cross-worktree port + docker-compose probe so
  sibling-worktree services don't go undetected.
- scenario-up: bootstrap-pr-worktree.sh pre-flight for missing
  kas-*.pem / keys / opentdf.yaml on fresh PR worktrees, plus a
  partial-install guard against silent empty SDK arrays in
  installed.json. Documents OTDFCTL_HEADS and PLATFORM_VERSION
  workarounds.
- scenario-run: source-build pytest fallback when installed.json
  is empty, and a new "assertion-stricter-than-implementation"
  classifier bucket for aspirational expectations.
- scenario-from-ticket: auto-pin tickets with linked GitHub PRs to
  source.ref:<headRefOid>; YAML templates extracted to
  references/yaml-templates.md.
- scenario-tear-down: shared-docker probe across worktrees.
- scenario-matrix: dedup workaround note pending DSPX-3417.
- feature-design: lightly retouched, cross-link to scenario-doctor.
- New scenario-doctor skill: diff running-vs-intended state via
  scripts/diff-running-vs-intended.sh; verbose recipes in
  references/probe-recipes.md.

Inline links to DSPX-3415..3419 mark each documented workaround as
temporary so it can be removed when the corresponding CLI fix lands.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .claude/skills/feature-design/SKILL.md        |  22 +--
 .claude/skills/instance-status/SKILL.md       |  78 +++++++--
 .../scripts/cross-worktree-probe.sh           |  57 +++++++
 .claude/skills/scenario-doctor/SKILL.md       |  95 +++++++++++
 .../references/probe-recipes.md               |  93 +++++++++++
 .../scripts/diff-running-vs-intended.sh       | 150 ++++++++++++++++++
 .claude/skills/scenario-from-ticket/SKILL.md  | 106 +++++--------
 .../references/yaml-templates.md              |  96 +++++++++++
 .claude/skills/scenario-matrix/SKILL.md       |  25 ++-
 .claude/skills/scenario-run/SKILL.md          |  85 +++++++---
 .claude/skills/scenario-tear-down/SKILL.md    |  72 ++++++---
 .claude/skills/scenario-up/SKILL.md           | 100 +++++++++---
 .../scripts/bootstrap-pr-worktree.sh          | 131 +++++++++++++++
 13 files changed, 944 insertions(+), 166 deletions(-)
 create mode 100755 .claude/skills/instance-status/scripts/cross-worktree-probe.sh
 create mode 100644 .claude/skills/scenario-doctor/SKILL.md
 create mode 100644 .claude/skills/scenario-doctor/references/probe-recipes.md
 create mode 100755 .claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
 create mode 100644 .claude/skills/scenario-from-ticket/references/yaml-templates.md
 create mode 100755 .claude/skills/scenario-up/scripts/bootstrap-pr-worktree.sh

diff --git a/.claude/skills/feature-design/SKILL.md b/.claude/skills/feature-design/SKILL.md
index bf3854aa6..4e1482e18 100644
--- a/.claude/skills/feature-design/SKILL.md
+++ b/.claude/skills/feature-design/SKILL.md
@@ -1,17 +1,17 @@
 ---
 name: feature-design
-description: Use when a feature or bug fix spans multiple repos (platform + Go/Java/JS SDKs) and you want the cross-repo spec and test artifacts set up in one pass.
+description: This skill should be used when the user asks to "design a cross-repo feature", "set up a feature spec", "draft a feature across platform and SDKs", "design a fix that spans repos", or wants the tests-side artifacts + per-repo todo lists set up in one pass for work that crosses platform + Go/Java/JS SDKs. Hands off to `feature-orchestrate` for the per-repo PR work.
 allowed-tools: Bash, Read, Write, Edit, Grep, Glob, Skill
 ---
 
 # feature-design
 
-You turn a fuzzy "let's build X across the OpenTDF repos" into a concrete bundle of artifacts that pin down the tests-side work first and stage the cross-repo work for handoff to `feature-orchestrate`.
+Turn a fuzzy "let's build X across the OpenTDF repos" into a concrete bundle of artifacts that pin down the tests-side work first and stage the cross-repo work for handoff to `feature-orchestrate`.
 
 Two ideas to internalize before reading the steps:
 
-1. **Tests-side artifacts land first, dormant.** The scenario + draft test + `feature_type` entry merge to `tests/main` as a regular PR. They stay "all skipped" until each SDK opens its own PR adding a `supports <feature>` case to its `cli.sh` source — that PR's CI activates the test for that SDK. This means no cross-PR lockstep coordination; per-repo PRs land async, in any order.
-2. **Propose, don't ask.** Draft a complete spec from the Jira ticket on the first pass and let the user redirect what's wrong in a single revision. Only ask one composite question. If you're missing information you can't fill in (no Jira ticket, ambiguous scope, unclear feature name), bail — don't fabricate.
+1. **Tests-side artifacts land first, dormant.** The scenario + draft test + `feature_type` entry merge to `tests/main` as a regular PR. They stay "all skipped" until each SDK opens its own PR adding a `supports <feature>` case to its `cli.sh` source — that PR's CI activates the test for that SDK. No cross-PR lockstep coordination; per-repo PRs land async, in any order.
+2. **Propose, don't ask.** Draft a complete spec from the Jira ticket on the first pass and let the user redirect what's wrong in a single revision. Only ask one composite question. If information is missing that can't be filled in (no Jira ticket, ambiguous scope, unclear feature name), bail — don't fabricate.
 
 ## Inputs
 
@@ -22,7 +22,7 @@ Two ideas to internalize before reading the steps:
 
 ### Step 1 — Pull the Jira context
 
-If a Jira key was given, run both — `view` takes the key positionally, `comment list` requires `--key`; comments often carry scope refinements that aren't in the description:
+If a Jira key was given, run both — `view` takes the key positionally, `comment list` requires `--key`; comments often carry scope refinements:
 
 ```bash
 acli jira workitem view <JIRA-KEY> --fields '*all' --json
@@ -33,17 +33,17 @@ Extract Issue Type, summary, description, status, and any comments about scope o
 
 ### Step 2 — Propose a complete draft
 
-Draft the full spec body and the per-repo todo lists inline in your reply. Don't ask the user one field at a time — produce a complete first draft they can react to:
+Draft the full spec body and the per-repo todo lists inline in the reply. Don't ask the user one field at a time — produce a complete first draft they can react to:
 
 - **Feature flag name** — snake_case identifier derived from the Jira summary. Becomes the `supports("<name>")` gate string AND the `feature_type` entry in `xtest/tdfs.py`. Validate it's a valid Python identifier and doesn't collide with an existing `feature_type` member.
 - **Touched repos** — default set is `tests, platform, sdk-go, sdk-java, sdk-web`. Trim or expand based on what the ticket says. Pure platform features skip the SDK repos; pure SDK-only features skip platform; `tests` is always present (the dormant scenario + tdfs.py entry has to live there).
-- **Per-repo todo lists** — 2-4 bullets per repo, derived from the description plus each repo's known role:
+- **Per-repo todo lists** — 2–4 bullets per repo:
   - `tests` — register the feature in `feature_type`, author the scenario, draft the test gated on `supports("<feature>")`.
   - `platform` — service-side implementation (KAS path, policy plumbing, etc.) and any env-var handling in the dev harness (e.g. honoring `XT_WITH_<FEATURE>`).
   - `sdk-go` / `sdk-java` / `sdk-web` — encrypt/decrypt path implementation, plus a `supports <feature>` case in that SDK's `cli.sh` source. **Don't pin the version bound in the spec** — the implementing engineer sets the `awk` predicate at PR time, since the bound depends on which release will ship the impl.
 - **Branch name** — `<JIRA-KEY>-<feature-slug>`, the same string across every touched repo so `feature-orchestrate` (and the user) can find each repo's PR by branch alone.
 
-Present the draft, then ask exactly one composite question: "Anything to redirect — feature name, touched repos, todo items, branch?" Apply edits in a single revision rather than turn-by-turn. The user can always drop into plain chat if they want to think out loud — just answer them and re-invoke this skill once the design firms up.
+Present the draft, then ask exactly one composite question: "Anything to redirect — feature name, touched repos, todo items, branch?" Apply edits in a single revision rather than turn-by-turn. The user can always drop into plain chat if they want to think out loud — answer normally and re-invoke this skill once the design firms up.
 
 If no Jira key was given AND the user's description doesn't pin down a clear scope (feature flag name, touched repos, intended behavior), bail rather than fabricate:
 
@@ -93,7 +93,7 @@ In this order, so each step's output feeds the next:
 
 1. **Add the feature flag to `xtest/tdfs.py`**. Find the `feature_type` Literal alias near the top of the file. Insert the new entry alphabetically. Don't touch any `cli.sh` files — `supports <feature>` cases land per-SDK in their own PRs.
 
-2. **Invoke `scenario-from-ticket`** via the Skill tool (`skill: scenario-from-ticket`, `args: <JIRA-KEY>`). It runs its Story/Task branch and produces the scenario + draft test gated on `supports("<feature>")` — pinning the feature-introducing components to `main` via `source.ref:`. If no Jira key was given, draft the scenario directly using the same shape (`xtest/scenarios/<feature-name>.yaml`).
+2. **Invoke `scenario-from-ticket`** via the Skill tool (`skill: scenario-from-ticket`, `args: <JIRA-KEY>`). It runs its Story/Task branch and produces the scenario + draft test gated on `supports("<feature>")`. If no Jira key was given, draft the scenario directly using the same shape (`xtest/scenarios/<feature-name>.yaml`).
 
 3. **Validate the scenario**:
 
@@ -108,11 +108,11 @@ One block summarizing:
 - The spec path (`xtest/features/<feature-name>.yaml`).
 - The scenario + draft test paths.
 - The line(s) added to `xtest/tdfs.py`.
-- A one-liner suggesting the next step: `feature-orchestrate xtest/features/<feature-name>.yaml`.
+- A one-liner suggesting next steps: `feature-orchestrate xtest/features/<feature-name>.yaml` (for per-repo PR work), or `scenario-up xtest/scenarios/<id>.yaml` + `scenario-doctor <id>` (to bring the dormant scenario up against `main` and confirm "all skipped" baseline before SDK work starts).
 
 ## Notes
 
 - This skill produces **tests-side artifacts only**. It does NOT create branches in other repos, does NOT open PRs, does NOT install platform/SDK builds. That's `feature-orchestrate`'s job.
 - Bugs that span repos use the same shape — pass the Bug ticket key and `scenario-from-ticket`'s Bug branch fills `expected:` / `actual:` from the reproduction prose. The cross-repo gating still works: tests land dormant, each per-repo PR activates them by adding the supports case as part of the fix.
-- For an existing spec being revised, read it first and propose a diff rather than a full rewrite. The tests-side artifacts (scenario, tdfs.py entry) usually shouldn't be regenerated — just edit them surgically.
+- For an existing spec being revised, read it first and propose a diff rather than a full rewrite. The tests-side artifacts (scenario, tdfs.py entry) usually shouldn't be regenerated — edit them surgically.
 - If the user starts the conversation by describing the feature in plain chat rather than invoking this skill, answer normally — re-invoke the skill once the scope firms up. Don't gatekeep.
diff --git a/.claude/skills/instance-status/SKILL.md b/.claude/skills/instance-status/SKILL.md
index cef888d2a..9467c2b40 100644
--- a/.claude/skills/instance-status/SKILL.md
+++ b/.claude/skills/instance-status/SKILL.md
@@ -1,36 +1,80 @@
 ---
 name: instance-status
-description: Use when the user asks what's running, or before starting a scenario to check for port collisions.
+description: This skill should be used when the user asks "what's running", "check ports", "show instance status", "list test instances", "are any services up", or before invoking `scenario-up` to detect port collisions (including from sibling git worktrees). For deeper "does the running env match what the scenario yaml says" verification, defer to `scenario-doctor` instead.
 allowed-tools: Bash, Read
 ---
 
 # instance-status
 
-You give the user a snapshot of all test instances in this checkout: what's defined, what's running, and whether each service is healthy.
+Report a snapshot of test environment state: which instances are defined in this worktree, what is actually listening on the conventional ports (regardless of which worktree owns it), and whether each service is healthy. Surface port collisions before they bite `scenario-up`.
 
 ## Process
 
-1. **List instances on disk**:
+### Step 0 — Cross-worktree probe (always first)
 
-   ```bash
-   uv run otdf-local instance ls --json
-   ```
+`otdf-local instance ls` is scoped to the current worktree's `tests/instances/`. Sibling worktrees' running services are invisible to that listing but very much listening on the host's ports. Probe the host directly:
 
-   Each entry includes `name`, `platform` version, `ports_base`, and the `kas:` keys. Flag any two instances that share a `ports_base` — they cannot run concurrently.
+```bash
+bash ${CLAUDE_PLUGIN_ROOT:-.}/skills/instance-status/scripts/cross-worktree-probe.sh
+```
 
-2. **For each instance**, check service status:
+Output is tab-separated, one row per listener:
 
-   ```bash
-   uv run otdf-local --instance <name> status --json
-   ```
+```
+port   proto  pid    cwd                                        kind
+8080   tcp    28656  /Users/.../reproducing-things/...           platform
+8585   tcp    28684  /Users/.../reproducing-things/...           kas
+compose docker -    main                                         compose-project
+```
 
-   Each service reports `running`, `healthy`, and the bound port. Don't run all instances in parallel — iterate; a status query is cheap.
+Carry forward two facts into the rest of the report:
+1. Which of the conventional ports (`8080`, `8181..8686`, `5432`, `8888`) are occupied.
+2. The owning `cwd` for each — when it differs from the current worktree, label the line as **foreign** in the final summary so the user knows to tear that down before re-using the port.
 
-3. **Summarize**:
-   - A short table per instance: service → port → state.
-   - Flag any unhealthy service with the path to its log (e.g. `tests/instances/<name>/logs/kas-alpha.log`).
-   - Mention port conflicts if two instances would collide on `ports.base`.
+### Step 1 — List instances on disk
+
+```bash
+uv run otdf-local instance ls --json
+```
+
+Each entry includes `name`, `platform` version, `ports_base`, and the `kas:` keys. Two checks:
+- Flag any two local instances that share a `ports_base` — they cannot run concurrently.
+- Note: this listing is **worktree-scoped**. The cross-worktree probe from Step 0 is the source of truth for "what's actually using port X."
+
+### Step 2 — Per-instance status
+
+For each local instance from Step 1:
+
+```bash
+uv run otdf-local --instance <name> status --json
+```
+
+Each service reports `running`, `healthy`, and the bound port. Run sequentially (a status query is cheap; parallel adds nothing). Cross-reference each "running" entry with Step 0's table — if the port shows `kind=platform` but the owning `cwd` is a sibling worktree, the local instance's status reading is misleading (it's reporting on someone else's binary).
+
+### Step 3 — Summarize
+
+Compose the reply in this order:
+1. **Cross-worktree listeners** — the Step 0 table, with each foreign row labeled. Skip if no ports are occupied.
+2. **Local instances** — one short block per instance: service → port → state (running/healthy). Mark each row's port as `local` or `foreign` based on Step 0's owner.
+3. **Port-base collisions** — any pair of local instances with the same `ports_base`, recommending a re-init: `uv run otdf-local instance init <name> --from-scenario <path> --ports-base <new>`.
+4. **Unhealthy rows** — each with the path to its log (e.g. `tests/instances/<name>/logs/kas-alpha.log`).
+
+Skip empty sections rather than print "(none)".
 
 ## When ports collide
 
-`otdf-local instance init` warns about this at creation time but does not enforce it. If you see two instances with the same `ports_base`, recommend the user reassign one via `uv run otdf-local instance init <name> --from-scenario <path> --ports-base <new>` (or hand-edit the `instance.yaml`).
+If Step 0 shows a foreign listener on a port the user is about to use, two paths:
+- Tear down the foreign instance first. Find the owning worktree from the `cwd` column; cd there and run `OTDF_LOCAL_INSTANCE_NAME=<name> uv run otdf-local down`.
+- Or pick a different ports base for the new instance: `uv run otdf-local instance init <name> --from-scenario <path> --ports-base 9080` (or any free base).
+
+If `otdf-local instance init` warns about a local collision at creation time, it doesn't enforce it; re-running with `--ports-base <new>` is the fix.
+
+## What this skill does NOT do
+
+For the deeper question "is the binary serving port X actually the one my scenario YAML pinned?", use `scenario-doctor` — that skill diffs the running service's `.version` sidecar against the instance's expected pin. `instance-status` reports *what's listening*, not *whether it's the right thing*.
+
+## Additional Resources
+
+### Script
+
+- **`scripts/cross-worktree-probe.sh`** — surveys conventional ports + docker compose projects across all worktrees on this host. Always run first in Step 0. Tab-separated stdout (header on line 1).
diff --git a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
new file mode 100755
index 000000000..baed227f9
--- /dev/null
+++ b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# cross-worktree-probe.sh — surface listeners on opentdf test ports across ALL worktrees.
+#
+# `otdf-local instance ls` is scoped to one worktree's tests/instances/; sibling
+# worktrees' running services are invisible to it. This script probes the host
+# directly so the agent can detect cross-worktree port collisions before
+# `scenario-up` (or explain why a port appears "free" from one CLI but isn't).
+#
+# Output: tab-separated, one record per line, header on first line.
+# Columns: port  proto  pid  cwd  kind
+#   kind ∈ { platform | kas | docker-keycloak | docker-postgres | unknown }
+
+set -u
+
+PORTS=(8080 8181 8282 8383 8484 8585 8686 5432 8888)
+
+printf 'port\tproto\tpid\tcwd\tkind\n'
+
+for port in "${PORTS[@]}"; do
+  # -F to use parseable format; -n -P to skip name resolution (faster)
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    pid="$(awk '{print $2}' <<<"$line")"
+    [[ -z "$pid" || "$pid" == "PID" ]] && continue
+
+    cwd="$(lsof -p "$pid" -d cwd -Fn 2>/dev/null | awk '/^n/ { sub(/^n/,""); print; exit }')"
+    cwd="${cwd:-?}"
+
+    cmd="$(ps -o command= -p "$pid" 2>/dev/null | head -c 200)"
+    case "$port" in
+      8080) kind=platform ;;
+      8181|8282|8383|8484|8585|8686) kind=kas ;;
+      8888) kind=docker-keycloak ;;
+      5432) kind=docker-postgres ;;
+      *)    kind=unknown ;;
+    esac
+    # Refine kind if process command says otherwise (e.g. a misbound port).
+    case "$cmd" in
+      *"/service "*|*"/service start"*) kind=platform ;;
+      *opentdf-kas*|*"kas start"*) kind=kas ;;
+    esac
+
+    printf '%s\ttcp\t%s\t%s\t%s\n' "$port" "$pid" "$cwd" "$kind"
+  done < <(lsof -nP -iTCP:"$port" -sTCP:LISTEN 2>/dev/null | tail -n +2)
+done
+
+# Docker compose projects sharing the host docker daemon — names like
+# `<project>-keycloak-1`, `<project>-opentdfdb-1`. The project is whatever
+# directory `docker compose` was invoked from (typically a worktree's
+# xtest/platform/src/<ref>/ directory).
+docker ps --format '{{.Names}}' 2>/dev/null | while IFS= read -r name; do
+  [[ -z "$name" ]] && continue
+  case "$name" in
+    *-keycloak-*)  printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
+    *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
+  esac
+done | sort -u
diff --git a/.claude/skills/scenario-doctor/SKILL.md b/.claude/skills/scenario-doctor/SKILL.md
new file mode 100644
index 000000000..f55bd58f3
--- /dev/null
+++ b/.claude/skills/scenario-doctor/SKILL.md
@@ -0,0 +1,95 @@
+---
+name: scenario-doctor
+description: This skill should be used when the user asks to "verify my instance", "doctor my scenario", "is my environment healthy", "does the running platform match the scenario", or to diagnose a flaky test run by confirming the expected binaries / keys / health are actually live. Cross-checks running state against `tests/instances/<name>/instance.yaml`.
+allowed-tools: Bash, Read
+---
+
+# scenario-doctor
+
+Cross-check what an instance's `instance.yaml` *intends* against what is *actually* running, and produce a verdict the user can act on. Most "the test failed for a weird reason" sessions trace back to a drift here — the wrong binary serving the port, stale keys in the worktree, an extra service from a sibling worktree squatting on a port, or a process owned by a different worktree's `otdf-local`.
+
+## Inputs
+
+- Instance name (typically the lowercased Jira key, e.g. `dspx-3302`). If a scenario YAML path is provided instead, read its `instance.metadata.name` and proceed.
+
+## Process
+
+### Step 1 — Run the diff script
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT:-.}/skills/scenario-doctor/scripts/diff-running-vs-intended.sh <name>
+```
+
+Output is tab-separated, one row per service:
+
+```
+service   port  expected_sha  actual_sha  health  status
+platform  8080  08ab3a0aef27  08ab3a0aef27  200    MATCH
+km1       8585  08ab3a0aef27  -             down   NOT-RUNNING
+alpha     8181  v090...       a1b2c3d4...   200    WRONG-BINARY
+```
+
+`status` enumerates:
+- `MATCH` — expected ref matches the running binary's `.version` sha, health is 200.
+- `WRONG-BINARY` — service is up but serving from a different ref than the instance pins. Often means a sibling worktree's environment is shadowing this one's expected binary.
+- `NOT-RUNNING` — port is empty; `otdf-local --instance <name> up` (or `restart <service>`) is needed.
+- `EXTRA` — port is occupied by a service the instance didn't declare. Usually a leftover from another instance/worktree.
+- `NO-PIN` — instance manifest didn't pin this service (skip).
+
+### Step 2 — Verify seed files
+
+For each unique worktree referenced in the diff output (parse the `expected_sha` rows back to `.version` sidecars), invoke the bootstrap script in dry-run inspection mode — re-using `scenario-up`'s probe so the file checks stay consistent:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT:-.}/skills/scenario-up/scripts/bootstrap-pr-worktree.sh <scenario-path>
+```
+
+Treat any `state=empty-dir` or `state=missing action=manual-required` row as a real problem worth surfacing — those are the silent-failure shapes (Docker bind-mount stubs, ungenerated dev keys).
+
+### Step 3 — Assign a verdict
+
+Roll up Steps 1–2 into one of three colors. Lead the reply with the verdict; users scan for this.
+
+- **GREEN** — every declared service is `MATCH` + 200, no `EXTRA` rows, every seed file `ok`. Nothing for the user to do.
+- **YELLOW** — at least one `WRONG-BINARY`, `EXTRA`, or `empty-dir`/`missing` row, but the instance is *running*. Tests may pass or fail unpredictably until the drift is resolved.
+- **RED** — at least one declared service is `NOT-RUNNING`. Tests cannot succeed; recommend `otdf-local --instance <name> up` (fresh start) or per-service `restart`.
+
+### Step 4 — Per-row remedy
+
+For each non-`MATCH` row, emit a one-line remedy alongside the diff table:
+
+| Status | Remedy |
+|---|---|
+| `NOT-RUNNING` | `otdf-local --instance <name> up` (full) or `restart <service>` (single service) |
+| `WRONG-BINARY` | Identify owning PID's worktree via `lsof -p <pid> -d cwd`. If sibling worktree: tear that down first (`OTDF_LOCAL_INSTANCE_NAME=<other> otdf-local down`). If same worktree, stale binary: `otdf-sdk-mgr install tip --ref <expected-ref> platform` then restart. |
+| `EXTRA` | Confirm the PID and its cwd. Stop owning instance or kill the stale PID. |
+| `empty-dir` / `missing` | Re-run `bootstrap-pr-worktree.sh` (Phase B of `scenario-up`) or hand-run `bash .github/scripts/init-temp-keys.sh` in the worktree. |
+
+### Step 5 — Output
+
+Compose the reply in this order: verdict line, diff table (Step 1 output, lightly formatted), seed-file table (Step 2 output, only rows that aren't `ok`), per-row remedy bullets. Skip empty sections rather than print "(none)" — agents pattern-match on what's present.
+
+## When this skill triggers
+
+After any of:
+- A surprising pytest result (skip when expected to pass, or pass when expected to skip-then-fail).
+- The user asking "what's running" with the implication that they suspect drift, not a simple `instance ls` query (that's `instance-status`'s job).
+- Returning to a long-lived branch where the running environment might be stale.
+
+For the simpler "what's defined / what's listening here" question without the diff-against-intent angle, defer to `instance-status`.
+
+## Limits
+
+- The script depends on the `.version` sidecar that `otdf-sdk-mgr install platform` writes. Binaries placed under `xtest/platform/dist/` by other means won't be diffable; they show as `expected_sha=?`.
+- `yq` is preferred for parsing `instance.yaml`; the script falls back to grep when `yq` isn't installed. Coverage of the fallback is narrower — install `yq` for accurate KAS-list extraction in unusual manifests.
+- Cross-worktree owner detection uses `lsof -p <pid> -d cwd`. Containers running services (rare today) wouldn't surface that way; the verdict would still flag the port collision via `EXTRA`, just without an owning-worktree label.
+
+## Additional Resources
+
+### Script
+
+- **`scripts/diff-running-vs-intended.sh`** — automates Step 1's expected-vs-actual diff. Takes one positional argument: the instance name. Tab-separated stdout.
+
+### Reference files
+
+- **`references/probe-recipes.md`** — verbose shell snippets for ad-hoc inspection: resolving a PID to its worktree, comparing `.version` sidecars by hand, detecting Docker-created empty-dir stubs, listing compose-project owners. Read this when the script's output is ambiguous or the user wants the underlying mechanics.
diff --git a/.claude/skills/scenario-doctor/references/probe-recipes.md b/.claude/skills/scenario-doctor/references/probe-recipes.md
new file mode 100644
index 000000000..bcb5440b6
--- /dev/null
+++ b/.claude/skills/scenario-doctor/references/probe-recipes.md
@@ -0,0 +1,93 @@
+# Probe recipes
+
+Shell snippets the `scenario-doctor` skill uses (or recommends users run by hand) to inspect running services and compare against `instance.yaml` expectations. `scripts/diff-running-vs-intended.sh` automates the common path; reach for these recipes when the script's output needs deeper investigation or the agent has to answer an ad-hoc "what's actually running on port X?" question.
+
+## Identify what's listening on the conventional ports
+
+```bash
+lsof -nP -iTCP:8080,8181,8282,8383,8484,8585,8686,5432,8888 -sTCP:LISTEN
+```
+
+Reads as `COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME`. The PID is what to chase next.
+
+## Resolve a PID to the binary path and its source worktree
+
+```bash
+ps -o command= -p <PID>
+# → /Users/.../tests/xtest/platform/dist/<slug>/service start --config-file …
+```
+
+The binary lives at `…/dist/<slug>/service`. Its sibling `.version` file records the source worktree and git SHA that built it:
+
+```bash
+cat "$(dirname "$(ps -o command= -p <PID> | awk '{print $1}')")/.version"
+# ref=refs/pull/3537/head
+# sha=08ab3a0aef…
+# worktree=/Users/.../DSPX-3302-02-platform-installer/tests/xtest/platform/src/refs--pull--3537--head
+```
+
+Whatever the `worktree=` line says is the directory the service binary loads keys / templates relative to — useful when investigating "platform started but says key X not found."
+
+## Resolve a PID to its cwd (often a different worktree than the agent)
+
+```bash
+lsof -p <PID> -d cwd -Fn | awk '/^n/ { sub(/^n/,""); print; exit }'
+```
+
+A PID's cwd reveals which worktree initiated the service. Use this to spot cases where the agent thinks it's in worktree A but a sibling worktree B owns the running binary.
+
+## Compare expected ref to actual ref for an instance
+
+```bash
+inst="tests/instances/<name>/instance.yaml"
+yq -r '.platform.source.ref // .platform.dist' "$inst"       # expected
+ps -o command= -p "$(lsof -nP -iTCP:8080 -sTCP:LISTEN | awk 'NR>1 {print $2; exit}')" \
+  | awk '{print $1}' | xargs -I{} cat "$(dirname {})/.version"  # actual
+```
+
+Diff the two. Mismatch → either the instance is being served by a stale binary or by a binary from a different worktree.
+
+## Health pings
+
+```bash
+curl -fsS http://localhost:8080/healthz   # platform
+curl -fsS http://localhost:8585/healthz   # km1
+```
+
+Returns `{"status":"SERVING"}` (HTTP 200) when healthy. Anything else is a real failure — check the corresponding log under `tests/instances/<name>/logs/`.
+
+## Confirm seed files exist (not Docker-created empty dirs)
+
+```bash
+worktree="…/xtest/platform/src/<slug>"
+for f in kas-private.pem kas-cert.pem kas-ec-private.pem kas-ec-cert.pem \
+         keys/ca.jks keys/localhost.crt keys/localhost.key opentdf.yaml; do
+  if [[ -f "$worktree/$f" ]]; then
+    printf 'ok\t%s\n' "$f"
+  elif [[ -d "$worktree/$f" ]]; then
+    printf 'empty-dir\t%s\n' "$f"  # Docker bind-mount left a stub directory
+  else
+    printf 'missing\t%s\n' "$f"
+  fi
+done
+```
+
+`empty-dir` is the silent-failure shape: Docker auto-created the path as a directory because the source file didn't exist when compose first ran. Removing the stub and re-bootstrapping (via `scripts/bootstrap-pr-worktree.sh` or `init-temp-keys.sh`) is the fix.
+
+## Detect cross-worktree docker compose sharing
+
+```bash
+docker ps --format '{{.Names}}' | grep -E -- '-keycloak-|-opentdfdb-' \
+  | sed -E 's/-(keycloak|opentdfdb)-[0-9]+$//' | sort -u
+```
+
+Lists every compose-project name currently sharing the docker daemon. Each project is typically named after the directory `docker compose` was invoked from (i.e. a worktree's `xtest/platform/src/<slug>/`). When multiple projects appear, `otdf-local --instance X down` will *not* stop docker — another instance is still using it.
+
+## Kill a stale platform/KAS process (use with care)
+
+```bash
+pkill -9 -f "/dist/<slug>/service start"     # platform
+pkill -9 -f "/dist/<slug>/service kas start" # KAS
+```
+
+Prefer `otdf-local --instance <name> down` when possible; `pkill` is the escape hatch when the instance owning the process doesn't match the worktree the agent is in (so `otdf-local` won't manage it cleanly).
diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
new file mode 100755
index 000000000..b7ff9f118
--- /dev/null
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# diff-running-vs-intended.sh — verify that running services match what an
+# instance.yaml claims they should be.
+#
+# Usage: diff-running-vs-intended.sh <instance-name>
+#
+# Walks the per-instance manifest at tests/instances/<name>/instance.yaml,
+# resolves each pin (dist:/source.ref:) to its expected dist directory and
+# git SHA via the .version sidecar, then compares against what's actually
+# listening on the conventional ports.
+#
+# Output: tab-separated, header on first line.
+# Columns: service  port  expected_sha  actual_sha  health  status
+#   status ∈ { MATCH | WRONG-BINARY | NOT-RUNNING | EXTRA | NO-PIN }
+#   health ∈ { 200 | <http-code> | down | - }
+
+set -u
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: $(basename "$0") <instance-name>" >&2
+  exit 2
+fi
+
+name="$1"
+
+# Resolve repo root by walking up from CWD until we find tests/instances/.
+dir="$PWD"
+while [[ "$dir" != "/" && ! -d "$dir/tests/instances" && ! -d "$dir/instances" ]]; do
+  dir="$(dirname "$dir")"
+done
+[[ -d "$dir/tests/instances" ]] && INST_ROOT="$dir/tests/instances"
+[[ -d "$dir/instances" ]] && INST_ROOT="$dir/instances"
+: "${INST_ROOT:?could not locate tests/instances/ above $PWD}"
+
+inst="$INST_ROOT/$name/instance.yaml"
+[[ -f "$inst" ]] || { echo "no instance.yaml at $inst" >&2; exit 2; }
+
+PLATFORM_DIST="${INST_ROOT%/instances}/xtest/platform/dist"
+
+# Port map (matches otdf-local's Ports defaults).
+declare -A PORT_OF=(
+  [platform]=8080
+  [alpha]=8181
+  [beta]=8282
+  [gamma]=8383
+  [delta]=8484
+  [km1]=8585
+  [km2]=8686
+)
+
+# Helper: resolve a pin (ref or dist) to expected_sha by reading .version.
+expected_sha_for() {
+  local pin="$1"  # could be a ref like 'main' or 'pr:3537', or a dist slug
+  local slug
+  for cand in "$PLATFORM_DIST"/*/; do
+    [[ -f "$cand/.version" ]] || continue
+    if grep -Fq "ref=$pin" "$cand/.version" \
+      || grep -Fq "ref=refs/pull/${pin#pr:}/head" "$cand/.version" \
+      || [[ "$(basename "${cand%/}")" == "$pin" ]]; then
+      awk -F= '/^sha=/ {print substr($2,1,12); exit}' "$cand/.version"
+      return
+    fi
+  done
+  echo "?"
+}
+
+# Helper: actual_sha by inspecting the running binary at $port.
+actual_sha_for_port() {
+  local port="$1"
+  local pid binary version
+  pid="$(lsof -nP -iTCP:"$port" -sTCP:LISTEN 2>/dev/null | awk 'NR>1 {print $2; exit}')"
+  [[ -z "$pid" ]] && { echo ""; return; }
+  binary="$(ps -o command= -p "$pid" 2>/dev/null | awk '{print $1}')"
+  [[ -f "$binary" ]] || { echo "?"; return; }
+  version="$(dirname "$binary")/.version"
+  [[ -f "$version" ]] && awk -F= '/^sha=/ {print substr($2,1,12); exit}' "$version" || echo "?"
+}
+
+# Helper: http health code.
+health_of() {
+  local port="$1"
+  curl -fsS -o /dev/null -w '%{http_code}' "http://localhost:$port/healthz" 2>/dev/null || echo down
+}
+
+# Extract pins from instance.yaml. yq optional; fall back to grep.
+get_pin() {
+  local field="$1"   # e.g. .platform OR .kas.km1
+  if command -v yq >/dev/null 2>&1; then
+    yq -r "($field.source.ref? // $field.dist? // \"\")" "$inst"
+  else
+    # Crude fallback: pull the first ref|dist under the section name.
+    awk -v sec="${field#.}" '
+      $0 ~ "^"sec":" {f=1; next}
+      f && /^[^[:space:]]/ {f=0}
+      f && /(ref|dist):/ {gsub(/[",{}]/,""); for(i=1;i<=NF;i++) if($i ~ /^(ref|dist):/) {print $(i+1); exit}}
+    ' "$inst"
+  fi
+}
+
+printf 'service\tport\texpected_sha\tactual_sha\thealth\tstatus\n'
+
+# Platform first.
+pin="$(get_pin .platform)"
+exp="$(expected_sha_for "$pin")"
+act="$(actual_sha_for_port 8080)"
+hc="$(health_of 8080)"
+if [[ -z "$pin" ]]; then status=NO-PIN
+elif [[ -z "$act" ]]; then status=NOT-RUNNING
+elif [[ "$act" == "$exp" ]]; then status=MATCH
+else status=WRONG-BINARY; fi
+printf 'platform\t8080\t%s\t%s\t%s\t%s\n' "${exp:-?}" "${act:--}" "$hc" "$status"
+
+# KAS instances declared in the manifest. Build the list either via yq or
+# the grep fallback.
+kas_names=()
+if command -v yq >/dev/null 2>&1; then
+  while IFS= read -r n; do kas_names+=("$n"); done < <(yq -r '.kas | keys[]' "$inst")
+else
+  while IFS= read -r n; do kas_names+=("$n"); done < <(
+    awk '/^kas:/{f=1;next} f && /^[a-z0-9_-]+:/{gsub(":",""); print $1} f && /^[^[:space:]]/{f=0}' "$inst"
+  )
+fi
+
+for kas in "${kas_names[@]}"; do
+  port="${PORT_OF[$kas]:-?}"
+  pin="$(get_pin ".kas.$kas")"
+  exp="$(expected_sha_for "$pin")"
+  act="$(actual_sha_for_port "$port")"
+  hc="$([[ "$port" != "?" ]] && health_of "$port" || echo -)"
+  if [[ -z "$pin" ]]; then status=NO-PIN
+  elif [[ -z "$act" ]]; then status=NOT-RUNNING
+  elif [[ "$act" == "$exp" ]]; then status=MATCH
+  else status=WRONG-BINARY; fi
+  printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$kas" "$port" "${exp:-?}" "${act:--}" "$hc" "$status"
+done
+
+# Detect EXTRA services: any port in PORT_OF that's listening but wasn't
+# declared in instance.yaml.
+declared_ports=(8080)
+for k in "${kas_names[@]}"; do declared_ports+=("${PORT_OF[$k]:-0}"); done
+for svc in "${!PORT_OF[@]}"; do
+  port="${PORT_OF[$svc]}"
+  in_declared=0
+  for d in "${declared_ports[@]}"; do [[ "$d" == "$port" ]] && in_declared=1 && break; done
+  [[ "$in_declared" == 1 ]] && continue
+  act="$(actual_sha_for_port "$port")"
+  [[ -z "$act" ]] && continue
+  hc="$(health_of "$port")"
+  printf '%s\t%s\t-\t%s\t%s\tEXTRA\n' "$svc" "$port" "$act" "$hc"
+done
diff --git a/.claude/skills/scenario-from-ticket/SKILL.md b/.claude/skills/scenario-from-ticket/SKILL.md
index 5c8693e8a..5743e5f6f 100644
--- a/.claude/skills/scenario-from-ticket/SKILL.md
+++ b/.claude/skills/scenario-from-ticket/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: scenario-from-ticket
-description: Use when the user mentions a Jira key ([PROJECT]-[NUMBER]) and wants a scenario — bug repro, TDD test, or behavior validation at a specific ref.
+description: This skill should be used when the user mentions a Jira key (e.g. "DSPX-3302") and asks to "create a scenario", "write a repro from the ticket", "make a TDD scenario", "draft a test for this bug", or otherwise turn a ticket into a `xtest/scenarios/<id>.yaml` manifest plus (optionally) a draft pytest. Handles Bugs, Stories/Tasks (TDD), and Spikes via Issue Type.
 allowed-tools: Bash, Read, Write, Grep, Glob
 ---
 
 # scenario-from-ticket
 
-You produce a `xtest/scenarios/<jira-key-lowercased>.yaml` manifest from a Jira ticket. The same skill handles bugs, features (TDD), and exploratory work — the *Issue Type* field on the ticket selects which way the rest of this skill behaves.
+Produce a `xtest/scenarios/<jira-key-lowercased>.yaml` manifest from a Jira ticket. The same skill handles bugs, features (TDD), and exploratory work — the *Issue Type* field on the ticket selects which way the rest of the skill behaves.
 
 Two artifacts:
 
@@ -17,7 +17,7 @@ The Jira key also becomes the working **branch name** (`<JIRA-KEY>-repro` for Bu
 
 ## Step 1 — Pull the Jira ticket into context
 
-**Always run BOTH commands** — exactly as shown; the two subcommands take the key differently (`view` is positional, `comment list` requires `--key`). Don't skip the comment list — comments often carry the most recent reproduction status, "what changed" notes, or "fixed by PR #N" pointers that aren't in the original description:
+Run **both** commands — they take the key differently (`view` is positional, `comment list` requires `--key`). Don't skip the comment list; comments often carry the most recent reproduction status, "what changed" notes, or "fixed by PR #N" pointers that aren't in the original description:
 
 ```bash
 acli jira workitem view <JIRA-KEY> --fields '*all' --json
@@ -31,11 +31,24 @@ From the JSON output of the first command, extract:
 - **Description** — version numbers, KAS topology, container types, feature flags, acceptance criteria typically live here.
 - **Status** — Backlog / In Progress / Done affects whether the scenario is forward-looking (TDD on Backlog) or retroactive (regression gate on Done).
 
-From the comments, pull any "tested at version X" / "reproduces on platform Y" / "fixed by PR #N" annotations into your mental model.
+From the comments, pull any "tested at version X" / "reproduces on platform Y" / "fixed by PR #N" annotations into context.
 
-If the ticket references attached logs, screenshots, or linked PRs, list them via `acli jira workitem attachment list <JIRA-KEY>` and `acli jira workitem link list <JIRA-KEY>` and call them out in your reply.
+If the ticket references attached logs, screenshots, or linked PRs, list them:
 
-**Permitted Jira writes**: only `acli jira workitem comment create <JIRA-KEY> ...` (to post a reproduction-status update if the user asks). Everything else — `edit`, `transition`, `assign`, `archive`, `delete`, `link create`, `watcher add` — is explicitly disallowed by the plugin's permissions; if the user wants those actions, instruct them to run the command themselves.
+```bash
+acli jira workitem attachment list <JIRA-KEY>
+acli jira workitem link list <JIRA-KEY>
+```
+
+**Linked-PR auto-pin.** When `link list` returns a PR URL (e.g. `https://github.com/opentdf/platform/pull/3537`), resolve it immediately and prefer it over the headless default `dist: lts`:
+
+```bash
+gh pr view <N> --repo <owner/repo> --json number,headRefName,headRefOid
+```
+
+Use the 40-char `headRefOid` as `source.ref:` for the platform/KAS pin. Branch names move on every push; SHAs don't. Record the branch name in `metadata.title` for human readability. See `references/yaml-templates.md` → "PR pin via Jira link" for the full template.
+
+**Permitted Jira writes**: only `acli jira workitem comment create <JIRA-KEY> ...` (to post a reproduction-status update if the user asks). Everything else — `edit`, `transition`, `assign`, `archive`, `delete`, `link create`, `watcher add` — is explicitly disallowed by the plugin's permissions; if the user wants those actions, instruct them to run the command.
 
 ## Step 2 — Branch on Issue Type
 
@@ -47,23 +60,19 @@ The ticket describes a behavior that should work but doesn't.
 - `actual:` — what actually happens, including the exact error message if the ticket quotes one.
 - Pin platform / KAS / SDKs to the **versions where the bug reproduces**. Usually `dist:` against a released version. Mixed-version topologies (e.g. platform `v0.9.0` + km1 `v0.9.0-rc.2`) are common and the schema supports them.
 
-If the description doesn't name versions, ask the user. (A headless agent has no user — in that case default to `dist: lts` everywhere and call out the assumption in `actual:`.)
+If the description doesn't name versions: prefer a linked PR (from Step 1) if any; otherwise ask the user. A headless agent with no PR and no version pin defaults to `dist: lts` and calls out the assumption in `actual:`.
 
 ### Story / Task (feature work, TDD-style)
 
-The ticket describes a behavior the user wants to *add*. The scenario you produce is a forward-looking regression gate, not a bug reproducer.
+The ticket describes a behavior the user wants to *add*. The scenario is a forward-looking regression gate, not a bug reproducer.
 
-- `expected:` — the new behavior the feature should provide, paraphrased from acceptance criteria.
-- `actual:` — the current state, e.g. "feature not implemented; tests skip via `<SDK>.supports('<feature>')` until the supports entry lands." The scenario's `actual:` is what `scenario-run`'s "expected outcome" classifier compares against: a real failure means progress was made; a uniform skip means the prereq SDK plumbing is still pending.
-- Pin platform / KAS / SDKs to the **ref where the feature will land**:
-  - HEAD of mainline: `platform: { source: { ref: main } }`, `sdks.<lang>.version: main`.
-  - Feature branch: `platform: { source: { ref: feature/ecdsa-binding } }`.
-  - Draft PR under review: resolve to its head SHA with `gh pr view <N> --json headRefOid` and pin `platform: { source: { ref: <40-char-SHA> } }`. SHAs are reproducible; branch names move every push.
-- Only pin the component(s) the feature actually touches. Leave the rest on `lts` / `stable`.
+- `expected:` — the new behavior, paraphrased from acceptance criteria.
+- `actual:` — current state, e.g. "feature not implemented; tests skip via `<SDK>.supports('<feature>')` until the supports entry lands." `scenario-run`'s "expected outcome" classifier compares against this — a real failure means progress; a uniform skip means the prereq SDK plumbing is still pending.
+- Pin platform / KAS / SDKs to the **ref where the feature will land**: linked PR (from Step 1) if any, else HEAD of mainline (`source: { ref: main }`), else a feature branch the user names. Only pin components the feature actually touches; leave the rest on `lts` / `stable`.
 
 ### Spike / unclear
 
-The ticket asks an open question or lacks enough concrete behavior to encode. Don't fabricate a scenario. Emit:
+The ticket asks an open question or lacks enough concrete behavior to encode. Don't fabricate. Emit:
 
 ```
 <JIRA-KEY> is a Spike (or has no specific behavior / version pins yet). Add either:
@@ -78,7 +87,7 @@ The ticket asks an open question or lacks enough concrete behavior to encode. Do
 
 - `metadata.id = <jira-key-lowercased>` — e.g. `DSPX-3302` → `dspx-3302`.
 - Scenario file path: `xtest/scenarios/<jira-key-lowercased>.yaml`.
-- If you need a new git branch, propose `<JIRA-KEY>-repro` for Bugs and `<JIRA-KEY>-tdd` for Stories/Tasks; let the user confirm before switching.
+- If a new git branch is needed, propose `<JIRA-KEY>-repro` for Bugs and `<JIRA-KEY>-tdd` for Stories/Tasks; let the user confirm before switching.
 
 ## Step 4 — Search for an existing pytest
 
@@ -88,55 +97,11 @@ grep -rn "<key_term>" xtest/test_*.py xtest/tdfs.py
 
 Likely candidates: `test_tdfs.py` (roundtrip), `test_abac.py` (ABAC), `test_legacy.py` (golden), `test_pqc.py`. If a test already asserts the relevant behavior, reuse it via `suite.select` — no draft test needed.
 
-**Don't grep `xtest/sdk/<lang>/cli.sh`.** Those wrappers are reusable infrastructure (versioned alongside each SDK dist) and their contents have nothing to do with scenario YAML fields. The scenario YAML doesn't need to know HOW a feature is plumbed — only WHICH pytest suite exercises it. Reading the wrappers is a waste of turns. If a feature's `supports("<name>")` gate isn't in `tdfs.py` yet, that's a signal that supporting infrastructure has to land separately from the scenario — note it in `actual:` and move on.
+**Don't grep `xtest/sdk/<lang>/cli.sh`.** Those wrappers are reusable infrastructure (versioned alongside each SDK dist) and their contents have nothing to do with scenario YAML fields. The scenario doesn't need to know HOW a feature is plumbed — only WHICH pytest suite exercises it. If a feature's `supports("<name>")` gate isn't in `tdfs.py` yet, that's a signal that supporting infrastructure has to land separately from the scenario — note it in `actual:` and move on.
 
 ## Step 5 — Write `xtest/scenarios/<id>.yaml`
 
-The canonical field list (titles, types, defaults, `anyOf` branches) lives in `xtest/schema/scenario.schema.json` — `Read` it whenever you need to know what's allowed. Each pin (`PlatformPin`, `KasPin`) requires **exactly one** of `dist:`, `source:`, or `image:`. `image:` is reserved for forward-compat and rejected today — pick `dist:` or `source:`.
-
-Released-version pin (typical Bug scenario):
-
-```yaml
-apiVersion: opentdf.io/v1alpha1
-kind: Scenario
-metadata:
-  id: <jira-key-lowercased>
-  title: "<Jira summary>"
-  created: <YYYY-MM-DD>
-instance:
-  metadata: { name: <jira-key-lowercased> }
-  platform: { dist: v0.9.0 }
-  ports: { base: <free base; 8080 if first, +1000 per concurrent scenario> }
-  kas:
-    alpha: { dist: v0.9.0, mode: standard }
-sdks:
-  encrypt:
-    go: { version: lts }
-  decrypt:
-    java: { version: "0.7.8" }
-suite:
-  select: "xtest/test_tdfs.py::test_tdf_roundtrip"
-  containers: ztdf
-expected: "..."
-actual:   "..."
-```
-
-Ref pin (TDD / HEAD / branch / PR):
-
-```yaml
-instance:
-  platform:
-    source: { ref: main }                  # branch, tag, or 40-char SHA
-  kas:
-    alpha:
-      source: { ref: feature/ecdsa-binding }
-      mode: standard
-sdks:
-  encrypt:
-    go: { version: main }                  # SdkPin.version accepts the same range of strings
-```
-
-Mix-and-match is fine — `platform` on `main`, `kas.alpha` on a released `dist:`, SDKs on different refs.
+Templates (released-version, ref-pin, mixed-mode, PR-pin-via-Jira-link) live in **`references/yaml-templates.md`**. Pick the matching shape, copy, and fill in.
 
 Validate before reporting success:
 
@@ -146,14 +111,19 @@ uv run python -m otdf_sdk_mgr.schema validate xtest/scenarios/<id>.yaml
 
 ## Step 6 — If no existing test fits
 
-Draft `xtest/bugs/<id>_test.py` using the `encrypt_sdk` / `decrypt_sdk` fixtures (pattern: `xtest/test_tdfs.py`). Surface the new file in your reply for the user to review — never silently land assertions.
+Draft `xtest/bugs/<id>_test.py` using the `encrypt_sdk` / `decrypt_sdk` fixtures (pattern: `xtest/test_tdfs.py`). Surface the new file in the reply for the user to review — never silently land assertions.
 
-For TDD tests where the underlying feature isn't yet implemented, gate participation behind `<sdk>.supports("<feature>")` and call `pytest.skip(...)` when the gate fails. The scenario then runs as "all skipped" until the SDK supports entry lands, at which point the test becomes a real assertion.
+For TDD tests where the underlying feature isn't yet implemented, gate participation behind `<sdk>.supports("<feature>")` and call `pytest.skip(...)` when the gate fails. The scenario then runs as "all skipped" until the SDK supports entry lands.
 
 ## Notes
 
-- `sdks.encrypt` and `sdks.decrypt` map to xtest's `--sdks-encrypt` / `--sdks-decrypt`. After PR #446 those pytest options take `sdk@version` specifiers like `go@v0.24.0`, `go@main`, or `go@*`. **Do NOT write those tokens in the YAML** — write a normal `{ version: lts }` (or any version string `otdf-sdk-mgr resolve` accepts: `v0.24.0`, `main`, an SDK-specific SHA, etc.). The `scenario-up` skill runs `otdf-sdk-mgr install scenario`, which records the resolved dist directory names in `xtest/scenarios/<id>.installed.json`; the bridge layers (`otdf-local scenario run` and pytest's `--scenario` default in `xtest/conftest.py`) read that file to emit the right `sdk@<dist>` tokens. If you forget the install step, those commands fail with `<id>.installed.json not found — run otdf-sdk-mgr install scenario first`.
+- `sdks.encrypt` and `sdks.decrypt` map to xtest's `--sdks-encrypt` / `--sdks-decrypt`. Pytest options take `sdk@version` specifiers (e.g. `go@v0.24.0`). **Do NOT write those tokens in the YAML** — write a normal `{ version: lts }` (or any version string `otdf-sdk-mgr resolve` accepts). `scenario-up` runs `otdf-sdk-mgr install scenario`, which records the resolved dist names in `xtest/scenarios/<id>.installed.json`; the bridge layers read that file to emit the right `sdk@<dist>` tokens.
 - List the same SDK in both `encrypt` and `decrypt` maps to reproduce xtest's legacy "all pairs" mode. Listing it on only one side keeps the scenario focused (a→b without b→a).
-- `instance.platform.dist` / `source.ref` and each `kas.<name>.dist` / `source.ref` need `otdf-sdk-mgr install scenario <path>` to have built the binary first. `scenario-up` handles that downstream.
 - For matrix runs (same suite × N refs), don't author N scenarios by hand — invoke the `scenario-matrix` skill against this scenario as the base.
-- One-line summary when done: report the scenario path, the new test file (if any), and the Jira link `https://virtru.atlassian.net/browse/<JIRA-KEY>` so the user can cross-reference.
+- Hand the resulting scenario to `scenario-up` next.
+
+## Additional Resources
+
+### Reference files
+
+- **`references/yaml-templates.md`** — every scenario YAML shape: released-version (Bug), ref-pin (TDD/HEAD), mixed-mode (new platform + shipped KAS), PR-pin-via-Jira-link (recommended when `acli link list` returned an opentdf PR), plus the validation command. Read this when writing or reviewing a scenario manifest.
diff --git a/.claude/skills/scenario-from-ticket/references/yaml-templates.md b/.claude/skills/scenario-from-ticket/references/yaml-templates.md
new file mode 100644
index 000000000..24b2640d0
--- /dev/null
+++ b/.claude/skills/scenario-from-ticket/references/yaml-templates.md
@@ -0,0 +1,96 @@
+# Scenario YAML templates
+
+The canonical field list (titles, types, defaults, `anyOf` branches) lives in `xtest/schema/scenario.schema.json`. Read it whenever a question about an allowed field arises. Each pin (`PlatformPin`, `KasPin`) requires **exactly one** of `dist:`, `source:`, or `image:`. `image:` is reserved for forward-compat and is rejected today — pick `dist:` or `source:`.
+
+## Released-version pin (typical Bug scenario)
+
+Use when reproducing a bug on a published release.
+
+```yaml
+apiVersion: opentdf.io/v1alpha1
+kind: Scenario
+metadata:
+  id: <jira-key-lowercased>
+  title: "<Jira summary>"
+  created: <YYYY-MM-DD>
+instance:
+  metadata: { name: <jira-key-lowercased> }
+  platform: { dist: v0.9.0 }
+  ports: { base: <free base; 8080 if first, +1000 per concurrent scenario> }
+  kas:
+    alpha: { dist: v0.9.0, mode: standard }
+sdks:
+  encrypt:
+    go: { version: lts }
+  decrypt:
+    java: { version: "0.7.8" }
+suite:
+  select: "xtest/test_tdfs.py::test_tdf_roundtrip"
+  containers: ztdf
+expected: "..."
+actual:   "..."
+```
+
+## Ref pin (TDD / HEAD / branch / PR)
+
+Use when the behavior under test lives on an unreleased branch, an in-flight PR, or HEAD. For PRs, prefer the 40-char `headRefOid` from `gh pr view <N> --json headRefOid` over the branch name — SHAs are immutable, branches move.
+
+```yaml
+instance:
+  platform:
+    source: { ref: main }                  # branch, tag, 40-char SHA, or pr:N
+  kas:
+    alpha:
+      source: { ref: feature/ecdsa-binding }
+      mode: standard
+sdks:
+  encrypt:
+    go: { version: main }                  # SdkPin.version accepts the same range of strings
+```
+
+## Mixed-mode (platform on a ref, KAS on a release)
+
+Use when validating that an unreleased platform interoperates with shipped KAS deployments (or vice versa).
+
+```yaml
+instance:
+  platform:
+    source: { ref: pr:3537 }               # in-flight PR
+  kas:
+    alpha: { dist: v0.9.0, mode: standard } # shipped KAS
+    km1:
+      source: { ref: pr:3537 }              # KAS that needs PR changes
+      mode: key_management
+sdks:
+  encrypt: { go: { version: main } }
+  decrypt: { go: { version: lts } }        # old client decrypting new platform output
+```
+
+## PR pin via Jira link (recommended for Story/Task tickets)
+
+When `acli jira workitem link list <KEY>` returned a linked PR (URL like `github.com/opentdf/platform/pull/<N>`), resolve and pin to the head SHA:
+
+```bash
+gh pr view <N> --repo opentdf/platform --json number,headRefName,headRefOid
+# → { "number": 3537, "headRefName": "DSPX-3383-post-quantum-kem", "headRefOid": "08ab3a0a…" }
+```
+
+Then in the scenario:
+
+```yaml
+metadata:
+  title: "<Jira summary> [opentdf/platform#3537 @ DSPX-3383-post-quantum-kem]"
+instance:
+  platform:
+    source: { ref: 08ab3a0a... }            # immutable 40-char SHA
+```
+
+Record the branch name in `metadata.title` for human readability; the SHA is what `otdf-sdk-mgr install` uses.
+
+## Validation
+
+Always validate before reporting success:
+
+```bash
+uv run python -m otdf_sdk_mgr.schema validate xtest/scenarios/<id>.yaml
+```
diff --git a/.claude/skills/scenario-matrix/SKILL.md b/.claude/skills/scenario-matrix/SKILL.md
index ee01aba54..9e4bbd90c 100644
--- a/.claude/skills/scenario-matrix/SKILL.md
+++ b/.claude/skills/scenario-matrix/SKILL.md
@@ -1,18 +1,18 @@
 ---
 name: scenario-matrix
-description: Use when running the same test suite across multiple refs, branches, PRs, or releases — bisecting regressions or validating a fix across versions. Generates scenario files only; does not run them.
+description: This skill should be used when the user asks to "run the same suite across multiple versions", "bisect a regression across releases", "validate a fix across PRs", "generate a scenario matrix", or wants the same test suite exercised at N different platform / SDK refs. Generates scenario files only; does not run them — hand the output to `scenario-up` / `scenario-run` per cell.
 allowed-tools: Bash, Read, Write, Grep, Glob
 ---
 
 # scenario-matrix
 
-You produce N scenario files from one base scenario, where N = the number of refs the user wants exercised. Each output scenario differs only in `instance.platform` (and optionally any KAS pins the user says should track the same ref). SDK pins are preserved unless explicitly told to vary.
+Produce N scenario files from one base scenario, where N is the number of refs the user wants exercised. Each output scenario differs only in `instance.platform` (and optionally any KAS pins the user says should track the same ref). SDK pins are preserved unless explicitly told to vary.
 
 ## Inputs
 
 - A **base**, either:
   - Path to an existing `xtest/scenarios/<id>.yaml`, OR
-  - A Jira ticket key — in which case invoke `scenario-from-ticket` first to produce the base, then proceed.
+  - A Jira ticket key — invoke `scenario-from-ticket` first to produce the base, then proceed.
 - A **ref list** — any combination of:
   - Released versions: `v0.9.0`, `v0.8.5`
   - Branch names: `main`, `feature/ecdsa-binding`
@@ -26,7 +26,7 @@ You produce N scenario files from one base scenario, where N = the number of ref
 - If given a path: `Read` it.
 - If given a ticket key: invoke `scenario-from-ticket` against the ticket first, then `Read` the produced file.
 
-The base scenario provides everything except `instance.platform` (and tracked KAS pins): metadata.title becomes the title prefix, `suite` is shared across all cells, `sdks` is preserved.
+The base scenario provides everything except `instance.platform` (and tracked KAS pins): `metadata.title` becomes the title prefix, `suite` is shared across all cells, `sdks` is preserved.
 
 ### Step 2 — Resolve each ref to a concrete value
 
@@ -54,7 +54,7 @@ Each cell scenario gets:
 - A unique `instance.metadata.name` (same as `metadata.id`).
 - A unique `instance.ports.base` — start from the base's value and add `+1000` per additional cell. `scenario-up` rejects overlapping port bases between concurrent instances.
 - `metadata.title` gets a ` [<token>]` suffix for at-a-glance identification.
-- `instance.platform` rewritten to the resolved ref. For KAS pins that should track the same ref (default: all of them), rewrite their pin too. KAS pins the user explicitly excluded keep the base's value.
+- `instance.platform` rewritten to the resolved ref. For KAS pins that should track the same ref (default: all of them), rewrite their pin too. Pins the user explicitly excluded keep the base's value.
 - `suite`, `sdks`, `expected`, `actual` — unchanged from the base.
 
 ### Step 4 — Validate every file
@@ -87,5 +87,18 @@ Bail (delete the just-written files) if any cell fails validation — partial ma
 
 - This skill **writes scenario files only**. It does not install artifacts, scaffold instances, or run pytest. Hand the resulting files to `scenario-up` and `scenario-run` per cell.
 - For two PRs that differ in *SDK* (not platform), vary `sdks.<encrypt|decrypt>.<lang>.version` instead of `platform`. Same pattern, different field — `SdkPin.version` accepts the same range of refs (`v0.24.0`, `main`, SHA).
-- For a full platform × SDK matrix, generate N×M scenarios. Be prepared for long install times — each new platform ref triggers a `go build` (~30-60s first time per version); subsequent runs reuse the cached binary.
+- For a full platform × SDK matrix, generate N×M scenarios. Be prepared for long install times — each new platform ref triggers a `go build` (~30–60s first time per version); subsequent runs reuse the cached binary.
 - Don't update `expected:` / `actual:` per cell unless the user specifies that one of the refs is the "known good" or "known broken" baseline.
+
+### Pre-install shared refs (workaround for [DSPX-3417](https://virtru.atlassian.net/browse/DSPX-3417))
+
+`otdf-sdk-mgr install scenario` currently rebuilds the platform once per pin even when N pins share a ref — so an N-cell matrix on the same platform ref triggers N rebuilds, each ~30–60s. Workaround:
+
+```bash
+# Build once.
+uv run otdf-sdk-mgr install tip --ref <shared-ref> platform
+# Then run the per-cell loop in Step 5; each `install scenario` will reuse
+# the cached binary instead of rebuilding.
+```
+
+When DSPX-3417's dedup ships, the workaround becomes unnecessary.
diff --git a/.claude/skills/scenario-run/SKILL.md b/.claude/skills/scenario-run/SKILL.md
index c127ecee4..f141e9617 100644
--- a/.claude/skills/scenario-run/SKILL.md
+++ b/.claude/skills/scenario-run/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: scenario-run
-description: Use after `scenario-up` to run the scenario's test suite and classify results against its expected/actual fields.
+description: This skill should be used when the user asks to "run the scenario", "run the scenario tests", "execute the scenario suite", "test the scenario", or after `scenario-up` to invoke the pytest selection declared by `xtest/scenarios/<id>.yaml` and classify the result against the scenario's `expected:` / `actual:` fields.
 allowed-tools: Bash, Read
 ---
 
 # scenario-run
 
-You run the pytest selection declared by the scenario's `suite` block against the running instance and interpret the result in terms of the ticket the scenario was authored for. The same three-bucket classification works for bug-repros (where "expected" means *failure that matches `actual:`*) and for TDD scenarios (where "expected" means *skip-until-feature-lands*).
+Invoke the pytest selection declared by the scenario's `suite` block against the running instance, then classify the result in terms of the ticket the scenario was authored for. The same four-bucket classification works for bug-repros (where "expected" means *failure that matches `actual:`*), TDD scenarios (where "expected" means *skip-until-feature-lands*), and assertion drift between draft tests and what the implementation actually emits.
 
 ## Inputs
 
@@ -15,34 +15,73 @@ You run the pytest selection declared by the scenario's `suite` block against th
 
 ## Process
 
-1. **Invoke the runner**:
+### Step 1 — Invoke the runner
 
-   ```bash
-   uv run otdf-local scenario run xtest/scenarios/<id>.yaml
-   ```
+```bash
+uv run otdf-local scenario run xtest/scenarios/<id>.yaml
+```
 
-   This translates the scenario's `suite.select`, `suite.containers`, `suite.markers`, and `sdks.{encrypt,decrypt}` into the equivalent `pytest --sdks-encrypt ... --sdks-decrypt ... --containers ...` invocation under `xtest/` with `OTDF_LOCAL_INSTANCE_NAME` set. SDK tokens are emitted in xtest's `sdk@version` form (see PR #446) — the resolved version names come from the sibling `<scenario>.installed.json` that `otdf-sdk-mgr install scenario` writes.
+This translates the scenario's `suite.select`, `suite.containers`, `suite.markers`, and `sdks.{encrypt,decrypt}` into the equivalent `pytest --sdks-encrypt … --sdks-decrypt … --containers …` invocation under `xtest/` with `OTDF_LOCAL_INSTANCE_NAME` set. SDK tokens are emitted in xtest's `sdk@version` form; the resolved version names come from the sibling `<scenario>.installed.json`.
 
-   If `scenario run` exits with `Error: <path>.installed.json not found`, the user skipped the install step. Tell them to run `uv run otdf-sdk-mgr install scenario <path>` (or re-run `scenario-up`) before retrying.
+Failure modes:
+- `Error: <path>.installed.json not found` — the user skipped Step 1 of `scenario-up`. Run `uv run otdf-sdk-mgr install scenario <path>` first.
+- `installed.json` is present but `sdks.encrypt` / `sdks.decrypt` are empty arrays despite the scenario declaring SDK pins — this is the **source-built SDK** case; fall back to a direct pytest invocation (see Step 1b).
 
-2. **Capture exit code and tail of output**. The pytest output is the source of truth; don't re-interpret.
+### Step 1b — Source-build fallback
 
-3. **Classify** against the scenario's `expected:` and `actual:` fields:
-   - **Expected outcome** — the test result matches what `expected:` (or, for a bug, `actual:`) predicts.
-     - Bug scenario: pytest FAILED with an assertion/stderr matching `actual:`. Bug reproduced. Cite the matching line.
-     - TDD/feature scenario on a ref where the feature isn't landed yet: tests SKIPPED via `supports("<feature>")`. Feature gate is still pending as predicted.
-     - TDD/feature scenario on a ref where the feature is landed: tests PASSED. Feature works; the scenario is now a regression gate.
-   - **Unexpected outcome** — the test result is *not* what the scenario predicted.
-     - Bug scenario: pytest PASSED. Either the bug is fixed at this pin, or the scenario doesn't capture it tightly enough. Suggest widening the assertion, pinning a different ref, or marking the bug closed.
-     - TDD/feature scenario: tests FAILED for a reason that doesn't match `actual:`. A real bug surfaced, OR the prereq implementation work landed and the test now needs a real assertion (not a skip). Surface the actual failure to the user.
-   - **Unrelated failure** — pytest errored out (collection error, environment issue, import error, timeout). Don't claim outcome match either way; report the error and recommend a next diagnostic step.
+When the scenario pins source-built SDKs (`source.ref` rather than `version`), `otdf-local scenario run` today produces an empty `--sdks-*` argv. Invoke pytest directly instead:
 
-4. **Record artifacts**. The pytest run leaves logs under `tests/instances/<id>/logs/`. List the relevant log files in your reply so the user can attach them to the Jira ticket.
+```bash
+cd xtest
+set -a
+eval "$(cd ../otdf-local && OTDF_LOCAL_INSTANCE_NAME=<id> uv run otdf-local env)"
+source test.env
+set +a
+
+# Map each source-pinned SDK to its dist slug under xtest/sdk/<lang>/dist/.
+# For platform PR #N, the slug is typically `refs--pull--<N>--head`.
+PLATFORM_VERSION=<future-version> OTDFCTL_HEADS='["<go-dist-slug>"]' \
+  uv run pytest <suite.select> \
+    --sdks-encrypt <lang>@<dist-slug> \
+    --sdks-decrypt <lang>@<dist-slug> \
+    --containers <suite.containers>
+```
+
+`PLATFORM_VERSION` and `OTDFCTL_HEADS` defaults are noted in `scenario-up`; pull them from there or from the scenario's source-build env knobs section. This fallback is temporary — tracked at [DSPX-3417](https://virtru.atlassian.net/browse/DSPX-3417) (scenario YAML accepting source builds) and [DSPX-3418](https://virtru.atlassian.net/browse/DSPX-3418) (`OTDFCTL_HEADS` → CLI flag).
+
+### Step 2 — Capture exit code and tail of output
+
+The pytest output is the source of truth; do not re-interpret it. Save the last ~60 lines for the evidence quote in the classification.
+
+### Step 3 — Classify against `expected:` and `actual:`
+
+Pick exactly one bucket. Lead the reply with the bucket name; users skim for it.
+
+- **Expected outcome** — the test result matches what `expected:` (or, for a bug, `actual:`) predicts.
+  - Bug scenario: pytest FAILED with an assertion or stderr matching `actual:`. Bug reproduced; cite the matching line.
+  - TDD/feature scenario on a ref where the feature isn't landed: tests SKIPPED via `supports("<feature>")`. Gate still pending as predicted.
+  - TDD/feature scenario on a ref where the feature is landed: tests PASSED. The scenario is now a regression gate.
+
+- **Unexpected outcome** — the test result is *not* what the scenario predicted.
+  - Bug scenario: pytest PASSED. Either the bug is fixed at this pin, or the scenario doesn't capture it tightly enough. Suggest widening the assertion, pinning a different ref, or closing the bug.
+  - TDD/feature scenario: tests FAILED for a reason that doesn't match `actual:`. A real bug surfaced, OR the prereq implementation landed and the test now needs a real assertion rather than a skip.
+
+- **Assertion-stricter-than-implementation** — pytest FAILED on a specific assertion whose expected value is *aspirational* (drawn from a PR description, spec, or RFC) rather than current behaviour. Diagnostic: one assertion compares a single real field to a single concrete value, both legitimate, and they simply don't match. The implementation works correctly under a *different* contract than the test encodes. Action: relax the assertion to the observed value (record both old and new in a comment so the intent is preserved), file a follow-up if the strict value is load-bearing. This is what catches "PR description said KAO type is `mlkem-wrapped` but the binary emits `wrapped`."
+
+- **Unrelated failure** — pytest errored out (collection error, environment issue, import error, timeout). Don't claim outcome match either way; report the error and recommend a next diagnostic step. If services look wrong, defer to `scenario-doctor` for a state diff.
+
+### Step 4 — Record artifacts
+
+Pytest leaves logs under `tests/instances/<id>/logs/`. List the relevant per-service log paths in the reply so the user can attach them to the Jira ticket.
 
 ## Output format
 
-One-line headline (`expected outcome` / `unexpected outcome` / `unrelated failure`), then a short bulleted summary:
-- `select:` the pytest selector
-- `exit_code:` the return value
-- `evidence:` 1-2 lines from the output that justify the classification
+One-line headline naming the bucket, then a short bulleted summary:
+- `select:` the pytest selector that ran
+- `exit_code:` the pytest return value
+- `evidence:` 1–2 lines from the output that justify the classification
 - `logs:` paths to the relevant per-service logs
+
+## When to defer
+
+If the failure looks environmental (services missing, ports drift, stale binary) rather than test-substantive, hand off to `scenario-doctor` for a state-vs-intent diff before iterating on the test or scenario.
diff --git a/.claude/skills/scenario-tear-down/SKILL.md b/.claude/skills/scenario-tear-down/SKILL.md
index 0838e9585..a37b5fbcb 100644
--- a/.claude/skills/scenario-tear-down/SKILL.md
+++ b/.claude/skills/scenario-tear-down/SKILL.md
@@ -1,42 +1,78 @@
 ---
 name: scenario-tear-down
-description: Use when the user is done with a scenario or wants to stop, clean up, or free ports/disk.
+description: This skill should be used when the user asks to "tear down the scenario", "stop the instance", "shut down the test environment", "clean up the scenario", "free the ports", or is done with a scenario and wants services stopped and (optionally) on-disk state removed.
 allowed-tools: Bash, Read
 ---
 
 # scenario-tear-down
 
-You stop a running scenario cleanly and optionally remove its on-disk state.
+Stop a running scenario cleanly and optionally remove its on-disk state. Confirm shared resources (docker stacks across worktrees, symlinked platform dirs) are handled appropriately.
 
 ## Inputs
 
-- The instance name (typically the lowercased Jira key, e.g. `dspx-3302`). If the user passes the scenario YAML path instead, read its `instance.metadata.name`.
-- Whether the user wants the instance directory preserved (default: yes — keep it for re-runs).
+- The instance name (typically the lowercased Jira key, e.g. `dspx-3302`). If the user passed the scenario YAML path instead, read its `instance.metadata.name`.
+- Whether to preserve the instance directory (default: yes — keep it for re-runs).
 
 ## Process
 
-1. **Stop services**:
+### Step 1 — Pre-flight shared resources
 
-   ```bash
-   uv run otdf-local --instance <name> down
-   ```
+Before stopping anything, list the docker compose projects currently sharing the host daemon:
 
-   The `down` command halts the platform process, all KAS instances under management, and the docker dependencies (keycloak, postgres) — unless another instance is still using them, in which case docker is left running.
+```bash
+docker ps --format '{{.Names}}' \
+  | grep -E -- '-keycloak-|-opentdfdb-' \
+  | sed -E 's/-(keycloak|opentdfdb)-[0-9]+$//' \
+  | sort -u
+```
 
-2. **Optionally clean state**. Only if the user explicitly asked to remove:
+Each line is a compose-project name — typically the directory name where `docker compose` was invoked (a worktree's `xtest/platform/src/<slug>/`). If more than one project appears, surface this in the reply: `down` will *keep* docker keycloak/postgres running because another instance still uses them. The user's expectation that "ports 5432 and 8888 are now free" would be wrong.
 
-   ```bash
-   uv run otdf-local instance rm <name> -y
-   ```
+### Step 2 — Stop services
 
-   This deletes `tests/instances/<name>/` including its `logs/`, `keys/`, and per-KAS configs. The platform binary at `xtest/platform/dist/<version>/service` is shared and is NOT removed (`otdf-sdk-mgr clean --dist-only` is the right command if the user wants to free that too).
+```bash
+uv run otdf-local --instance <name> down
+```
 
-3. **Confirm port range is free** (useful if the user is about to bring up another scenario on the same base):
+Halts the platform process, all KAS instances under management, and the docker dependencies — unless another instance is still using them, in which case docker is left running (per Step 1's pre-flight). Other instances' platforms and KAS processes are untouched.
 
-   ```bash
-   uv run otdf-local instance ls --json
-   ```
+### Step 3 — Optionally clean state
+
+Only if the user explicitly asked to remove:
+
+```bash
+uv run otdf-local instance rm <name> -y
+```
+
+Deletes `tests/instances/<name>/` including its `logs/`, `keys/`, and per-KAS configs. The platform binary at `xtest/platform/dist/<slug>/service` is shared and is NOT removed. To free those too:
+
+```bash
+uv run otdf-sdk-mgr clean --dist-only
+```
+
+### Step 4 — Confirm
+
+```bash
+uv run otdf-local instance ls --json
+```
+
+Verify the instance is gone (if `rm`'d) or that its services no longer appear running. If sibling worktrees still own ports, that's recorded in Step 1's output — flag it in the summary.
+
+## Post-down notes to surface
+
+- **Symlinked platform dir**: if this worktree's `xtest/platform` is a symlink (or `xtest/platform.local-backup/` exists), mention it. That was a one-time workaround for `uv tool install`'d CLIs anchoring to a sibling worktree (see DSPX-3415). The backup directory accumulates stale `src/` and can be reclaimed (`rm -rf xtest/platform.local-backup`) once the user is sure the symlink is permanent.
+- **Foreign docker-compose project**: if Step 1 surfaced another project, name it so the user knows which worktree to manage if they want a truly clean host.
 
 ## Caution
 
 Never remove an instance without explicit user confirmation. The directory may contain golden keys or generated configs that took time to assemble. If unsure, leave it.
+
+## Output
+
+One-line summary, then optional sections in this order:
+- Stop result (services stopped: …).
+- Cleaned (if `rm` was run): instance dir removed at …
+- Docker status: stopped / still running (with project names if shared).
+- Post-down notes (symlinks, backup dirs, foreign projects).
+
+Skip empty sections.
diff --git a/.claude/skills/scenario-up/SKILL.md b/.claude/skills/scenario-up/SKILL.md
index dcf1ea357..45050fe71 100644
--- a/.claude/skills/scenario-up/SKILL.md
+++ b/.claude/skills/scenario-up/SKILL.md
@@ -1,51 +1,105 @@
 ---
 name: scenario-up
-description: Use when the user has a scenario YAML and wants the environment started (before running tests).
+description: This skill should be used when the user asks to "bring up a scenario", "start a scenario environment", "spin up the test instance", "install and run the scenario", or has authored a `xtest/scenarios/<id>.yaml` and wants the platform + KAS + dependencies started before invoking pytest. Use `scenario-run` after this succeeds.
 allowed-tools: Bash, Read
 ---
 
 # scenario-up
 
-You bring the environment described by a `scenarios.yaml` up and confirm it's healthy. The three steps are non-negotiable; do them in order.
+Bring the environment described by a `xtest/scenarios/<id>.yaml` up and confirm it is healthy. The four steps are non-negotiable; do them in order.
 
 ## Inputs
 
-- Path to a validated `xtest/scenarios/<id>.yaml`. If the user doesn't provide one, ask.
+- Path to a validated `xtest/scenarios/<id>.yaml`. If the user did not provide one, ask.
 
 ## Process
 
-1. **Install artifacts** — platform binary, per-KAS binaries, helper scripts, and the encrypt+decrypt SDKs declared in the scenario:
+### Step 1 — Install artifacts
 
-   ```bash
-   uv run otdf-sdk-mgr install scenario xtest/scenarios/<id>.yaml
-   ```
+```bash
+uv run otdf-sdk-mgr install scenario xtest/scenarios/<id>.yaml
+```
 
-   This writes `xtest/scenarios/<id>.installed.json` next to the scenario with the resolved dist paths. The first `go build` per platform version takes ~30-60s; subsequent runs reuse the cached binary.
+Installs the platform binary, per-KAS binaries, helper scripts, and the encrypt + decrypt SDKs declared in the scenario. The result is recorded at `xtest/scenarios/<id>.installed.json` next to the scenario.
 
-2. **Scaffold the instance directory** (creates `tests/instances/<id>/`):
+**Guard against partial installs.** Read the resulting `<id>.installed.json` immediately:
 
-   ```bash
-   uv run otdf-local instance init <id> --from-scenario xtest/scenarios/<id>.yaml
-   ```
+```bash
+cat xtest/scenarios/<id>.installed.json | jq '{status, sdk_count: (.sdks.encrypt + .sdks.decrypt | length)}'
+```
 
-   If the instance already exists, this is a no-op for the existing files; double-check with `uv run otdf-local instance ls` first to avoid surprising the user.
+If `status == "partial"` OR `sdks.encrypt` / `sdks.decrypt` are empty arrays *but* the scenario declared SDK entries, treat it as a hard failure and stop. Today `install scenario` silently ignores source-built SDK pins (only released versions resolve via `install_release`). The remedy:
 
-3. **Bring it up**:
+```bash
+# Install source-built SDKs separately, then continue.
+uv run otdf-sdk-mgr install tip --ref <ref> <sdk>
+```
 
-   ```bash
-   uv run otdf-local --instance <id> up
-   ```
+This limitation is tracked at [DSPX-3417](https://virtru.atlassian.net/browse/DSPX-3417). When that ships, the guard becomes redundant — keep it until then.
 
-   Then poll status until everything is healthy (don't proceed before this succeeds):
+First `go build` per platform version takes ~30–60s; subsequent runs reuse the cached binary.
 
-   ```bash
-   uv run otdf-local --instance <id> status --json
-   ```
+### Step 2 — Scaffold the instance directory
 
-   If any service stays unhealthy after ~60 seconds, surface the relevant log via `uv run otdf-local --instance <id> logs <service> -n 50` and report the failure mode rather than retrying blindly.
+```bash
+uv run otdf-local instance init <id> --from-scenario xtest/scenarios/<id>.yaml
+```
+
+Creates `tests/instances/<id>/`. If the instance already exists, the command is a no-op for existing files. Double-check with `uv run otdf-local instance ls` first to avoid surprising the user with overwrites.
+
+### Step 2.5 — Bootstrap PR worktrees (when source-pinned)
+
+A freshly built PR worktree from `install tip --ref pr:N` ships *templates* but not generated dev keys, and lacks the `opentdf.yaml` filename `otdf-local` expects. Running `up` against it produces cryptic Docker "Is a directory" and platform "no such file" errors. Pre-flight the seed files:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT:-.}/skills/scenario-up/scripts/bootstrap-pr-worktree.sh xtest/scenarios/<id>.yaml
+```
+
+Script behaviour: for each `source.ref` pin in the scenario, resolve the dist's worktree via its `.version` sidecar; check that `kas-*.pem`, `keys/{ca.jks,localhost.crt,localhost.key}`, and `opentdf.yaml` exist as *files* (not Docker-created empty dirs). On miss it generates / copies from `xtest/platform/src/main/` / suggests `bash .github/scripts/init-temp-keys.sh`. Output is tab-separated; review the rows where `action != kept` before proceeding.
+
+Skip this step for scenarios pinned entirely on `dist:` (released versions) — those use pre-baked artifacts and don't need seeding.
+
+[DSPX-3416](https://virtru.atlassian.net/browse/DSPX-3416) tracks moving this bootstrap into `otdf-local up` itself. Until it lands, run the script.
+
+### Step 3 — Bring it up
+
+```bash
+uv run otdf-local --instance <id> up
+```
+
+Then poll status until everything is healthy (do not proceed before this succeeds):
+
+```bash
+uv run otdf-local --instance <id> status --json
+```
+
+If any service stays unhealthy after ~60 seconds, surface the relevant log via `uv run otdf-local --instance <id> logs <service> -n 50` and report the failure mode rather than retrying blindly.
+
+## Source-build env knobs
+
+When the scenario pins source-built artifacts (`source.ref` on platform / KAS / SDKs), two env-var overrides are temporarily required for `scenario-run`. Note them now so the user has them ready:
+
+```bash
+# Tell xtest which otdfctl binary to use (the slug under xtest/sdk/go/dist/).
+export OTDFCTL_HEADS='["refs--pull--<N>--head"]'
+
+# Make tdfs.get_platform_features() enable in-flight feature flags whose semver
+# gate is in the future; PR builds self-report old versions.
+export PLATFORM_VERSION=0.17.0
+```
+
+These workarounds are tracked at [DSPX-3418](https://virtru.atlassian.net/browse/DSPX-3418) (`OTDFCTL_HEADS` → CLI flag) and [DSPX-3419](https://virtru.atlassian.net/browse/DSPX-3419) (auto-derive `PLATFORM_VERSION`). When either lands, remove the corresponding line.
 
 ## Output
 
 Once healthy, report:
 - The instance name and which ports it occupies (look at `instance.yaml`'s `ports.base`).
-- The next command the user is likely to run (`scenario-run`).
+- The path to `<id>.installed.json` (so `scenario-run` can find it).
+- Any unusual rows from the bootstrap probe (e.g. "seeded `keys/ca.jks` from main worktree").
+- The next command the user is likely to run: `scenario-run xtest/scenarios/<id>.yaml`.
+
+## Additional Resources
+
+### Script
+
+- **`scripts/bootstrap-pr-worktree.sh`** — pre-flights a PR worktree's seed files before `otdf-local up`. Takes one positional argument: the scenario YAML path. Tab-separated stdout. Idempotent — safe to re-run.
diff --git a/.claude/skills/scenario-up/scripts/bootstrap-pr-worktree.sh b/.claude/skills/scenario-up/scripts/bootstrap-pr-worktree.sh
new file mode 100755
index 000000000..72a97bdd6
--- /dev/null
+++ b/.claude/skills/scenario-up/scripts/bootstrap-pr-worktree.sh
@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# bootstrap-pr-worktree.sh — ensure platform source worktrees referenced by a
+# scenario have the seed files otdf-local + docker-compose expect.
+#
+# Usage: bootstrap-pr-worktree.sh <path-to-scenario.yaml>
+#
+# A fresh `otdf-sdk-mgr install tip --ref <ref> platform` produces the
+# /service binary and a populated git worktree at xtest/platform/src/<slug>/,
+# but it does NOT generate the dev keys (kas-*.pem, keys/ca.jks, …) or copy
+# opentdf-dev.yaml → opentdf.yaml. `otdf-local up` then fails in cryptic
+# ways (Keycloak "Is a directory", platform "no such file"). This script
+# pre-flights each referenced worktree and either bootstraps or fails loudly
+# with the exact remedy.
+#
+# Output: tab-separated, header on first line.
+# Columns: worktree  file  state  action
+#   state ∈ { ok | missing | empty-dir }
+#   action ∈ { kept | generated | copied | manual-required }
+
+set -u
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: $(basename "$0") <scenario.yaml>" >&2
+  exit 2
+fi
+
+scenario="$1"
+[[ -f "$scenario" ]] || { echo "scenario not found: $scenario" >&2; exit 2; }
+
+# Resolve repo root (the dir containing xtest/) by walking up from $scenario.
+dir="$(cd "$(dirname "$scenario")" && pwd)"
+while [[ "$dir" != "/" && ! -d "$dir/xtest" ]]; do dir="$(dirname "$dir")"; done
+[[ -d "$dir/xtest" ]] || { echo "could not locate xtest/ above $scenario" >&2; exit 2; }
+PLATFORM_DIST="$dir/xtest/platform/dist"
+
+# Files each worktree needs. Order matters for the action log — opentdf.yaml
+# last so its "copied from opentdf-dev.yaml" message lands after the keys.
+REQUIRED_FILES=(
+  kas-private.pem
+  kas-cert.pem
+  kas-ec-private.pem
+  kas-ec-cert.pem
+  keys/ca.jks
+  keys/localhost.crt
+  keys/localhost.key
+  opentdf.yaml
+)
+
+# Extract referenced refs from the scenario. We tolerate yq presence/absence:
+# prefer `yq -r` when available, fall back to a grep that handles the two
+# shapes we emit (`ref: pr:3537` inline and `{ ref: pr:3537 }` flow-style).
+refs=()
+if command -v yq >/dev/null 2>&1; then
+  while IFS= read -r r; do [[ -n "$r" && "$r" != "null" ]] && refs+=("$r"); done < <(
+    yq -r '
+      [ .instance.platform.source.ref?,
+        (.instance.kas[]?.source.ref?)
+      ] | .[] | select(. != null)
+    ' "$scenario" 2>/dev/null | sort -u
+  )
+else
+  while IFS= read -r r; do refs+=("$r"); done < <(
+    grep -E '\{?\s*ref:' "$scenario" | sed -E 's/.*ref:[[:space:]]*"?([^",}[:space:]]+)"?.*/\1/' | sort -u
+  )
+fi
+
+if [[ ${#refs[@]} -eq 0 ]]; then
+  echo "no source.ref pins found in $scenario (dist-only scenario, nothing to bootstrap)" >&2
+  exit 0
+fi
+
+printf 'worktree\tfile\tstate\taction\n'
+
+for ref in "${refs[@]}"; do
+  # Slug used by otdf-sdk-mgr: replace `/` and `:` with `--`. Mutable refs
+  # like `main`, `pr:3537` get slugs `main`, `refs--pull--3537--head` (the
+  # `pr:N` shorthand expands inside the installer). Read the .version sidecar
+  # to get the canonical worktree path rather than guess.
+  dist_dir=""
+  for slug_candidate in "$PLATFORM_DIST"/*/; do
+    [[ -f "$slug_candidate/.version" ]] || continue
+    if grep -Fq "ref=$ref" "$slug_candidate/.version" || grep -Fq "ref=refs/pull/${ref#pr:}/head" "$slug_candidate/.version"; then
+      dist_dir="${slug_candidate%/}"; break
+    fi
+  done
+  if [[ -z "$dist_dir" ]]; then
+    printf '%s\t-\tmissing\tmanual-required\n' "$ref"
+    echo "no dist dir found for ref=$ref; run 'otdf-sdk-mgr install tip --ref $ref platform' first" >&2
+    continue
+  fi
+  worktree="$(awk -F= '/^worktree=/ {print $2}' "$dist_dir/.version")"
+  [[ -d "$worktree" ]] || { printf '%s\t.version\tmissing\tmanual-required\n' "$ref"; continue; }
+
+  for f in "${REQUIRED_FILES[@]}"; do
+    path="$worktree/$f"
+    if [[ -f "$path" ]]; then
+      printf '%s\t%s\tok\tkept\n' "$worktree" "$f"
+      continue
+    fi
+    if [[ -d "$path" ]]; then
+      # Docker bind-mount created an empty dir on a prior failed up. Remove it
+      # so the bootstrap fill below can replace it with a real file.
+      rmdir "$path" 2>/dev/null || true
+      printf '%s\t%s\tempty-dir\tremoved\n' "$worktree" "$f"
+    fi
+
+    # Fill rules:
+    #   opentdf.yaml: cp opentdf-dev.yaml → opentdf.yaml (legacy template name).
+    #   everything else: try copying from xtest/platform/src/main/, else fail.
+    if [[ "$f" == "opentdf.yaml" && -f "$worktree/opentdf-dev.yaml" ]]; then
+      cp "$worktree/opentdf-dev.yaml" "$path"
+      printf '%s\t%s\tmissing\tcopied(opentdf-dev.yaml)\n' "$worktree" "$f"
+      continue
+    fi
+
+    main_dir="$dir/xtest/platform/src/main"
+    if [[ -f "$main_dir/$f" ]]; then
+      mkdir -p "$(dirname "$path")"
+      cp "$main_dir/$f" "$path"
+      printf '%s\t%s\tmissing\tcopied(main)\n' "$worktree" "$f"
+      continue
+    fi
+
+    printf '%s\t%s\tmissing\tmanual-required\n' "$worktree" "$f"
+    cat >&2 <<EOF
+missing: $path
+  remedy: cd "$worktree" && bash .github/scripts/init-temp-keys.sh
+          (run from inside the worktree; generates kas-*.pem and keys/*)
+EOF
+  done
+done

From 5f31811806abd032a6b3e19cf74bb3cd29300e32 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 2 Jun 2026 09:26:54 -0400
Subject: [PATCH 26/64] fix(.claude/skills): align scenario-* with
 self-provisioning init + correct schema
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- scenario-up: drop Step 2.5 bootstrap script (instance init now
  self-provisions keys + opentdf.yaml per 74492a47); add an
  `otdf-local env` sanity check before handing off to scenario-run.
- scenario-run: replace stale `suite.select` references with
  `suite.targets` (list); update Step 1b source-build fallback template
  to unpack targets positionally.
- scenario-doctor: Step 2 now invokes the read-only verifier against
  the instance dir instead of the platform worktree.
- scenario-from-ticket: one stale `suite.select` mention fixed.
- Move bootstrap-pr-worktree.sh → scenario-doctor/scripts/check-instance-seed.sh
  and rewrite as a read-only verifier (no cp/rmdir side effects).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .claude/skills/scenario-doctor/SKILL.md       |  15 +-
 .../scripts/check-instance-seed.sh            |  77 ++++++++++
 .claude/skills/scenario-from-ticket/SKILL.md  |   2 +-
 .claude/skills/scenario-run/SKILL.md          |   8 +-
 .claude/skills/scenario-up/SKILL.md           |  31 ++---
 .../scripts/bootstrap-pr-worktree.sh          | 131 ------------------
 6 files changed, 99 insertions(+), 165 deletions(-)
 create mode 100644 .claude/skills/scenario-doctor/scripts/check-instance-seed.sh
 delete mode 100755 .claude/skills/scenario-up/scripts/bootstrap-pr-worktree.sh

diff --git a/.claude/skills/scenario-doctor/SKILL.md b/.claude/skills/scenario-doctor/SKILL.md
index f55bd58f3..fb918c687 100644
--- a/.claude/skills/scenario-doctor/SKILL.md
+++ b/.claude/skills/scenario-doctor/SKILL.md
@@ -36,22 +36,22 @@ alpha     8181  v090...       a1b2c3d4...   200    WRONG-BINARY
 - `EXTRA` — port is occupied by a service the instance didn't declare. Usually a leftover from another instance/worktree.
 - `NO-PIN` — instance manifest didn't pin this service (skip).
 
-### Step 2 — Verify seed files
+### Step 2 — Verify instance-dir seed files
 
-For each unique worktree referenced in the diff output (parse the `expected_sha` rows back to `.version` sidecars), invoke the bootstrap script in dry-run inspection mode — re-using `scenario-up`'s probe so the file checks stay consistent:
+`otdf-local instance init` is responsible for seeding `keys/{ca.jks,localhost.crt,localhost.key}`, `keys/kas-*.pem`, and `instances/<name>/opentdf.yaml` (with a generated `services.kas.root_key`). Confirm they're all present:
 
 ```bash
-bash ${CLAUDE_PLUGIN_ROOT:-.}/skills/scenario-up/scripts/bootstrap-pr-worktree.sh <scenario-path>
+bash ${CLAUDE_PLUGIN_ROOT:-.}/skills/scenario-doctor/scripts/check-instance-seed.sh <name>
 ```
 
-Treat any `state=empty-dir` or `state=missing action=manual-required` row as a real problem worth surfacing — those are the silent-failure shapes (Docker bind-mount stubs, ungenerated dev keys).
+Tab-separated output, one row per artifact, `state ∈ {ok, missing, empty}`. Treat any non-`ok` row as a real problem — re-run `uv run otdf-local instance init <name> --from-scenario <path>` to refresh (existing files are preserved, so this won't churn the root_key).
 
 ### Step 3 — Assign a verdict
 
 Roll up Steps 1–2 into one of three colors. Lead the reply with the verdict; users scan for this.
 
 - **GREEN** — every declared service is `MATCH` + 200, no `EXTRA` rows, every seed file `ok`. Nothing for the user to do.
-- **YELLOW** — at least one `WRONG-BINARY`, `EXTRA`, or `empty-dir`/`missing` row, but the instance is *running*. Tests may pass or fail unpredictably until the drift is resolved.
+- **YELLOW** — at least one `WRONG-BINARY`, `EXTRA`, or `missing`/`empty` seed-file row, but the instance is *running*. Tests may pass or fail unpredictably until the drift is resolved.
 - **RED** — at least one declared service is `NOT-RUNNING`. Tests cannot succeed; recommend `otdf-local --instance <name> up` (fresh start) or per-service `restart`.
 
 ### Step 4 — Per-row remedy
@@ -63,7 +63,7 @@ For each non-`MATCH` row, emit a one-line remedy alongside the diff table:
 | `NOT-RUNNING` | `otdf-local --instance <name> up` (full) or `restart <service>` (single service) |
 | `WRONG-BINARY` | Identify owning PID's worktree via `lsof -p <pid> -d cwd`. If sibling worktree: tear that down first (`OTDF_LOCAL_INSTANCE_NAME=<other> otdf-local down`). If same worktree, stale binary: `otdf-sdk-mgr install tip --ref <expected-ref> platform` then restart. |
 | `EXTRA` | Confirm the PID and its cwd. Stop owning instance or kill the stale PID. |
-| `empty-dir` / `missing` | Re-run `bootstrap-pr-worktree.sh` (Phase B of `scenario-up`) or hand-run `bash .github/scripts/init-temp-keys.sh` in the worktree. |
+| `missing` / `empty` (seed file) | Re-run `otdf-local instance init <name> --from-scenario <path>`. Existing files are preserved; only the missing seed gets regenerated. |
 
 ### Step 5 — Output
 
@@ -86,9 +86,10 @@ For the simpler "what's defined / what's listening here" question without the di
 
 ## Additional Resources
 
-### Script
+### Scripts
 
 - **`scripts/diff-running-vs-intended.sh`** — automates Step 1's expected-vs-actual diff. Takes one positional argument: the instance name. Tab-separated stdout.
+- **`scripts/check-instance-seed.sh`** — read-only verifier for Step 2. Takes one positional argument: the instance name. Confirms `keys/{ca.jks,localhost.crt,localhost.key}`, `keys/kas-*.pem`, and `opentdf.yaml` (with a non-empty `services.kas.root_key`) are present in `tests/instances/<name>/`. Tab-separated stdout.
 
 ### Reference files
 
diff --git a/.claude/skills/scenario-doctor/scripts/check-instance-seed.sh b/.claude/skills/scenario-doctor/scripts/check-instance-seed.sh
new file mode 100644
index 000000000..98b30f681
--- /dev/null
+++ b/.claude/skills/scenario-doctor/scripts/check-instance-seed.sh
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# check-instance-seed.sh — read-only verifier that `otdf-local instance init`
+# left the instance dir with the seed bundle `up` and pytest expect.
+#
+# Usage: check-instance-seed.sh <instance-name>
+#
+# `instance init` self-provisions: keys/{ca.jks,localhost.crt,localhost.key},
+# keys/kas-{private,cert,ec-private,ec-cert}.pem, and instances/<name>/opentdf.yaml
+# with a generated services.kas.root_key. This script confirms each is present
+# and reports tab-separated rows; it does not modify anything.
+#
+# Output: tab-separated, header on first line.
+# Columns: artifact  state  detail
+#   state ∈ { ok | missing | empty }
+
+set -u
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: $(basename "$0") <instance-name>" >&2
+  exit 2
+fi
+
+name="$1"
+
+# Resolve repo root by walking up from $PWD until we find the tests/ marker.
+dir="$PWD"
+while [[ "$dir" != "/" && ! -d "$dir/instances" ]]; do dir="$(dirname "$dir")"; done
+if [[ ! -d "$dir/instances" ]]; then
+  echo "could not locate tests/instances/ above $PWD" >&2
+  exit 2
+fi
+instance_dir="$dir/instances/$name"
+if [[ ! -d "$instance_dir" ]]; then
+  echo "instance not found: $instance_dir" >&2
+  exit 2
+fi
+
+REQUIRED_FILES=(
+  keys/ca.jks
+  keys/localhost.crt
+  keys/localhost.key
+  keys/kas-private.pem
+  keys/kas-cert.pem
+  keys/kas-ec-private.pem
+  keys/kas-ec-cert.pem
+  opentdf.yaml
+)
+
+printf 'artifact\tstate\tdetail\n'
+
+for f in "${REQUIRED_FILES[@]}"; do
+  path="$instance_dir/$f"
+  if [[ ! -e "$path" ]]; then
+    printf '%s\tmissing\t-\n' "$f"
+  elif [[ -d "$path" ]]; then
+    printf '%s\tempty\tdirectory leftover (docker bind-mount stub)\n' "$f"
+  elif [[ ! -s "$path" ]]; then
+    printf '%s\tempty\tzero bytes\n' "$f"
+  else
+    printf '%s\tok\t-\n' "$f"
+  fi
+done
+
+# Confirm the per-instance root_key got written into opentdf.yaml.
+config="$instance_dir/opentdf.yaml"
+if [[ -f "$config" ]]; then
+  if command -v yq >/dev/null 2>&1; then
+    rk="$(yq -r '.services.kas.root_key // ""' "$config" 2>/dev/null)"
+  else
+    rk="$(grep -E '^[[:space:]]*root_key:' "$config" 2>/dev/null | head -1 | sed -E 's/.*root_key:[[:space:]]*"?([^"[:space:]]+)"?.*/\1/')"
+  fi
+  if [[ -z "$rk" || "$rk" == "null" ]]; then
+    printf '%s\tmissing\troot_key empty in opentdf.yaml\n' "services.kas.root_key"
+  else
+    printf '%s\tok\t-\n' "services.kas.root_key"
+  fi
+fi
diff --git a/.claude/skills/scenario-from-ticket/SKILL.md b/.claude/skills/scenario-from-ticket/SKILL.md
index 5743e5f6f..8daff3da8 100644
--- a/.claude/skills/scenario-from-ticket/SKILL.md
+++ b/.claude/skills/scenario-from-ticket/SKILL.md
@@ -95,7 +95,7 @@ The ticket asks an open question or lacks enough concrete behavior to encode. Do
 grep -rn "<key_term>" xtest/test_*.py xtest/tdfs.py
 ```
 
-Likely candidates: `test_tdfs.py` (roundtrip), `test_abac.py` (ABAC), `test_legacy.py` (golden), `test_pqc.py`. If a test already asserts the relevant behavior, reuse it via `suite.select` — no draft test needed.
+Likely candidates: `test_tdfs.py` (roundtrip), `test_abac.py` (ABAC), `test_legacy.py` (golden), `test_pqc.py`. If a test already asserts the relevant behavior, reuse it via `suite.targets` (list of pytest selectors) — no draft test needed.
 
 **Don't grep `xtest/sdk/<lang>/cli.sh`.** Those wrappers are reusable infrastructure (versioned alongside each SDK dist) and their contents have nothing to do with scenario YAML fields. The scenario doesn't need to know HOW a feature is plumbed — only WHICH pytest suite exercises it. If a feature's `supports("<name>")` gate isn't in `tdfs.py` yet, that's a signal that supporting infrastructure has to land separately from the scenario — note it in `actual:` and move on.
 
diff --git a/.claude/skills/scenario-run/SKILL.md b/.claude/skills/scenario-run/SKILL.md
index f141e9617..7bd3a360a 100644
--- a/.claude/skills/scenario-run/SKILL.md
+++ b/.claude/skills/scenario-run/SKILL.md
@@ -21,7 +21,7 @@ Invoke the pytest selection declared by the scenario's `suite` block against the
 uv run otdf-local scenario run xtest/scenarios/<id>.yaml
 ```
 
-This translates the scenario's `suite.select`, `suite.containers`, `suite.markers`, and `sdks.{encrypt,decrypt}` into the equivalent `pytest --sdks-encrypt … --sdks-decrypt … --containers …` invocation under `xtest/` with `OTDF_LOCAL_INSTANCE_NAME` set. SDK tokens are emitted in xtest's `sdk@version` form; the resolved version names come from the sibling `<scenario>.installed.json`.
+This translates the scenario's `suite.targets` (list — each entry becomes a positional pytest arg), `suite.containers` (list — joined into a single whitespace-separated `--containers` value), `suite.kexpr`, `suite.markers`, and `sdks.{encrypt,decrypt}` into the equivalent `pytest <targets…> --sdks-encrypt … --sdks-decrypt … --containers …` invocation under `xtest/` with `OTDF_LOCAL_INSTANCE_NAME` set. SDK tokens are emitted in xtest's `sdk@version` form; the resolved version names come from the sibling `<scenario>.installed.json`.
 
 Failure modes:
 - `Error: <path>.installed.json not found` — the user skipped Step 1 of `scenario-up`. Run `uv run otdf-sdk-mgr install scenario <path>` first.
@@ -41,10 +41,10 @@ set +a
 # Map each source-pinned SDK to its dist slug under xtest/sdk/<lang>/dist/.
 # For platform PR #N, the slug is typically `refs--pull--<N>--head`.
 PLATFORM_VERSION=<future-version> OTDFCTL_HEADS='["<go-dist-slug>"]' \
-  uv run pytest <suite.select> \
+  uv run pytest <suite.targets...> \
     --sdks-encrypt <lang>@<dist-slug> \
     --sdks-decrypt <lang>@<dist-slug> \
-    --containers <suite.containers>
+    --containers "<suite.containers joined by space>"
 ```
 
 `PLATFORM_VERSION` and `OTDFCTL_HEADS` defaults are noted in `scenario-up`; pull them from there or from the scenario's source-build env knobs section. This fallback is temporary — tracked at [DSPX-3417](https://virtru.atlassian.net/browse/DSPX-3417) (scenario YAML accepting source builds) and [DSPX-3418](https://virtru.atlassian.net/browse/DSPX-3418) (`OTDFCTL_HEADS` → CLI flag).
@@ -77,7 +77,7 @@ Pytest leaves logs under `tests/instances/<id>/logs/`. List the relevant per-ser
 ## Output format
 
 One-line headline naming the bucket, then a short bulleted summary:
-- `select:` the pytest selector that ran
+- `targets:` the pytest selectors that ran (one per `suite.targets` entry)
 - `exit_code:` the pytest return value
 - `evidence:` 1–2 lines from the output that justify the classification
 - `logs:` paths to the relevant per-service logs
diff --git a/.claude/skills/scenario-up/SKILL.md b/.claude/skills/scenario-up/SKILL.md
index 45050fe71..ebbe9f267 100644
--- a/.claude/skills/scenario-up/SKILL.md
+++ b/.claude/skills/scenario-up/SKILL.md
@@ -45,21 +45,7 @@ First `go build` per platform version takes ~30–60s; subsequent runs reuse the
 uv run otdf-local instance init <id> --from-scenario xtest/scenarios/<id>.yaml
 ```
 
-Creates `tests/instances/<id>/`. If the instance already exists, the command is a no-op for existing files. Double-check with `uv run otdf-local instance ls` first to avoid surprising the user with overwrites.
-
-### Step 2.5 — Bootstrap PR worktrees (when source-pinned)
-
-A freshly built PR worktree from `install tip --ref pr:N` ships *templates* but not generated dev keys, and lacks the `opentdf.yaml` filename `otdf-local` expects. Running `up` against it produces cryptic Docker "Is a directory" and platform "no such file" errors. Pre-flight the seed files:
-
-```bash
-bash ${CLAUDE_PLUGIN_ROOT:-.}/skills/scenario-up/scripts/bootstrap-pr-worktree.sh xtest/scenarios/<id>.yaml
-```
-
-Script behaviour: for each `source.ref` pin in the scenario, resolve the dist's worktree via its `.version` sidecar; check that `kas-*.pem`, `keys/{ca.jks,localhost.crt,localhost.key}`, and `opentdf.yaml` exist as *files* (not Docker-created empty dirs). On miss it generates / copies from `xtest/platform/src/main/` / suggests `bash .github/scripts/init-temp-keys.sh`. Output is tab-separated; review the rows where `action != kept` before proceeding.
-
-Skip this step for scenarios pinned entirely on `dist:` (released versions) — those use pre-baked artifacts and don't need seeding.
-
-[DSPX-3416](https://virtru.atlassian.net/browse/DSPX-3416) tracks moving this bootstrap into `otdf-local up` itself. Until it lands, run the script.
+Creates `tests/instances/<id>/` and **self-provisions the bootstrap bundle**: generates the Keycloak TLS pair + `keys/ca.jks` truststore, creates `kas-*.pem` keys, and copies the platform's `opentdf-dev.yaml` (or `opentdf-example.yaml`) into `instances/<id>/opentdf.yaml` with a freshly generated `services.kas.root_key`. Idempotent — existing files are preserved, so the per-instance root key survives re-runs. Double-check with `uv run otdf-local instance ls` first to avoid surprising the user with overwrites.
 
 ### Step 3 — Bring it up
 
@@ -75,6 +61,14 @@ uv run otdf-local --instance <id> status --json
 
 If any service stays unhealthy after ~60 seconds, surface the relevant log via `uv run otdf-local --instance <id> logs <service> -n 50` and report the failure mode rather than retrying blindly.
 
+Once healthy, sanity-check the env exports `scenario-run` will rely on:
+
+```bash
+uv run otdf-local --instance <id> env --format json | jq '{PLATFORM_DIR,PLATFORMURL,SCHEMA_FILE,OT_ROOT_KEY}'
+```
+
+All four must be non-null. If `OT_ROOT_KEY` is null, the instance's `opentdf.yaml` is missing or didn't get a `services.kas.root_key` written (re-run `instance init` to refresh).
+
 ## Source-build env knobs
 
 When the scenario pins source-built artifacts (`source.ref` on platform / KAS / SDKs), two env-var overrides are temporarily required for `scenario-run`. Note them now so the user has them ready:
@@ -95,11 +89,4 @@ These workarounds are tracked at [DSPX-3418](https://virtru.atlassian.net/browse
 Once healthy, report:
 - The instance name and which ports it occupies (look at `instance.yaml`'s `ports.base`).
 - The path to `<id>.installed.json` (so `scenario-run` can find it).
-- Any unusual rows from the bootstrap probe (e.g. "seeded `keys/ca.jks` from main worktree").
 - The next command the user is likely to run: `scenario-run xtest/scenarios/<id>.yaml`.
-
-## Additional Resources
-
-### Script
-
-- **`scripts/bootstrap-pr-worktree.sh`** — pre-flights a PR worktree's seed files before `otdf-local up`. Takes one positional argument: the scenario YAML path. Tab-separated stdout. Idempotent — safe to re-run.
diff --git a/.claude/skills/scenario-up/scripts/bootstrap-pr-worktree.sh b/.claude/skills/scenario-up/scripts/bootstrap-pr-worktree.sh
deleted file mode 100755
index 72a97bdd6..000000000
--- a/.claude/skills/scenario-up/scripts/bootstrap-pr-worktree.sh
+++ /dev/null
@@ -1,131 +0,0 @@
-#!/usr/bin/env bash
-# bootstrap-pr-worktree.sh — ensure platform source worktrees referenced by a
-# scenario have the seed files otdf-local + docker-compose expect.
-#
-# Usage: bootstrap-pr-worktree.sh <path-to-scenario.yaml>
-#
-# A fresh `otdf-sdk-mgr install tip --ref <ref> platform` produces the
-# /service binary and a populated git worktree at xtest/platform/src/<slug>/,
-# but it does NOT generate the dev keys (kas-*.pem, keys/ca.jks, …) or copy
-# opentdf-dev.yaml → opentdf.yaml. `otdf-local up` then fails in cryptic
-# ways (Keycloak "Is a directory", platform "no such file"). This script
-# pre-flights each referenced worktree and either bootstraps or fails loudly
-# with the exact remedy.
-#
-# Output: tab-separated, header on first line.
-# Columns: worktree  file  state  action
-#   state ∈ { ok | missing | empty-dir }
-#   action ∈ { kept | generated | copied | manual-required }
-
-set -u
-
-if [[ $# -lt 1 ]]; then
-  echo "usage: $(basename "$0") <scenario.yaml>" >&2
-  exit 2
-fi
-
-scenario="$1"
-[[ -f "$scenario" ]] || { echo "scenario not found: $scenario" >&2; exit 2; }
-
-# Resolve repo root (the dir containing xtest/) by walking up from $scenario.
-dir="$(cd "$(dirname "$scenario")" && pwd)"
-while [[ "$dir" != "/" && ! -d "$dir/xtest" ]]; do dir="$(dirname "$dir")"; done
-[[ -d "$dir/xtest" ]] || { echo "could not locate xtest/ above $scenario" >&2; exit 2; }
-PLATFORM_DIST="$dir/xtest/platform/dist"
-
-# Files each worktree needs. Order matters for the action log — opentdf.yaml
-# last so its "copied from opentdf-dev.yaml" message lands after the keys.
-REQUIRED_FILES=(
-  kas-private.pem
-  kas-cert.pem
-  kas-ec-private.pem
-  kas-ec-cert.pem
-  keys/ca.jks
-  keys/localhost.crt
-  keys/localhost.key
-  opentdf.yaml
-)
-
-# Extract referenced refs from the scenario. We tolerate yq presence/absence:
-# prefer `yq -r` when available, fall back to a grep that handles the two
-# shapes we emit (`ref: pr:3537` inline and `{ ref: pr:3537 }` flow-style).
-refs=()
-if command -v yq >/dev/null 2>&1; then
-  while IFS= read -r r; do [[ -n "$r" && "$r" != "null" ]] && refs+=("$r"); done < <(
-    yq -r '
-      [ .instance.platform.source.ref?,
-        (.instance.kas[]?.source.ref?)
-      ] | .[] | select(. != null)
-    ' "$scenario" 2>/dev/null | sort -u
-  )
-else
-  while IFS= read -r r; do refs+=("$r"); done < <(
-    grep -E '\{?\s*ref:' "$scenario" | sed -E 's/.*ref:[[:space:]]*"?([^",}[:space:]]+)"?.*/\1/' | sort -u
-  )
-fi
-
-if [[ ${#refs[@]} -eq 0 ]]; then
-  echo "no source.ref pins found in $scenario (dist-only scenario, nothing to bootstrap)" >&2
-  exit 0
-fi
-
-printf 'worktree\tfile\tstate\taction\n'
-
-for ref in "${refs[@]}"; do
-  # Slug used by otdf-sdk-mgr: replace `/` and `:` with `--`. Mutable refs
-  # like `main`, `pr:3537` get slugs `main`, `refs--pull--3537--head` (the
-  # `pr:N` shorthand expands inside the installer). Read the .version sidecar
-  # to get the canonical worktree path rather than guess.
-  dist_dir=""
-  for slug_candidate in "$PLATFORM_DIST"/*/; do
-    [[ -f "$slug_candidate/.version" ]] || continue
-    if grep -Fq "ref=$ref" "$slug_candidate/.version" || grep -Fq "ref=refs/pull/${ref#pr:}/head" "$slug_candidate/.version"; then
-      dist_dir="${slug_candidate%/}"; break
-    fi
-  done
-  if [[ -z "$dist_dir" ]]; then
-    printf '%s\t-\tmissing\tmanual-required\n' "$ref"
-    echo "no dist dir found for ref=$ref; run 'otdf-sdk-mgr install tip --ref $ref platform' first" >&2
-    continue
-  fi
-  worktree="$(awk -F= '/^worktree=/ {print $2}' "$dist_dir/.version")"
-  [[ -d "$worktree" ]] || { printf '%s\t.version\tmissing\tmanual-required\n' "$ref"; continue; }
-
-  for f in "${REQUIRED_FILES[@]}"; do
-    path="$worktree/$f"
-    if [[ -f "$path" ]]; then
-      printf '%s\t%s\tok\tkept\n' "$worktree" "$f"
-      continue
-    fi
-    if [[ -d "$path" ]]; then
-      # Docker bind-mount created an empty dir on a prior failed up. Remove it
-      # so the bootstrap fill below can replace it with a real file.
-      rmdir "$path" 2>/dev/null || true
-      printf '%s\t%s\tempty-dir\tremoved\n' "$worktree" "$f"
-    fi
-
-    # Fill rules:
-    #   opentdf.yaml: cp opentdf-dev.yaml → opentdf.yaml (legacy template name).
-    #   everything else: try copying from xtest/platform/src/main/, else fail.
-    if [[ "$f" == "opentdf.yaml" && -f "$worktree/opentdf-dev.yaml" ]]; then
-      cp "$worktree/opentdf-dev.yaml" "$path"
-      printf '%s\t%s\tmissing\tcopied(opentdf-dev.yaml)\n' "$worktree" "$f"
-      continue
-    fi
-
-    main_dir="$dir/xtest/platform/src/main"
-    if [[ -f "$main_dir/$f" ]]; then
-      mkdir -p "$(dirname "$path")"
-      cp "$main_dir/$f" "$path"
-      printf '%s\t%s\tmissing\tcopied(main)\n' "$worktree" "$f"
-      continue
-    fi
-
-    printf '%s\t%s\tmissing\tmanual-required\n' "$worktree" "$f"
-    cat >&2 <<EOF
-missing: $path
-  remedy: cd "$worktree" && bash .github/scripts/init-temp-keys.sh
-          (run from inside the worktree; generates kas-*.pem and keys/*)
-EOF
-  done
-done

From d3caf8143e68530269ba985e8a4a1fbbaedd9cfa Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 2 Jun 2026 13:44:43 -0400
Subject: [PATCH 27/64] fix(.claude/skills): add --instance parameter to
 scenario run examples

Ensures consistency with other otdf-local commands (up, down, status, logs)
that already show the --instance parameter. While scenario run has a default
that reads from the YAML, explicitly including --instance makes examples
self-documenting and prevents confusion.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .claude/skills/scenario-matrix/SKILL.md | 2 +-
 .claude/skills/scenario-run/SKILL.md    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/scenario-matrix/SKILL.md b/.claude/skills/scenario-matrix/SKILL.md
index 9e4bbd90c..b5e239535 100644
--- a/.claude/skills/scenario-matrix/SKILL.md
+++ b/.claude/skills/scenario-matrix/SKILL.md
@@ -78,7 +78,7 @@ Bail (delete the just-written files) if any cell fails validation — partial ma
     uv run otdf-sdk-mgr install scenario "$f"
     uv run otdf-local instance init "$name" --from-scenario "$f"
     uv run otdf-local --instance "$name" up
-    uv run otdf-local scenario run "$f"
+    uv run otdf-local scenario run --instance "$name" "$f"
     uv run otdf-local --instance "$name" down
   done
   ```
diff --git a/.claude/skills/scenario-run/SKILL.md b/.claude/skills/scenario-run/SKILL.md
index 7bd3a360a..e533145bf 100644
--- a/.claude/skills/scenario-run/SKILL.md
+++ b/.claude/skills/scenario-run/SKILL.md
@@ -18,7 +18,7 @@ Invoke the pytest selection declared by the scenario's `suite` block against the
 ### Step 1 — Invoke the runner
 
 ```bash
-uv run otdf-local scenario run xtest/scenarios/<id>.yaml
+uv run otdf-local scenario run --instance <id> xtest/scenarios/<id>.yaml
 ```
 
 This translates the scenario's `suite.targets` (list — each entry becomes a positional pytest arg), `suite.containers` (list — joined into a single whitespace-separated `--containers` value), `suite.kexpr`, `suite.markers`, and `sdks.{encrypt,decrypt}` into the equivalent `pytest <targets…> --sdks-encrypt … --sdks-decrypt … --containers …` invocation under `xtest/` with `OTDF_LOCAL_INSTANCE_NAME` set. SDK tokens are emitted in xtest's `sdk@version` form; the resolved version names come from the sibling `<scenario>.installed.json`.

From de2ee7473e8cfd3f3b307363e5ed9d724902c315 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 09:35:31 -0400
Subject: [PATCH 28/64] fix(install,up,doctor): ensure otdf-sdk-mgr builds are
 used (DSPX-3302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Systemic fix for the workflow where `otdf-sdk-mgr install` builds binaries
but `otdf-local` doesn't use them, falling back to stale `go run` from source.

**Phase 1: otdf-sdk-mgr auto-converts source → dist**
- After successful platform build, `install scenario` now updates instance.yaml
- Converts `platform.source.ref` → `platform.dist: <slug>`
- Uses dump_instance() to persist the change
- User sees: "Updating instance to use platform dist: refs--heads--..."

**Phase 2: otdf-local warns on source mode**
- Before launching platform, checks if `instance.platform.source` is set
- Emits structured warning with instance name, ref, and fix command
- Helps users diagnose why changes aren't appearing

**Phase 3: scenario-doctor detects source mode**
- diff-running-vs-intended.sh now checks for platform.source before diff table
- Emits actionable warning: "run otdf-sdk-mgr install scenario <path>"
- Fixed bash compatibility issue (requires bash 5+ for associative arrays)

This ensures the "install → use" workflow works correctly without manual
intervention.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .../scripts/diff-running-vs-intended.sh          | 16 +++++++++++++++-
 otdf-local/src/otdf_local/services/platform.py   | 11 +++++++++++
 otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py    | 10 ++++++++++
 3 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
index b7ff9f118..6e5f65915 100755
--- a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -35,7 +35,8 @@ done
 inst="$INST_ROOT/$name/instance.yaml"
 [[ -f "$inst" ]] || { echo "no instance.yaml at $inst" >&2; exit 2; }
 
-PLATFORM_DIST="${INST_ROOT%/instances}/xtest/platform/dist"
+INST_DIR_PARENT="${INST_ROOT%/instances}"
+PLATFORM_DIST="$INST_DIR_PARENT/xtest/platform/dist"
 
 # Port map (matches otdf-local's Ports defaults).
 declare -A PORT_OF=(
@@ -99,6 +100,19 @@ get_pin() {
 
 printf 'service\tport\texpected_sha\tactual_sha\thealth\tstatus\n'
 
+# Check if platform is configured for source mode (pre-PR#510 instances).
+platform_uses_source=0
+if command -v yq >/dev/null 2>&1; then
+  [[ -n "$(yq -r '.platform.source.ref // ""' "$inst")" ]] && platform_uses_source=1
+else
+  grep -q 'source:' "$inst" && platform_uses_source=1
+fi
+if [[ "$platform_uses_source" == 1 ]]; then
+  echo "⚠️  WARNING: instance uses platform.source; binary builds are ignored" >&2
+  echo "    Run: otdf-sdk-mgr install scenario $inst" >&2
+  echo "    This will update instance.yaml to use platform.dist" >&2
+fi
+
 # Platform first.
 pin="$(get_pin .platform)"
 exp="$(expected_sha_for "$pin")"
diff --git a/otdf-local/src/otdf_local/services/platform.py b/otdf-local/src/otdf_local/services/platform.py
index 66d61b820..390f44b1d 100644
--- a/otdf-local/src/otdf_local/services/platform.py
+++ b/otdf-local/src/otdf_local/services/platform.py
@@ -149,6 +149,17 @@ def start(self) -> bool:
 
         # Build the command — pinned binary when an instance is loaded,
         # legacy `go run ./service` otherwise.
+        instance = self.settings.load_instance()
+        if instance and instance.platform.source:
+            self.logger.warning(
+                "instance uses platform.source; binary builds are ignored",
+                extra={
+                    "instance": instance.metadata.name or self.settings.instance,
+                    "ref": instance.platform.source.ref,
+                    "hint": "run 'otdf-sdk-mgr install scenario <instance.yaml>' to use built binary",
+                },
+            )
+
         instance_paths = self._instance_dist_paths()
         if instance_paths is not None:
             binary, worktree = instance_paths
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py
index 0884e69a3..d8f26e276 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py
@@ -29,6 +29,7 @@
     KasPin,
     PlatformPin,
     Scenario,
+    dump_instance,
     load_yaml_mapping,
 )
 
@@ -105,6 +106,15 @@ def _snapshot(status: str | None = None) -> dict[str, object]:
         if not skip_scripts:
             install_helper_scripts()
 
+        # Convert platform.source → platform.dist after successful build
+        # so otdf-local uses the built binary instead of falling back to go run
+        if instance.platform.source is not None:
+            assert isinstance(installed_platform, dict)
+            dist_name = Path(str(installed_platform["path"])).name
+            typer.echo(f"  Updating instance to use platform dist: {dist_name}")
+            instance.platform = PlatformPin(dist=dist_name)
+            dump_instance(instance, path)
+
         if scenario is not None:
             install_paths: dict[tuple[str, str, str | None], str] = {}
             for entry in scenario.sdks.union():

From 329cd9f1a27ed405d3e5211f9aff2c3b8daff437 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 13:23:16 -0400
Subject: [PATCH 29/64] fixup cleanups

---
 .../skills/instance-status/scripts/cross-worktree-probe.sh    | 2 +-
 .../scenario-doctor/scripts/diff-running-vs-intended.sh       | 1 -
 otdf-sdk-mgr/tests/test_schema_sync.py                        | 4 +---
 3 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
index baed227f9..1e91c95ba 100755
--- a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
+++ b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
@@ -36,7 +36,7 @@ for port in "${PORTS[@]}"; do
     esac
     # Refine kind if process command says otherwise (e.g. a misbound port).
     case "$cmd" in
-      *"/service "*|*"/service start"*) kind=platform ;;
+      *"/service "*) kind=platform ;;
       *opentdf-kas*|*"kas start"*) kind=kas ;;
     esac
 
diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
index 6e5f65915..c7a9257f8 100755
--- a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -52,7 +52,6 @@ declare -A PORT_OF=(
 # Helper: resolve a pin (ref or dist) to expected_sha by reading .version.
 expected_sha_for() {
   local pin="$1"  # could be a ref like 'main' or 'pr:3537', or a dist slug
-  local slug
   for cand in "$PLATFORM_DIST"/*/; do
     [[ -f "$cand/.version" ]] || continue
     if grep -Fq "ref=$pin" "$cand/.version" \
diff --git a/otdf-sdk-mgr/tests/test_schema_sync.py b/otdf-sdk-mgr/tests/test_schema_sync.py
index addeaf8ad..7e950a9cb 100644
--- a/otdf-sdk-mgr/tests/test_schema_sync.py
+++ b/otdf-sdk-mgr/tests/test_schema_sync.py
@@ -27,9 +27,7 @@ def _xtest_schema_dir() -> Path:
 @pytest.mark.parametrize(("model", "filename"), SCHEMAS, ids=lambda v: getattr(v, "__name__", v))
 def test_committed_schema_matches_model(model: type, filename: str) -> None:
     path = _xtest_schema_dir() / filename
-    assert path.is_file(), (
-        f"Missing {path}. Run `uv run otdf-sdk-mgr schema dump` to regenerate."
-    )
+    assert path.is_file(), f"Missing {path}. Run `uv run otdf-sdk-mgr schema dump` to regenerate."
     expected = render(model)
     actual = path.read_text(encoding="utf-8")
     assert actual == expected, (

From ee7e302494ba8b897612017180196e822be37b0f Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 13:35:57 -0400
Subject: [PATCH 30/64] style(.claude/skills): format all shell scripts with
 shfmt

- Format bash code block in scenario-tear-down SKILL.md
- Format cross-worktree-probe.sh (case statement indentation, pipe operators)
- Format diff-running-vs-intended.sh (compound commands, line continuations)
- All changes follow .editorconfig: 2-space indent, bash variant, function braces on same line
- Passes shellcheck validation

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 .../scripts/cross-worktree-probe.sh           | 18 ++++----
 .../scripts/diff-running-vs-intended.sh       | 43 +++++++++++++------
 .claude/skills/scenario-tear-down/SKILL.md    |  8 ++--
 3 files changed, 42 insertions(+), 27 deletions(-)

diff --git a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
index 1e91c95ba..a9e62c938 100755
--- a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
+++ b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
@@ -28,16 +28,16 @@ for port in "${PORTS[@]}"; do
 
     cmd="$(ps -o command= -p "$pid" 2>/dev/null | head -c 200)"
     case "$port" in
-      8080) kind=platform ;;
-      8181|8282|8383|8484|8585|8686) kind=kas ;;
-      8888) kind=docker-keycloak ;;
-      5432) kind=docker-postgres ;;
-      *)    kind=unknown ;;
+    8080) kind=platform ;;
+    8181 | 8282 | 8383 | 8484 | 8585 | 8686) kind=kas ;;
+    8888) kind=docker-keycloak ;;
+    5432) kind=docker-postgres ;;
+    *) kind=unknown ;;
     esac
     # Refine kind if process command says otherwise (e.g. a misbound port).
     case "$cmd" in
-      *"/service "*) kind=platform ;;
-      *opentdf-kas*|*"kas start"*) kind=kas ;;
+    *"/service "*) kind=platform ;;
+    *opentdf-kas* | *"kas start"*) kind=kas ;;
     esac
 
     printf '%s\ttcp\t%s\t%s\t%s\n' "$port" "$pid" "$cwd" "$kind"
@@ -51,7 +51,7 @@ done
 docker ps --format '{{.Names}}' 2>/dev/null | while IFS= read -r name; do
   [[ -z "$name" ]] && continue
   case "$name" in
-    *-keycloak-*)  printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
-    *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
+  *-keycloak-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
+  *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
   esac
 done | sort -u
diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
index c7a9257f8..e25073bea 100755
--- a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -33,7 +33,10 @@ done
 : "${INST_ROOT:?could not locate tests/instances/ above $PWD}"
 
 inst="$INST_ROOT/$name/instance.yaml"
-[[ -f "$inst" ]] || { echo "no instance.yaml at $inst" >&2; exit 2; }
+[[ -f "$inst" ]] || {
+  echo "no instance.yaml at $inst" >&2
+  exit 2
+}
 
 INST_DIR_PARENT="${INST_ROOT%/instances}"
 PLATFORM_DIST="$INST_DIR_PARENT/xtest/platform/dist"
@@ -51,12 +54,12 @@ declare -A PORT_OF=(
 
 # Helper: resolve a pin (ref or dist) to expected_sha by reading .version.
 expected_sha_for() {
-  local pin="$1"  # could be a ref like 'main' or 'pr:3537', or a dist slug
+  local pin="$1" # could be a ref like 'main' or 'pr:3537', or a dist slug
   for cand in "$PLATFORM_DIST"/*/; do
     [[ -f "$cand/.version" ]] || continue
-    if grep -Fq "ref=$pin" "$cand/.version" \
-      || grep -Fq "ref=refs/pull/${pin#pr:}/head" "$cand/.version" \
-      || [[ "$(basename "${cand%/}")" == "$pin" ]]; then
+    if grep -Fq "ref=$pin" "$cand/.version" ||
+      grep -Fq "ref=refs/pull/${pin#pr:}/head" "$cand/.version" ||
+      [[ "$(basename "${cand%/}")" == "$pin" ]]; then
       awk -F= '/^sha=/ {print substr($2,1,12); exit}' "$cand/.version"
       return
     fi
@@ -69,9 +72,15 @@ actual_sha_for_port() {
   local port="$1"
   local pid binary version
   pid="$(lsof -nP -iTCP:"$port" -sTCP:LISTEN 2>/dev/null | awk 'NR>1 {print $2; exit}')"
-  [[ -z "$pid" ]] && { echo ""; return; }
+  [[ -z "$pid" ]] && {
+    echo ""
+    return
+  }
   binary="$(ps -o command= -p "$pid" 2>/dev/null | awk '{print $1}')"
-  [[ -f "$binary" ]] || { echo "?"; return; }
+  [[ -f "$binary" ]] || {
+    echo "?"
+    return
+  }
   version="$(dirname "$binary")/.version"
   [[ -f "$version" ]] && awk -F= '/^sha=/ {print substr($2,1,12); exit}' "$version" || echo "?"
 }
@@ -84,7 +93,7 @@ health_of() {
 
 # Extract pins from instance.yaml. yq optional; fall back to grep.
 get_pin() {
-  local field="$1"   # e.g. .platform OR .kas.km1
+  local field="$1" # e.g. .platform OR .kas.km1
   if command -v yq >/dev/null 2>&1; then
     yq -r "($field.source.ref? // $field.dist? // \"\")" "$inst"
   else
@@ -117,9 +126,12 @@ pin="$(get_pin .platform)"
 exp="$(expected_sha_for "$pin")"
 act="$(actual_sha_for_port 8080)"
 hc="$(health_of 8080)"
-if [[ -z "$pin" ]]; then status=NO-PIN
-elif [[ -z "$act" ]]; then status=NOT-RUNNING
-elif [[ "$act" == "$exp" ]]; then status=MATCH
+if [[ -z "$pin" ]]; then
+  status=NO-PIN
+elif [[ -z "$act" ]]; then
+  status=NOT-RUNNING
+elif [[ "$act" == "$exp" ]]; then
+  status=MATCH
 else status=WRONG-BINARY; fi
 printf 'platform\t8080\t%s\t%s\t%s\t%s\n' "${exp:-?}" "${act:--}" "$hc" "$status"
 
@@ -140,9 +152,12 @@ for kas in "${kas_names[@]}"; do
   exp="$(expected_sha_for "$pin")"
   act="$(actual_sha_for_port "$port")"
   hc="$([[ "$port" != "?" ]] && health_of "$port" || echo -)"
-  if [[ -z "$pin" ]]; then status=NO-PIN
-  elif [[ -z "$act" ]]; then status=NOT-RUNNING
-  elif [[ "$act" == "$exp" ]]; then status=MATCH
+  if [[ -z "$pin" ]]; then
+    status=NO-PIN
+  elif [[ -z "$act" ]]; then
+    status=NOT-RUNNING
+  elif [[ "$act" == "$exp" ]]; then
+    status=MATCH
   else status=WRONG-BINARY; fi
   printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$kas" "$port" "${exp:-?}" "${act:--}" "$hc" "$status"
 done
diff --git a/.claude/skills/scenario-tear-down/SKILL.md b/.claude/skills/scenario-tear-down/SKILL.md
index a37b5fbcb..cd992db81 100644
--- a/.claude/skills/scenario-tear-down/SKILL.md
+++ b/.claude/skills/scenario-tear-down/SKILL.md
@@ -20,10 +20,10 @@ Stop a running scenario cleanly and optionally remove its on-disk state. Confirm
 Before stopping anything, list the docker compose projects currently sharing the host daemon:
 
 ```bash
-docker ps --format '{{.Names}}' \
-  | grep -E -- '-keycloak-|-opentdfdb-' \
-  | sed -E 's/-(keycloak|opentdfdb)-[0-9]+$//' \
-  | sort -u
+docker ps --format '{{.Names}}' |
+	grep -E -- '-keycloak-|-opentdfdb-' |
+	sed -E 's/-(keycloak|opentdfdb)-[0-9]+$//' |
+	sort -u
 ```
 
 Each line is a compose-project name — typically the directory name where `docker compose` was invoked (a worktree's `xtest/platform/src/<slug>/`). If more than one project appears, surface this in the reply: `down` will *keep* docker keycloak/postgres running because another instance still uses them. The user's expectation that "ports 5432 and 8888 are now free" would be wrong.

From 7291b3603b607a8f063f64813e16a67fab823cfe Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 13:43:43 -0400
Subject: [PATCH 31/64] fixup shfmt

---
 .../scripts/cross-worktree-probe.sh            | 18 +++++++++---------
 .../scripts/diff-running-vs-intended.sh        | 14 +++++++-------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
index a9e62c938..2d303d47a 100755
--- a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
+++ b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
@@ -28,16 +28,16 @@ for port in "${PORTS[@]}"; do
 
     cmd="$(ps -o command= -p "$pid" 2>/dev/null | head -c 200)"
     case "$port" in
-    8080) kind=platform ;;
-    8181 | 8282 | 8383 | 8484 | 8585 | 8686) kind=kas ;;
-    8888) kind=docker-keycloak ;;
-    5432) kind=docker-postgres ;;
-    *) kind=unknown ;;
+      8080) kind=platform ;;
+      8181 | 8282 | 8383 | 8484 | 8585 | 8686) kind=kas ;;
+      8888) kind=docker-keycloak ;;
+      5432) kind=docker-postgres ;;
+      *) kind=unknown ;;
     esac
     # Refine kind if process command says otherwise (e.g. a misbound port).
     case "$cmd" in
-    *"/service "*) kind=platform ;;
-    *opentdf-kas* | *"kas start"*) kind=kas ;;
+      *"/service "*) kind=platform ;;
+      *opentdf-kas* | *"kas start"*) kind=kas ;;
     esac
 
     printf '%s\ttcp\t%s\t%s\t%s\n' "$port" "$pid" "$cwd" "$kind"
@@ -51,7 +51,7 @@ done
 docker ps --format '{{.Names}}' 2>/dev/null | while IFS= read -r name; do
   [[ -z "$name" ]] && continue
   case "$name" in
-  *-keycloak-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
-  *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
+    *-keycloak-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
+    *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
   esac
 done | sort -u
diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
index e25073bea..e31ed4af8 100755
--- a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -43,13 +43,13 @@ PLATFORM_DIST="$INST_DIR_PARENT/xtest/platform/dist"
 
 # Port map (matches otdf-local's Ports defaults).
 declare -A PORT_OF=(
-  [platform]=8080
-  [alpha]=8181
-  [beta]=8282
-  [gamma]=8383
-  [delta]=8484
-  [km1]=8585
-  [km2]=8686
+   [platform]=8080
+   [alpha]=8181
+   [beta]=8282
+   [gamma]=8383
+   [delta]=8484
+   [km1]=8585
+   [km2]=8686
 )
 
 # Helper: resolve a pin (ref or dist) to expected_sha by reading .version.

From 17939cf63a5a33270ab2455b2f70b777e23d81f0 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 13:48:07 -0400
Subject: [PATCH 32/64] fixup shfmt

---
 .../scripts/diff-running-vs-intended.sh            | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
index e31ed4af8..7fe92c134 100755
--- a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -43,13 +43,13 @@ PLATFORM_DIST="$INST_DIR_PARENT/xtest/platform/dist"
 
 # Port map (matches otdf-local's Ports defaults).
 declare -A PORT_OF=(
-   [platform]=8080
-   [alpha]=8181
-   [beta]=8282
-   [gamma]=8383
-   [delta]=8484
-   [km1]=8585
-   [km2]=8686
+    [platform]=8080
+    [alpha]=8181
+    [beta]=8282
+    [gamma]=8383
+    [delta]=8484
+    [km1]=8585
+    [km2]=8686
 )
 
 # Helper: resolve a pin (ref or dist) to expected_sha by reading .version.

From 8b69e5701cf7f12476666caa6e1caa892e4419fb Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 13:58:04 -0400
Subject: [PATCH 33/64] Revert "fixup shfmt"

This reverts commit be25ebbbdd7514fc843f7ceb5b4fd42d709618a9.
---
 .../scripts/diff-running-vs-intended.sh            | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
index 7fe92c134..e31ed4af8 100755
--- a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -43,13 +43,13 @@ PLATFORM_DIST="$INST_DIR_PARENT/xtest/platform/dist"
 
 # Port map (matches otdf-local's Ports defaults).
 declare -A PORT_OF=(
-    [platform]=8080
-    [alpha]=8181
-    [beta]=8282
-    [gamma]=8383
-    [delta]=8484
-    [km1]=8585
-    [km2]=8686
+   [platform]=8080
+   [alpha]=8181
+   [beta]=8282
+   [gamma]=8383
+   [delta]=8484
+   [km1]=8585
+   [km2]=8686
 )
 
 # Helper: resolve a pin (ref or dist) to expected_sha by reading .version.

From 8278da5b1497b4298c4488a06af3677e98271118 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 13:58:04 -0400
Subject: [PATCH 34/64] Revert "fixup shfmt"

This reverts commit 1e90caf8bebad3af8b7f002440ad29e6d0f0fe9f.
---
 .../scripts/cross-worktree-probe.sh            | 18 +++++++++---------
 .../scripts/diff-running-vs-intended.sh        | 14 +++++++-------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
index 2d303d47a..a9e62c938 100755
--- a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
+++ b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
@@ -28,16 +28,16 @@ for port in "${PORTS[@]}"; do
 
     cmd="$(ps -o command= -p "$pid" 2>/dev/null | head -c 200)"
     case "$port" in
-      8080) kind=platform ;;
-      8181 | 8282 | 8383 | 8484 | 8585 | 8686) kind=kas ;;
-      8888) kind=docker-keycloak ;;
-      5432) kind=docker-postgres ;;
-      *) kind=unknown ;;
+    8080) kind=platform ;;
+    8181 | 8282 | 8383 | 8484 | 8585 | 8686) kind=kas ;;
+    8888) kind=docker-keycloak ;;
+    5432) kind=docker-postgres ;;
+    *) kind=unknown ;;
     esac
     # Refine kind if process command says otherwise (e.g. a misbound port).
     case "$cmd" in
-      *"/service "*) kind=platform ;;
-      *opentdf-kas* | *"kas start"*) kind=kas ;;
+    *"/service "*) kind=platform ;;
+    *opentdf-kas* | *"kas start"*) kind=kas ;;
     esac
 
     printf '%s\ttcp\t%s\t%s\t%s\n' "$port" "$pid" "$cwd" "$kind"
@@ -51,7 +51,7 @@ done
 docker ps --format '{{.Names}}' 2>/dev/null | while IFS= read -r name; do
   [[ -z "$name" ]] && continue
   case "$name" in
-    *-keycloak-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
-    *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
+  *-keycloak-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
+  *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
   esac
 done | sort -u
diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
index e31ed4af8..e25073bea 100755
--- a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -43,13 +43,13 @@ PLATFORM_DIST="$INST_DIR_PARENT/xtest/platform/dist"
 
 # Port map (matches otdf-local's Ports defaults).
 declare -A PORT_OF=(
-   [platform]=8080
-   [alpha]=8181
-   [beta]=8282
-   [gamma]=8383
-   [delta]=8484
-   [km1]=8585
-   [km2]=8686
+  [platform]=8080
+  [alpha]=8181
+  [beta]=8282
+  [gamma]=8383
+  [delta]=8484
+  [km1]=8585
+  [km2]=8686
 )
 
 # Helper: resolve a pin (ref or dist) to expected_sha by reading .version.

From db398f1623e79335e9d5871e39dbb46161c748ef Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 13:58:04 -0400
Subject: [PATCH 35/64] Revert "style(.claude/skills): format all shell scripts
 with shfmt"

This reverts commit 336ea1b58eb76a75fe8066e5112df4c10133e8e2.
---
 .../scripts/cross-worktree-probe.sh           | 18 ++++----
 .../scripts/diff-running-vs-intended.sh       | 43 ++++++-------------
 .claude/skills/scenario-tear-down/SKILL.md    |  8 ++--
 3 files changed, 27 insertions(+), 42 deletions(-)

diff --git a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
index a9e62c938..1e91c95ba 100755
--- a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
+++ b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
@@ -28,16 +28,16 @@ for port in "${PORTS[@]}"; do
 
     cmd="$(ps -o command= -p "$pid" 2>/dev/null | head -c 200)"
     case "$port" in
-    8080) kind=platform ;;
-    8181 | 8282 | 8383 | 8484 | 8585 | 8686) kind=kas ;;
-    8888) kind=docker-keycloak ;;
-    5432) kind=docker-postgres ;;
-    *) kind=unknown ;;
+      8080) kind=platform ;;
+      8181|8282|8383|8484|8585|8686) kind=kas ;;
+      8888) kind=docker-keycloak ;;
+      5432) kind=docker-postgres ;;
+      *)    kind=unknown ;;
     esac
     # Refine kind if process command says otherwise (e.g. a misbound port).
     case "$cmd" in
-    *"/service "*) kind=platform ;;
-    *opentdf-kas* | *"kas start"*) kind=kas ;;
+      *"/service "*) kind=platform ;;
+      *opentdf-kas*|*"kas start"*) kind=kas ;;
     esac
 
     printf '%s\ttcp\t%s\t%s\t%s\n' "$port" "$pid" "$cwd" "$kind"
@@ -51,7 +51,7 @@ done
 docker ps --format '{{.Names}}' 2>/dev/null | while IFS= read -r name; do
   [[ -z "$name" ]] && continue
   case "$name" in
-  *-keycloak-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
-  *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
+    *-keycloak-*)  printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
+    *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
   esac
 done | sort -u
diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
index e25073bea..c7a9257f8 100755
--- a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -33,10 +33,7 @@ done
 : "${INST_ROOT:?could not locate tests/instances/ above $PWD}"
 
 inst="$INST_ROOT/$name/instance.yaml"
-[[ -f "$inst" ]] || {
-  echo "no instance.yaml at $inst" >&2
-  exit 2
-}
+[[ -f "$inst" ]] || { echo "no instance.yaml at $inst" >&2; exit 2; }
 
 INST_DIR_PARENT="${INST_ROOT%/instances}"
 PLATFORM_DIST="$INST_DIR_PARENT/xtest/platform/dist"
@@ -54,12 +51,12 @@ declare -A PORT_OF=(
 
 # Helper: resolve a pin (ref or dist) to expected_sha by reading .version.
 expected_sha_for() {
-  local pin="$1" # could be a ref like 'main' or 'pr:3537', or a dist slug
+  local pin="$1"  # could be a ref like 'main' or 'pr:3537', or a dist slug
   for cand in "$PLATFORM_DIST"/*/; do
     [[ -f "$cand/.version" ]] || continue
-    if grep -Fq "ref=$pin" "$cand/.version" ||
-      grep -Fq "ref=refs/pull/${pin#pr:}/head" "$cand/.version" ||
-      [[ "$(basename "${cand%/}")" == "$pin" ]]; then
+    if grep -Fq "ref=$pin" "$cand/.version" \
+      || grep -Fq "ref=refs/pull/${pin#pr:}/head" "$cand/.version" \
+      || [[ "$(basename "${cand%/}")" == "$pin" ]]; then
       awk -F= '/^sha=/ {print substr($2,1,12); exit}' "$cand/.version"
       return
     fi
@@ -72,15 +69,9 @@ actual_sha_for_port() {
   local port="$1"
   local pid binary version
   pid="$(lsof -nP -iTCP:"$port" -sTCP:LISTEN 2>/dev/null | awk 'NR>1 {print $2; exit}')"
-  [[ -z "$pid" ]] && {
-    echo ""
-    return
-  }
+  [[ -z "$pid" ]] && { echo ""; return; }
   binary="$(ps -o command= -p "$pid" 2>/dev/null | awk '{print $1}')"
-  [[ -f "$binary" ]] || {
-    echo "?"
-    return
-  }
+  [[ -f "$binary" ]] || { echo "?"; return; }
   version="$(dirname "$binary")/.version"
   [[ -f "$version" ]] && awk -F= '/^sha=/ {print substr($2,1,12); exit}' "$version" || echo "?"
 }
@@ -93,7 +84,7 @@ health_of() {
 
 # Extract pins from instance.yaml. yq optional; fall back to grep.
 get_pin() {
-  local field="$1" # e.g. .platform OR .kas.km1
+  local field="$1"   # e.g. .platform OR .kas.km1
   if command -v yq >/dev/null 2>&1; then
     yq -r "($field.source.ref? // $field.dist? // \"\")" "$inst"
   else
@@ -126,12 +117,9 @@ pin="$(get_pin .platform)"
 exp="$(expected_sha_for "$pin")"
 act="$(actual_sha_for_port 8080)"
 hc="$(health_of 8080)"
-if [[ -z "$pin" ]]; then
-  status=NO-PIN
-elif [[ -z "$act" ]]; then
-  status=NOT-RUNNING
-elif [[ "$act" == "$exp" ]]; then
-  status=MATCH
+if [[ -z "$pin" ]]; then status=NO-PIN
+elif [[ -z "$act" ]]; then status=NOT-RUNNING
+elif [[ "$act" == "$exp" ]]; then status=MATCH
 else status=WRONG-BINARY; fi
 printf 'platform\t8080\t%s\t%s\t%s\t%s\n' "${exp:-?}" "${act:--}" "$hc" "$status"
 
@@ -152,12 +140,9 @@ for kas in "${kas_names[@]}"; do
   exp="$(expected_sha_for "$pin")"
   act="$(actual_sha_for_port "$port")"
   hc="$([[ "$port" != "?" ]] && health_of "$port" || echo -)"
-  if [[ -z "$pin" ]]; then
-    status=NO-PIN
-  elif [[ -z "$act" ]]; then
-    status=NOT-RUNNING
-  elif [[ "$act" == "$exp" ]]; then
-    status=MATCH
+  if [[ -z "$pin" ]]; then status=NO-PIN
+  elif [[ -z "$act" ]]; then status=NOT-RUNNING
+  elif [[ "$act" == "$exp" ]]; then status=MATCH
   else status=WRONG-BINARY; fi
   printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$kas" "$port" "${exp:-?}" "${act:--}" "$hc" "$status"
 done
diff --git a/.claude/skills/scenario-tear-down/SKILL.md b/.claude/skills/scenario-tear-down/SKILL.md
index cd992db81..a37b5fbcb 100644
--- a/.claude/skills/scenario-tear-down/SKILL.md
+++ b/.claude/skills/scenario-tear-down/SKILL.md
@@ -20,10 +20,10 @@ Stop a running scenario cleanly and optionally remove its on-disk state. Confirm
 Before stopping anything, list the docker compose projects currently sharing the host daemon:
 
 ```bash
-docker ps --format '{{.Names}}' |
-	grep -E -- '-keycloak-|-opentdfdb-' |
-	sed -E 's/-(keycloak|opentdfdb)-[0-9]+$//' |
-	sort -u
+docker ps --format '{{.Names}}' \
+  | grep -E -- '-keycloak-|-opentdfdb-' \
+  | sed -E 's/-(keycloak|opentdfdb)-[0-9]+$//' \
+  | sort -u
 ```
 
 Each line is a compose-project name — typically the directory name where `docker compose` was invoked (a worktree's `xtest/platform/src/<slug>/`). If more than one project appears, surface this in the reply: `down` will *keep* docker keycloak/postgres running because another instance still uses them. The user's expectation that "ports 5432 and 8888 are now free" would be wrong.

From 3c7236071517eb197dea03b76c1afda10c76ea82 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 14:13:21 -0400
Subject: [PATCH 36/64] style: fix shfmt formatting by removing keep_padding
 from .editorconfig

keep_padding = true caused bizarre column-alignment when shfmt expanded
inline { ... } blocks, aligning body content to the column of the opening
brace rather than using normal indentation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../scripts/cross-worktree-probe.sh           |  8 ++--
 .../scripts/diff-running-vs-intended.sh       | 43 +++++++++++++------
 .editorconfig                                 |  3 --
 xtest/sdk/go/otdfctl.sh                       |  2 +-
 xtest/sdk/java/cli.sh                         |  2 +-
 5 files changed, 35 insertions(+), 23 deletions(-)

diff --git a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
index 1e91c95ba..2d303d47a 100755
--- a/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
+++ b/.claude/skills/instance-status/scripts/cross-worktree-probe.sh
@@ -29,15 +29,15 @@ for port in "${PORTS[@]}"; do
     cmd="$(ps -o command= -p "$pid" 2>/dev/null | head -c 200)"
     case "$port" in
       8080) kind=platform ;;
-      8181|8282|8383|8484|8585|8686) kind=kas ;;
+      8181 | 8282 | 8383 | 8484 | 8585 | 8686) kind=kas ;;
       8888) kind=docker-keycloak ;;
       5432) kind=docker-postgres ;;
-      *)    kind=unknown ;;
+      *) kind=unknown ;;
     esac
     # Refine kind if process command says otherwise (e.g. a misbound port).
     case "$cmd" in
       *"/service "*) kind=platform ;;
-      *opentdf-kas*|*"kas start"*) kind=kas ;;
+      *opentdf-kas* | *"kas start"*) kind=kas ;;
     esac
 
     printf '%s\ttcp\t%s\t%s\t%s\n' "$port" "$pid" "$cwd" "$kind"
@@ -51,7 +51,7 @@ done
 docker ps --format '{{.Names}}' 2>/dev/null | while IFS= read -r name; do
   [[ -z "$name" ]] && continue
   case "$name" in
-    *-keycloak-*)  printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
+    *-keycloak-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-keycloak-*}" ;;
     *-opentdfdb-*) printf 'compose\tdocker\t-\t%s\tcompose-project\n' "${name%-opentdfdb-*}" ;;
   esac
 done | sort -u
diff --git a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
index c7a9257f8..e25073bea 100755
--- a/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
+++ b/.claude/skills/scenario-doctor/scripts/diff-running-vs-intended.sh
@@ -33,7 +33,10 @@ done
 : "${INST_ROOT:?could not locate tests/instances/ above $PWD}"
 
 inst="$INST_ROOT/$name/instance.yaml"
-[[ -f "$inst" ]] || { echo "no instance.yaml at $inst" >&2; exit 2; }
+[[ -f "$inst" ]] || {
+  echo "no instance.yaml at $inst" >&2
+  exit 2
+}
 
 INST_DIR_PARENT="${INST_ROOT%/instances}"
 PLATFORM_DIST="$INST_DIR_PARENT/xtest/platform/dist"
@@ -51,12 +54,12 @@ declare -A PORT_OF=(
 
 # Helper: resolve a pin (ref or dist) to expected_sha by reading .version.
 expected_sha_for() {
-  local pin="$1"  # could be a ref like 'main' or 'pr:3537', or a dist slug
+  local pin="$1" # could be a ref like 'main' or 'pr:3537', or a dist slug
   for cand in "$PLATFORM_DIST"/*/; do
     [[ -f "$cand/.version" ]] || continue
-    if grep -Fq "ref=$pin" "$cand/.version" \
-      || grep -Fq "ref=refs/pull/${pin#pr:}/head" "$cand/.version" \
-      || [[ "$(basename "${cand%/}")" == "$pin" ]]; then
+    if grep -Fq "ref=$pin" "$cand/.version" ||
+      grep -Fq "ref=refs/pull/${pin#pr:}/head" "$cand/.version" ||
+      [[ "$(basename "${cand%/}")" == "$pin" ]]; then
       awk -F= '/^sha=/ {print substr($2,1,12); exit}' "$cand/.version"
       return
     fi
@@ -69,9 +72,15 @@ actual_sha_for_port() {
   local port="$1"
   local pid binary version
   pid="$(lsof -nP -iTCP:"$port" -sTCP:LISTEN 2>/dev/null | awk 'NR>1 {print $2; exit}')"
-  [[ -z "$pid" ]] && { echo ""; return; }
+  [[ -z "$pid" ]] && {
+    echo ""
+    return
+  }
   binary="$(ps -o command= -p "$pid" 2>/dev/null | awk '{print $1}')"
-  [[ -f "$binary" ]] || { echo "?"; return; }
+  [[ -f "$binary" ]] || {
+    echo "?"
+    return
+  }
   version="$(dirname "$binary")/.version"
   [[ -f "$version" ]] && awk -F= '/^sha=/ {print substr($2,1,12); exit}' "$version" || echo "?"
 }
@@ -84,7 +93,7 @@ health_of() {
 
 # Extract pins from instance.yaml. yq optional; fall back to grep.
 get_pin() {
-  local field="$1"   # e.g. .platform OR .kas.km1
+  local field="$1" # e.g. .platform OR .kas.km1
   if command -v yq >/dev/null 2>&1; then
     yq -r "($field.source.ref? // $field.dist? // \"\")" "$inst"
   else
@@ -117,9 +126,12 @@ pin="$(get_pin .platform)"
 exp="$(expected_sha_for "$pin")"
 act="$(actual_sha_for_port 8080)"
 hc="$(health_of 8080)"
-if [[ -z "$pin" ]]; then status=NO-PIN
-elif [[ -z "$act" ]]; then status=NOT-RUNNING
-elif [[ "$act" == "$exp" ]]; then status=MATCH
+if [[ -z "$pin" ]]; then
+  status=NO-PIN
+elif [[ -z "$act" ]]; then
+  status=NOT-RUNNING
+elif [[ "$act" == "$exp" ]]; then
+  status=MATCH
 else status=WRONG-BINARY; fi
 printf 'platform\t8080\t%s\t%s\t%s\t%s\n' "${exp:-?}" "${act:--}" "$hc" "$status"
 
@@ -140,9 +152,12 @@ for kas in "${kas_names[@]}"; do
   exp="$(expected_sha_for "$pin")"
   act="$(actual_sha_for_port "$port")"
   hc="$([[ "$port" != "?" ]] && health_of "$port" || echo -)"
-  if [[ -z "$pin" ]]; then status=NO-PIN
-  elif [[ -z "$act" ]]; then status=NOT-RUNNING
-  elif [[ "$act" == "$exp" ]]; then status=MATCH
+  if [[ -z "$pin" ]]; then
+    status=NO-PIN
+  elif [[ -z "$act" ]]; then
+    status=NOT-RUNNING
+  elif [[ "$act" == "$exp" ]]; then
+    status=MATCH
   else status=WRONG-BINARY; fi
   printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$kas" "$port" "${exp:-?}" "${act:--}" "$hc" "$status"
 done
diff --git a/.editorconfig b/.editorconfig
index edb53ee58..239a6d503 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -18,8 +18,5 @@ binary_next_line = false
 # Switch case indentation
 switch_case_indent = true
 
-# Keep column alignment
-keep_padding = true
-
 # Function brace on same line
 function_next_line = false
diff --git a/xtest/sdk/go/otdfctl.sh b/xtest/sdk/go/otdfctl.sh
index c30ab481c..f055f7dcd 100755
--- a/xtest/sdk/go/otdfctl.sh
+++ b/xtest/sdk/go/otdfctl.sh
@@ -5,7 +5,7 @@
 #
 # Usage: ./otdfctl.sh [otdfctl options]
 #
-SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null  && pwd)
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
 
 XTEST_DIR="$SCRIPT_DIR"
 while [ ! -f "$XTEST_DIR/test.env" ] && [ "$(basename "$XTEST_DIR")" != "xtest" ]; do
diff --git a/xtest/sdk/java/cli.sh b/xtest/sdk/java/cli.sh
index 0f5758c50..46b755391 100755
--- a/xtest/sdk/java/cli.sh
+++ b/xtest/sdk/java/cli.sh
@@ -97,7 +97,7 @@ if [ "$1" == "supports" ]; then
       ;;
 
     mechanism-rsa-4096 | mechanism-ec-curves-384-521)
-       # rsa4096 support in >= 0.13.0
+      # rsa4096 support in >= 0.13.0
       set -o pipefail
       java -jar "$SCRIPT_DIR"/cmdline.jar --version | jq -re .version | awk -F. '{ if ($1 > 0 || ($1 == 0 && $2 >= 13)) exit 0; else exit 1; }'
       exit $?

From cb2a902f1012e99af857e3c6ab14a5e3e8399c64 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 18 May 2026 11:32:43 -0400
Subject: [PATCH 37/64] feat(.claude): feature-orchestrate skill +
 cells-of-effort spec (DSPX-3302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements the second half of the multi-repo feature workflow. feature-design
(landed in PR 5) authors the spec and tests-side artifacts; feature-orchestrate
reads that spec, creates git worktrees, and fans claude -p subagents out in
topological waves so each cell of work proceeds in parallel where possible.

Spec schema change (informal — no Pydantic model yet):

The platform monorepo holds proto definitions, the Go SDK, KAS service code,
and shared libs, so a single feature often touches multiple "cells of effort"
inside one repo. The spec now expresses work as cells, not repos. Each cell
has a `path:` (which sibling repo to worktree from), a `branch:`, a `todo:`
list, and an optional `depends_on:` edge. Canonical example: every SDK cell
declares `depends_on: [platform-proto]` whenever the feature changes wire
format — the proto cell regenerates Go/Java/JS bindings before the SDKs can
adopt them.

- `otdf-sdk-mgr orchestrate run <spec>` (new CLI verb in `cli_orchestrate.py`):
  parses the spec, topologically sorts cells by `depends_on`, creates worktrees
  at `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/`, and dispatches one
  `claude -p` subagent per cell. Cells in the same wave run in parallel via
  `ThreadPoolExecutor`. Per-cell prompts embed the full spec body for
  cross-cell context. `--dry-run`, `--only <cell>`, `--timeout`, `--model`
  flags. Per-cell stdout captured to `.claude/tmp/runs/<KEY>-<cell>.jsonl`.
- Per-worktree `.claude/settings.json` auto-written if absent, with a minimal
  allowlist tailored to the repo (`go`/`make`/`buf` for platform, `mvn` for
  java-sdk, `npm` for web-sdk) plus universal `git`/`gh pr create`. Skipped
  if the user has committed their own settings.
- `feature-orchestrate` SKILL.md: thin wrapper that surfaces the dry-run plan,
  asks the user to confirm, then dispatches.
- `feature-design` SKILL.md Step 2/3: teaches the cell shape, `path:`,
  `depends_on:`, and the proto-blocks-SDK pattern as the canonical example.
  Branches are now per-cell (`<JIRA-KEY>-<cell-key>`) so concurrent worktrees
  of the same repo don't collide.
- 10 new unit tests (`test_orchestrate.py`): load + validation, topological
  waves with skip semantics, cycle detection (incl. diamond), worktree path
  resolution. All passing alongside the existing 65.
- `xtest/features/{README,CLAUDE}.md`: cell-aware terminology.
- `settings.json` + `plugin.json`: `Bash(claude -p *)`, `Bash(git worktree *)`,
  `Bash(gh pr create *)` allowlists; `Skill(feature-orchestrate)` registered.

Out of scope for this PR: status command, --retry, Pydantic model for Feature,
cross-PR linking automation, non-Sonnet subagent models. See plan file for
the full follow-up list.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/plugin/plugin.json                    |   5 +
 .claude/settings.json                         |   3 +
 .claude/skills/feature-design/SKILL.md        |  74 ++-
 .claude/skills/feature-orchestrate/SKILL.md   |  75 +++
 otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py          |   2 +
 .../src/otdf_sdk_mgr/cli_orchestrate.py       | 451 ++++++++++++++++++
 otdf-sdk-mgr/tests/test_orchestrate.py        | 186 ++++++++
 xtest/features/CLAUDE.md                      |   6 +-
 xtest/features/README.md                      |   4 +-
 9 files changed, 784 insertions(+), 22 deletions(-)
 create mode 100644 .claude/skills/feature-orchestrate/SKILL.md
 create mode 100644 otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
 create mode 100644 otdf-sdk-mgr/tests/test_orchestrate.py

diff --git a/.claude/plugin/plugin.json b/.claude/plugin/plugin.json
index 906d0d240..76115cdf4 100644
--- a/.claude/plugin/plugin.json
+++ b/.claude/plugin/plugin.json
@@ -5,6 +5,7 @@
   "skills_dir": "../skills",
   "skills": [
     "feature-design",
+    "feature-orchestrate",
     "scenario-from-ticket",
     "scenario-matrix",
     "scenario-up",
@@ -25,6 +26,9 @@
       "Bash(uv run otdf-local *)",
       "Bash(uv run otdf-sdk-mgr *)",
       "Bash(uv run pytest *)",
+      "Bash(claude -p *)",
+      "Bash(git worktree *)",
+      "Bash(gh pr create *)",
       "Bash(acli jira workitem view *)",
       "Bash(acli jira workitem search *)",
       "Bash(acli jira workitem comment list *)",
@@ -33,6 +37,7 @@
       "Bash(acli jira workitem link list *)",
       "Bash(acli jira project view *)",
       "Skill(feature-design)",
+      "Skill(feature-orchestrate)",
       "Skill(scenario-from-ticket)",
       "Skill(scenario-matrix)",
       "Skill(scenario-up)",
diff --git a/.claude/settings.json b/.claude/settings.json
index a14484c31..00f0670d3 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -5,6 +5,9 @@
       "Bash(uv run otdf-sdk-mgr *)",
       "Bash(uv run pytest *)",
       "Bash(uv sync *)",
+      "Bash(claude -p *)",
+      "Bash(git worktree *)",
+      "Bash(gh pr create *)",
       "Bash(git status *)",
       "Bash(git diff *)",
       "Bash(git log *)",
diff --git a/.claude/skills/feature-design/SKILL.md b/.claude/skills/feature-design/SKILL.md
index 4e1482e18..d6ed646e1 100644
--- a/.claude/skills/feature-design/SKILL.md
+++ b/.claude/skills/feature-design/SKILL.md
@@ -36,14 +36,30 @@ Extract Issue Type, summary, description, status, and any comments about scope o
 Draft the full spec body and the per-repo todo lists inline in the reply. Don't ask the user one field at a time — produce a complete first draft they can react to:
 
 - **Feature flag name** — snake_case identifier derived from the Jira summary. Becomes the `supports("<name>")` gate string AND the `feature_type` entry in `xtest/tdfs.py`. Validate it's a valid Python identifier and doesn't collide with an existing `feature_type` member.
-- **Touched repos** — default set is `tests, platform, sdk-go, sdk-java, sdk-web`. Trim or expand based on what the ticket says. Pure platform features skip the SDK repos; pure SDK-only features skip platform; `tests` is always present (the dormant scenario + tdfs.py entry has to live there).
-- **Per-repo todo lists** — 2–4 bullets per repo:
+- **Touched cells** — the spec divides work into *cells of effort*, not just repos. The platform monorepo holds proto definitions, the Go SDK, KAS service code, and shared libraries; a feature often touches multiple cells *inside* `platform` plus one or more standalone SDK repos. Default cells when a feature spans the whole stack:
+  - `tests` — always present (dormant scenario + `feature_type` entry); no `path:` since it IS the current repo.
+  - `platform-proto` — when the feature changes wire format (`.proto` edits + `buf generate`). The bindings it produces are an upstream dependency for every SDK cell. `path: platform`.
+  - `platform-service` — KAS path / policy plumbing / dev-harness env-var handling. `path: platform`.
+  - `platform-go-sdk` — Go SDK encrypt/decrypt path (lives in the platform monorepo at `sdk/`). `path: platform`.
+  - `java-sdk` — Java SDK. `path: java-sdk` (standalone repo).
+  - `web-sdk` — JS/TS SDK. `path: web-sdk` (standalone repo).
+  - `otdfctl` — Go CLI. `path: otdfctl`. Rare; usually only when the feature surfaces in the CLI directly.
+
+  Pure platform-internal features skip the SDK cells. SDK-only features skip the platform cells. Trim aggressively.
+
+- **`path:`** — for every non-`tests` cell, set `path:` to the sibling directory under `~/Documents/GitHub/opentdf/`. Multiple cells can share a `path` value (the orchestrator creates a separate worktree per cell, each on its own branch).
+
+- **`depends_on:`** — list other cell keys whose work must finish before this cell can adopt their output. The canonical case: every cell that consumes regenerated bindings declares `depends_on: [platform-proto]` whenever the feature changes proto. Without `depends_on`, the orchestrator runs cells in parallel.
+
+- **Per-cell todo lists** — 2-4 bullets per cell:
   - `tests` — register the feature in `feature_type`, author the scenario, draft the test gated on `supports("<feature>")`.
-  - `platform` — service-side implementation (KAS path, policy plumbing, etc.) and any env-var handling in the dev harness (e.g. honoring `XT_WITH_<FEATURE>`).
-  - `sdk-go` / `sdk-java` / `sdk-web` — encrypt/decrypt path implementation, plus a `supports <feature>` case in that SDK's `cli.sh` source. **Don't pin the version bound in the spec** — the implementing engineer sets the `awk` predicate at PR time, since the bound depends on which release will ship the impl.
-- **Branch name** — `<JIRA-KEY>-<feature-slug>`, the same string across every touched repo so `feature-orchestrate` (and the user) can find each repo's PR by branch alone.
+  - `platform-proto` — edit the `.proto`, run `buf generate`, commit the regenerated stubs across Go / Java / JS subdirs.
+  - `platform-service` — implement the server-side change; honor any new env var the test harness uses (e.g. `XT_WITH_<FEATURE>`).
+  - `platform-go-sdk` / `java-sdk` / `web-sdk` / `otdfctl` — implement the client encrypt/decrypt path, plus a `supports <feature>` case in that SDK's `cli.sh` source. **Don't pin the version bound in the spec** — the implementing engineer sets the `awk` predicate at PR time, since the bound depends on which release ships the impl.
+
+- **Branch names** — `<JIRA-KEY>-<cell-key>` (e.g. `DSPX-2719-platform-proto`, `DSPX-2719-java-sdk`). Cell-specific rather than uniform-across-repos because the orchestrator creates a separate worktree per cell, each on its own branch — multiple cells sharing the same `path` would otherwise collide.
 
-Present the draft, then ask exactly one composite question: "Anything to redirect — feature name, touched repos, todo items, branch?" Apply edits in a single revision rather than turn-by-turn. The user can always drop into plain chat if they want to think out loud — answer normally and re-invoke this skill once the design firms up.
+Present the draft, then ask exactly one composite question: "Anything to redirect — feature name, touched cells, todo items, dependency edges, branches?" Apply edits in a single revision rather than turn-by-turn. The user can always drop into plain chat if they want to think out loud — just answer them and re-invoke this skill once the design firms up.
 
 If no Jira key was given AND the user's description doesn't pin down a clear scope (feature flag name, touched repos, intended behavior), bail rather than fabricate:
 
@@ -67,25 +83,49 @@ metadata:
   created: <YYYY-MM-DD>
 repos:
   tests:
-    branch: <JIRA-KEY>-<feature-slug>
+    branch: <JIRA-KEY>-tests
     todo:
       - Register "<feature-name>" in xtest/tdfs.py feature_type
       - Author scenario + draft test (via scenario-from-ticket)
-  platform:
-    branch: <JIRA-KEY>-<feature-slug>
-    todo: [ ... ]
-  sdk-go:
-    branch: <JIRA-KEY>-<feature-slug>
+  platform-proto:                          # cell key, not repo name
+    path: platform                         # which sibling repo this lives in
+    branch: <JIRA-KEY>-platform-proto
+    todo:
+      - Edit <service>.proto, add <RPC> with <fields>
+      - Run buf generate; commit regenerated Go/Java/JS stubs
+  platform-service:
+    path: platform
+    branch: <JIRA-KEY>-platform-service
+    depends_on: [platform-proto]           # waits for proto cell
+    todo:
+      - Implement the new RPC handler in the KAS service
+      - Honor XT_WITH_<FEATURE> in the dev test harness
+  platform-go-sdk:
+    path: platform
+    branch: <JIRA-KEY>-platform-go-sdk
+    depends_on: [platform-proto]
+    todo:
+      - Implement <feature> in the SDK's encrypt path
+      - Add `supports <feature>` case to sdk/go/cli.sh
+  java-sdk:
+    path: java-sdk
+    branch: <JIRA-KEY>-java-sdk
+    depends_on: [platform-proto]
+    todo:
+      - Implement <feature> in the Java SDK encrypt path
+      - Add `supports <feature>` case to sdk/java/cli.sh
+  web-sdk:
+    path: web-sdk
+    branch: <JIRA-KEY>-web-sdk
+    depends_on: [platform-proto]
     todo:
-      - Implement <feature> in the encrypt/decrypt path
-      - Add `supports <feature>` case to cli.sh with version-bound awk predicate
-  sdk-java: { branch: ..., todo: [ ... ] }
-  sdk-web:  { branch: ..., todo: [ ... ] }
+      - Implement <feature> in the JS SDK encrypt path
+      - Add `supports <feature>` case to sdk/js/cli.sh
 scenarios:
   - xtest/scenarios/<jira-key-lowercased>.yaml
 ```
 
-PR status (open/merged/CI passing) deliberately is NOT in the spec — it's auto-discovered from `gh pr list --search "head:<branch>"` per repo whenever something asks "where are we?" The spec is a declaration of intent.
+PR status (open/merged/CI passing) deliberately is NOT in the spec — it's auto-discovered from `gh pr list --search "head:<branch>"` per repo whenever something asks "where are we?" The spec is a declaration of intent. The orchestrator (`feature-orchestrate`) reads this file and fans out one subagent per cell, respecting `depends_on` waves.
 
 ### Step 4 — Drive the tests-side artifacts
 
diff --git a/.claude/skills/feature-orchestrate/SKILL.md b/.claude/skills/feature-orchestrate/SKILL.md
new file mode 100644
index 000000000..4732abece
--- /dev/null
+++ b/.claude/skills/feature-orchestrate/SKILL.md
@@ -0,0 +1,75 @@
+---
+name: feature-orchestrate
+description: Fan out per-cell subagents to implement a multi-repo feature described by `xtest/features/<name>.yaml`. Reads the spec, creates one git worktree per cell at `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/`, topologically sorts cells by `depends_on`, and launches `claude -p` subagents in parallel within each wave. Each subagent implements its cell and opens a draft PR. Use after `feature-design` has produced the spec and the tests-side PR is in flight (or merged).
+allowed-tools: Bash, Read
+---
+
+# feature-orchestrate
+
+You drive the cross-repo implementation of a feature whose spec lives at `xtest/features/<feature-name>.yaml`. The tests-side artifacts (scenario, draft test, `feature_type` entry) have already been authored by `feature-design`; your job is to dispatch a subagent per remaining cell, in dependency order, and report the resulting PRs.
+
+The heavy lifting is a Python helper: `uv run otdf-sdk-mgr orchestrate run <spec>`. The skill body is a thin wrapper around it — invoke the verb, surface its output.
+
+## Inputs
+
+- Path to a feature spec at `xtest/features/<name>.yaml` (produced by `feature-design`).
+- (Optional) `--only <cell-key>` to run a subset of cells. Repeatable.
+- (Optional) `--dry-run` to print the plan without dispatching.
+
+## Process
+
+### Step 1 — Sanity-check the spec
+
+Before dispatching, run a dry-run so the user can confirm the topology and pinning are what they expect:
+
+```bash
+uv run otdf-sdk-mgr orchestrate run xtest/features/<name>.yaml --dry-run
+```
+
+The output names each cell, its target repo path, the branch it'll work on, and the worktree path the orchestrator will create. Each wave is a set of cells with no dependencies between them; cells in a later wave have at least one `depends_on` edge into an earlier wave.
+
+Surface the dry-run output to the user verbatim. If anything looks wrong (a cell going to the wrong repo, a missing `depends_on` edge, a stale branch name), ask the user to fix the spec via `feature-design` (or edit it directly) before proceeding.
+
+### Step 2 — Dispatch
+
+When the user confirms, run for real:
+
+```bash
+uv run otdf-sdk-mgr orchestrate run xtest/features/<name>.yaml
+```
+
+For each cell, the orchestrator:
+
+1. Creates `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/` as a worktree of `~/Documents/GitHub/opentdf/<path>` on branch `<cell.branch>`. Idempotent — reuses an existing worktree if it's already on the right branch, bails if it's on a different one.
+2. Writes a minimal `.claude/settings.json` into the worktree (allowing `git`, `gh pr create`, and the repo-type-appropriate test commands: `go`/`make`/`buf` for platform, `mvn` for java-sdk, `npm` for web-sdk).
+3. Launches `claude -p --model sonnet --permission-mode acceptEdits` inside the worktree with a prompt containing the full spec body + that cell's todo + house-style commit guidance. The subagent implements, commits, opens a draft PR via `gh pr create --draft`, and prints the PR URL as its last line of output.
+4. Captures stdout to `.claude/tmp/runs/<JIRA-KEY>-<cell-key>.jsonl` for inspection.
+
+Cells in the same wave run in parallel (Python `ThreadPoolExecutor`). Each subagent has a 30-minute timeout by default (`--timeout 1800` to override). If a subagent fails, its dependents in later waves are skipped with a clear "upstream dependency failed" note.
+
+### Step 3 — Report
+
+When the orchestrator finishes, it prints a final table:
+
+```
+CELL                     STATUS PR / ERROR
+platform-proto           OK     https://github.com/opentdf/platform/pull/1234
+platform-service         OK     https://github.com/opentdf/platform/pull/1235
+java-sdk                 OK     https://github.com/opentdf/java-sdk/pull/567
+web-sdk                  FAIL   exit 1
+```
+
+Pass the table on to the user, plus the JSONL transcript paths for any FAIL rows so they can inspect what went wrong.
+
+## When to use partial runs
+
+- `--only platform-proto` — proto change has to ship before anything else can adopt the new bindings. Run the proto cell alone first, review the PR, merge it, then run the rest.
+- `--only java-sdk` — re-launch a single failed cell after fixing whatever broke. The dependency check still runs; if `java-sdk`'s `depends_on` failed earlier, the orchestrator will refuse rather than racing.
+
+## Notes
+
+- This skill **does not edit the `tests/` repo**. The `tests` cell in the spec is owned by `feature-design`; the orchestrator skips it. If the tests-side PR isn't merged yet, that's fine — the subagent PRs will run their CI against the SDK changes, and the dormant tests in `tests/main` only activate once each repo's `supports("<feature>")` case lands.
+- Worktrees live at `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/` regardless of which repo they came from. The user's main checkouts (`~/Documents/GitHub/opentdf/{platform,java-sdk,web-sdk,otdfctl}/`) are never modified.
+- Subagents print the PR URL on their last line of output as a contract — the orchestrator parses it with a regex. If a subagent doesn't print one, the orchestrator reports the cell as "no PR URL" but doesn't mark it failed (the subagent may have done useful work even if the PR step failed).
+- The orchestrator dispatches subagents in parallel within a wave, so per-cell logs interleave in real time but each cell's full transcript lands in its own JSONL file. Inspect transcripts under `.claude/tmp/runs/`.
+- For features whose protos don't change wire format, omit `depends_on: [platform-proto]` on the SDK cells — they can run in parallel with the proto cell (or skip the proto cell entirely).
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py
index 78b137c95..0483fb69a 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli.py
@@ -10,6 +10,7 @@
 import typer
 
 from otdf_sdk_mgr.cli_install import install_app
+from otdf_sdk_mgr.cli_orchestrate import orchestrate_app
 from otdf_sdk_mgr.cli_schema import schema_app
 from otdf_sdk_mgr.cli_versions import versions_app
 from otdf_sdk_mgr.config import ALL_SDKS, get_sdk_dirs
@@ -21,6 +22,7 @@
 )
 
 app.add_typer(install_app, name="install")
+app.add_typer(orchestrate_app, name="orchestrate")
 app.add_typer(schema_app, name="schema")
 app.add_typer(versions_app, name="versions")
 
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
new file mode 100644
index 000000000..0a0483278
--- /dev/null
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
@@ -0,0 +1,451 @@
+"""`otdf-sdk-mgr orchestrate` subcommands.
+
+Read a multi-repo feature spec from `xtest/features/<name>.yaml`, topologically
+sort the cells by `depends_on`, create one git worktree per cell at
+`~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/`, and fan out `claude -p`
+subagents to implement each cell in parallel within each wave. Each subagent
+opens a draft PR and prints its URL as the last line of stdout.
+
+The `tests` cell is skipped — `feature-design` already produced its artifacts
+(scenario, draft test, `feature_type` entry).
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import json
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Iterable
+
+import typer
+from ruamel.yaml import YAML
+
+orchestrate_app = typer.Typer(
+    help="Fan out per-cell subagents to implement a multi-repo feature.",
+)
+
+
+# ------------------------------------------------------------------ data model
+
+
+@dataclass(frozen=True)
+class Cell:
+    key: str
+    path: str | None
+    branch: str
+    todo: tuple[str, ...]
+    depends_on: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class FeatureSpec:
+    name: str
+    jira: str | None
+    title: str
+    body: str
+    cells: dict[str, Cell]
+    scenarios: tuple[str, ...]
+
+
+# ------------------------------------------------------------------ load
+
+
+def _safe_yaml() -> YAML:
+    return YAML(typ="safe")
+
+
+def load_spec(path: Path) -> FeatureSpec:
+    raw = path.read_text(encoding="utf-8")
+    parsed = _safe_yaml().load(raw)
+    if not isinstance(parsed, dict):
+        raise ValueError(f"{path}: top-level must be a mapping")
+
+    meta = parsed.get("metadata") or {}
+    if not isinstance(meta, dict):
+        raise ValueError(f"{path}: metadata must be a mapping")
+    name = meta.get("name")
+    if not isinstance(name, str) or not name:
+        raise ValueError(f"{path}: metadata.name is required")
+
+    repos = parsed.get("repos") or {}
+    if not isinstance(repos, dict):
+        raise ValueError(f"{path}: repos must be a mapping")
+
+    cells: dict[str, Cell] = {}
+    for key, entry in repos.items():
+        if not isinstance(entry, dict):
+            raise ValueError(f"{path}: repos.{key} must be a mapping")
+        branch = entry.get("branch")
+        if not isinstance(branch, str) or not branch:
+            raise ValueError(f"{path}: repos.{key}.branch is required")
+        todo = entry.get("todo") or []
+        if not isinstance(todo, list):
+            raise ValueError(f"{path}: repos.{key}.todo must be a list")
+        deps = entry.get("depends_on") or []
+        if not isinstance(deps, list):
+            raise ValueError(f"{path}: repos.{key}.depends_on must be a list")
+        repo_path = entry.get("path")
+        if key != "tests" and not isinstance(repo_path, str):
+            raise ValueError(
+                f"{path}: repos.{key}.path is required for non-tests cells"
+            )
+        cells[key] = Cell(
+            key=key,
+            path=repo_path,
+            branch=branch,
+            todo=tuple(str(t) for t in todo),
+            depends_on=tuple(str(d) for d in deps),
+        )
+
+    for cell in cells.values():
+        for dep in cell.depends_on:
+            if dep not in cells:
+                raise ValueError(
+                    f"{path}: repos.{cell.key}.depends_on references unknown key '{dep}'"
+                )
+
+    return FeatureSpec(
+        name=name,
+        jira=meta.get("jira"),
+        title=meta.get("title", name),
+        body=raw,
+        cells=cells,
+        scenarios=tuple(parsed.get("scenarios") or []),
+    )
+
+
+# ------------------------------------------------------------------ topo sort
+
+
+def topological_waves(
+    cells: dict[str, Cell], *, skip: Iterable[str] = ()
+) -> list[list[Cell]]:
+    """Group cells into dependency waves; cells within a wave are independent.
+
+    Skipped cells are treated as already-done (their dependents see them as
+    satisfied). Raises ValueError on cycles, naming the remaining set.
+    """
+    skip_set = set(skip)
+    active = {k: c for k, c in cells.items() if k not in skip_set}
+
+    indeg: dict[str, int] = {k: 0 for k in active}
+    for cell in active.values():
+        for dep in cell.depends_on:
+            if dep in active:
+                indeg[cell.key] += 1
+
+    waves: list[list[Cell]] = []
+    remaining = dict(active)
+    while remaining:
+        wave_keys = sorted(k for k, d in indeg.items() if d == 0 and k in remaining)
+        if not wave_keys:
+            raise ValueError(f"Dependency cycle among cells: {sorted(remaining)}")
+        wave = [remaining[k] for k in wave_keys]
+        waves.append(wave)
+        for k in wave_keys:
+            del remaining[k]
+            for other in remaining.values():
+                if k in other.depends_on:
+                    indeg[other.key] -= 1
+    return waves
+
+
+# ------------------------------------------------------------------ worktrees
+
+
+OPENTDF_ROOT = Path.home() / "Documents/GitHub/opentdf"
+WORKTREES_ROOT = Path.home() / "Documents/GitHub/worktrees"
+
+
+def worktree_for(spec: FeatureSpec, cell: Cell) -> Path:
+    jira = spec.jira or spec.name
+    return WORKTREES_ROOT / f"{jira}-{cell.key}"
+
+
+def ensure_worktree(spec: FeatureSpec, cell: Cell) -> Path:
+    """Create the cell's worktree if missing. Reuse if present and on the right branch.
+
+    Bails (RuntimeError) if the directory exists but is on a different branch —
+    we don't want to disturb concurrent work the user may have in flight.
+    """
+    if cell.path is None:
+        raise ValueError(f"cell '{cell.key}' has no path; cannot create worktree")
+    repo = OPENTDF_ROOT / cell.path
+    if not repo.is_dir():
+        raise FileNotFoundError(f"Sibling repo not found: {repo}")
+
+    wt = worktree_for(spec, cell)
+    if wt.exists():
+        current = subprocess.check_output(
+            ["git", "-C", str(wt), "branch", "--show-current"], text=True
+        ).strip()
+        if current != cell.branch:
+            raise RuntimeError(
+                f"Worktree {wt} is on branch '{current}', expected '{cell.branch}'. "
+                f"Remove it manually or check it out to the right branch."
+            )
+        return wt
+
+    wt.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.check_call(
+        ["git", "-C", str(repo), "worktree", "add", str(wt), "-b", cell.branch],
+    )
+    return wt
+
+
+# ----------------------------------------------------- subagent settings.json
+
+
+COMMON_ALLOW: tuple[str, ...] = (
+    "Bash(git *)",
+    "Bash(gh pr create *)",
+    "Bash(gh pr edit *)",
+    "Bash(gh pr view *)",
+    "Bash(ls *)",
+    "Bash(cat *)",
+    "Skill(*)",
+)
+
+REPO_ALLOW: dict[str, tuple[str, ...]] = {
+    "platform": ("Bash(go *)", "Bash(make *)", "Bash(buf *)", "Bash(yq *)"),
+    "java-sdk": ("Bash(mvn *)", "Bash(./mvnw *)"),
+    "web-sdk": ("Bash(npm *)", "Bash(pnpm *)", "Bash(node *)"),
+    "otdfctl": ("Bash(go *)", "Bash(make *)"),
+}
+
+
+def ensure_subagent_settings(worktree: Path, repo_path: str | None) -> None:
+    """Pre-write a minimal .claude/settings.json so the subagent has a working allowlist.
+
+    Skipped if the worktree already has one — the user may have committed a
+    tighter or broader policy that we shouldn't overwrite.
+    """
+    settings_path = worktree / ".claude" / "settings.json"
+    if settings_path.exists():
+        return
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    allow = list(COMMON_ALLOW) + list(REPO_ALLOW.get(repo_path or "", ()))
+    settings_path.write_text(
+        json.dumps({"permissions": {"allow": allow}}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+
+# ----------------------------------------------------------- subagent prompt
+
+
+PROMPT_TEMPLATE = """\
+You are implementing a single cell of the OpenTDF feature `{name}` ({jira}).
+Title: {title}
+Branch (already checked out): {branch}
+Cell key: {cell_key}
+Working directory: a git worktree of the `{path}` repo.
+
+The full feature spec is below for cross-cell context. Your work is whatever
+`repos.{cell_key}.todo` lists.
+
+--- BEGIN SPEC ---
+{body}
+--- END SPEC ---
+
+Instructions:
+1. Implement every item in `repos.{cell_key}.todo`. Don't switch branches.
+2. Run the repo's local checks before committing (unit tests, linters, build).
+3. Commit using house-style subject: `<type>({path}): <description> ({jira})`.
+   No `Jira:` footer. Add `Co-Authored-By: Claude` to the message.
+4. Open a draft PR via `gh pr create --draft --title "<same as commit subject>" --body "..."`.
+   PR body references the parent Jira (https://virtru.atlassian.net/browse/{jira})
+   and the tests-side scenario(s): {scenarios}.
+5. Print the PR URL on the LAST LINE of your output — the orchestrator parses it.
+
+Stay inside this worktree. Don't run pytest in tests/ — that's a different cell.
+"""
+
+
+def build_prompt(spec: FeatureSpec, cell: Cell) -> str:
+    return PROMPT_TEMPLATE.format(
+        name=spec.name,
+        jira=spec.jira or "(no Jira ticket)",
+        title=spec.title,
+        branch=cell.branch,
+        cell_key=cell.key,
+        path=cell.path or "",
+        body=spec.body,
+        scenarios=", ".join(spec.scenarios) or "(none)",
+    )
+
+
+# ------------------------------------------------------------------ dispatch
+
+
+PR_URL_RE = re.compile(r"https://github\.com/[^\s]+/pull/\d+")
+
+
+@dataclass
+class CellResult:
+    cell: Cell
+    worktree: Path
+    transcript: Path
+    success: bool
+    pr_url: str | None
+    error: str | None
+
+
+def run_cell(
+    spec: FeatureSpec,
+    cell: Cell,
+    *,
+    transcripts_dir: Path,
+    timeout_s: int,
+    model: str,
+) -> CellResult:
+    try:
+        wt = ensure_worktree(spec, cell)
+    except Exception as e:
+        return CellResult(cell, Path(), Path(), False, None, f"worktree: {e}")
+
+    ensure_subagent_settings(wt, cell.path)
+
+    transcripts_dir.mkdir(parents=True, exist_ok=True)
+    transcript = transcripts_dir / f"{spec.jira or spec.name}-{cell.key}.jsonl"
+
+    cmd = [
+        "claude", "-p",
+        "--model", model,
+        "--permission-mode", "acceptEdits",
+        "--output-format", "stream-json",
+        "--verbose",
+        build_prompt(spec, cell),
+    ]
+    try:
+        with transcript.open("w", encoding="utf-8") as out:
+            completed = subprocess.run(
+                cmd,
+                cwd=wt,
+                stdout=out,
+                stderr=subprocess.STDOUT,
+                timeout=timeout_s,
+            )
+    except subprocess.TimeoutExpired:
+        return CellResult(cell, wt, transcript, False, None, f"timed out after {timeout_s}s")
+
+    if completed.returncode != 0:
+        return CellResult(cell, wt, transcript, False, None, f"exit {completed.returncode}")
+
+    pr_url: str | None = None
+    for line in transcript.read_text(encoding="utf-8").splitlines():
+        m = PR_URL_RE.search(line)
+        if m:
+            pr_url = m.group(0)
+    return CellResult(cell, wt, transcript, True, pr_url, None)
+
+
+# ---------------------------------------------------------------------- CLI
+
+
+@orchestrate_app.command("run")
+def run(
+    spec_path: Annotated[Path, typer.Argument(help="Path to xtest/features/<name>.yaml")],
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Print the plan, don't dispatch.")
+    ] = False,
+    only: Annotated[
+        list[str] | None,
+        typer.Option("--only", help="Only run these cell keys (repeatable)."),
+    ] = None,
+    timeout_s: Annotated[
+        int, typer.Option("--timeout", help="Per-cell timeout (seconds).")
+    ] = 1800,
+    model: Annotated[
+        str, typer.Option("--model", help="Sub-agent model alias.")
+    ] = "sonnet",
+    transcripts_dir: Annotated[
+        Path,
+        typer.Option(
+            "--transcripts-dir",
+            help="Directory for per-cell JSONL transcripts.",
+        ),
+    ] = Path(".claude/tmp/runs"),
+) -> None:
+    """Fan out per-cell subagents for a multi-repo feature spec."""
+    if not spec_path.is_file():
+        typer.echo(f"Error: {spec_path} not found", err=True)
+        raise typer.Exit(1)
+    try:
+        spec = load_spec(spec_path)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from e
+
+    skip: set[str] = {"tests"}
+    if only:
+        only_set = set(only)
+        unknown = only_set - set(spec.cells)
+        if unknown:
+            typer.echo(f"Error: --only references unknown cell(s): {sorted(unknown)}", err=True)
+            raise typer.Exit(1)
+        skip = skip | (set(spec.cells) - only_set)
+
+    try:
+        waves = topological_waves(spec.cells, skip=skip)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from e
+
+    if dry_run:
+        typer.echo(f"Feature: {spec.name} ({spec.jira or 'no Jira'}) — {spec.title}")
+        for i, wave in enumerate(waves, 1):
+            typer.echo(f"  Wave {i}:")
+            for cell in wave:
+                wt = worktree_for(spec, cell)
+                typer.echo(
+                    f"    - {cell.key}: path={cell.path} branch={cell.branch} worktree={wt}"
+                )
+        return
+
+    failed: set[str] = set()
+    results: list[CellResult] = []
+    for i, wave in enumerate(waves, 1):
+        typer.echo(f"=== Wave {i} ({len(wave)} cells) ===")
+        runnable = [c for c in wave if not (set(c.depends_on) & failed)]
+        for skipped in (c for c in wave if c not in runnable):
+            typer.echo(f"  skipping {skipped.key}: upstream dependency failed")
+            results.append(
+                CellResult(skipped, Path(), Path(), False, None, "upstream dependency failed")
+            )
+            failed.add(skipped.key)
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, len(runnable))) as ex:
+            futures = {
+                ex.submit(
+                    run_cell,
+                    spec,
+                    c,
+                    transcripts_dir=transcripts_dir,
+                    timeout_s=timeout_s,
+                    model=model,
+                ): c
+                for c in runnable
+            }
+            for fut in concurrent.futures.as_completed(futures):
+                r = fut.result()
+                results.append(r)
+                status = "OK" if r.success else "FAIL"
+                detail = r.pr_url or r.error or "(no PR URL)"
+                typer.echo(f"  [{status}] {r.cell.key}: {detail}")
+                if not r.success:
+                    failed.add(r.cell.key)
+
+    typer.echo("")
+    typer.echo("=== Final report ===")
+    typer.echo(f"{'CELL':<24} {'STATUS':<6} PR / ERROR")
+    for r in results:
+        status = "OK" if r.success else "FAIL"
+        rhs = r.pr_url or r.error or "?"
+        typer.echo(f"{r.cell.key:<24} {status:<6} {rhs}")
+
+    if any(not r.success for r in results):
+        raise typer.Exit(1)
diff --git a/otdf-sdk-mgr/tests/test_orchestrate.py b/otdf-sdk-mgr/tests/test_orchestrate.py
new file mode 100644
index 000000000..0507ccba0
--- /dev/null
+++ b/otdf-sdk-mgr/tests/test_orchestrate.py
@@ -0,0 +1,186 @@
+"""Unit tests for the orchestrator's pure-logic pieces.
+
+Subprocess-touching helpers (`ensure_worktree`, `run_cell`) are exercised by
+the smoke test in the project root; here we focus on parsing, topological
+sorting, cycle detection, and pure path resolution.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from otdf_sdk_mgr.cli_orchestrate import (
+    Cell,
+    FeatureSpec,
+    load_spec,
+    topological_waves,
+    worktree_for,
+)
+
+
+def _minimal_spec_yaml() -> str:
+    return """\
+apiVersion: opentdf.io/v1alpha1
+kind: Feature
+metadata:
+  name: ecdsa_binding
+  jira: TEST-1
+  title: "ECDSA cross-SDK"
+  created: 2026-05-18
+repos:
+  tests:
+    branch: TEST-1-tdd
+    todo: [register entry]
+  platform-proto:
+    path: platform
+    branch: TEST-1-proto
+    todo: [add RPC]
+  platform-service:
+    path: platform
+    branch: TEST-1-service
+    depends_on: [platform-proto]
+    todo: [impl rewrap]
+  java-sdk:
+    path: java-sdk
+    branch: TEST-1
+    depends_on: [platform-proto]
+    todo: [impl encrypt]
+scenarios:
+  - xtest/scenarios/test-1.yaml
+"""
+
+
+def _write_spec(tmp_path: Path, body: str) -> Path:
+    p = tmp_path / "feature.yaml"
+    p.write_text(body, encoding="utf-8")
+    return p
+
+
+# ----------------------------------------------------------------- load_spec
+
+
+def test_load_spec_roundtrip(tmp_path: Path) -> None:
+    spec = load_spec(_write_spec(tmp_path, _minimal_spec_yaml()))
+    assert spec.name == "ecdsa_binding"
+    assert spec.jira == "TEST-1"
+    assert spec.title == "ECDSA cross-SDK"
+    assert set(spec.cells) == {"tests", "platform-proto", "platform-service", "java-sdk"}
+    assert spec.cells["platform-service"].depends_on == ("platform-proto",)
+    assert spec.cells["tests"].path is None
+    assert spec.cells["platform-proto"].path == "platform"
+    assert spec.scenarios == ("xtest/scenarios/test-1.yaml",)
+
+
+def test_load_spec_requires_path_for_non_tests(tmp_path: Path) -> None:
+    body = """\
+apiVersion: opentdf.io/v1alpha1
+kind: Feature
+metadata: { name: x, jira: T-1, title: t, created: 2026-05-18 }
+repos:
+  platform-proto:
+    branch: T-1-proto
+    todo: []
+"""
+    with pytest.raises(ValueError, match="path is required"):
+        load_spec(_write_spec(tmp_path, body))
+
+
+def test_load_spec_rejects_unknown_dep(tmp_path: Path) -> None:
+    body = """\
+apiVersion: opentdf.io/v1alpha1
+kind: Feature
+metadata: { name: x, jira: T-1, title: t, created: 2026-05-18 }
+repos:
+  a:
+    path: platform
+    branch: T-1-a
+    depends_on: [b]
+    todo: []
+"""
+    with pytest.raises(ValueError, match="unknown key 'b'"):
+        load_spec(_write_spec(tmp_path, body))
+
+
+# ---------------------------------------------------------- topological_waves
+
+
+def _cell(key: str, deps: tuple[str, ...] = ()) -> Cell:
+    return Cell(key=key, path="x", branch=f"b-{key}", todo=(), depends_on=deps)
+
+
+def test_topo_no_deps_single_wave() -> None:
+    cells = {k: _cell(k) for k in ("a", "b", "c")}
+    waves = topological_waves(cells)
+    assert len(waves) == 1
+    assert sorted(c.key for c in waves[0]) == ["a", "b", "c"]
+
+
+def test_topo_proto_blocks_rest() -> None:
+    cells = {
+        "platform-proto": _cell("platform-proto"),
+        "platform-service": _cell("platform-service", ("platform-proto",)),
+        "java-sdk": _cell("java-sdk", ("platform-proto",)),
+        "web-sdk": _cell("web-sdk", ("platform-proto",)),
+    }
+    waves = topological_waves(cells)
+    assert [sorted(c.key for c in w) for w in waves] == [
+        ["platform-proto"],
+        ["java-sdk", "platform-service", "web-sdk"],
+    ]
+
+
+def test_topo_skip_treats_as_done() -> None:
+    cells = {
+        "tests": _cell("tests"),
+        "platform-proto": _cell("platform-proto", ("tests",)),
+    }
+    waves = topological_waves(cells, skip={"tests"})
+    assert [c.key for w in waves for c in w] == ["platform-proto"]
+
+
+def test_topo_cycle_detected() -> None:
+    cells = {
+        "a": _cell("a", ("b",)),
+        "b": _cell("b", ("a",)),
+    }
+    with pytest.raises(ValueError, match="cycle"):
+        topological_waves(cells)
+
+
+def test_topo_diamond() -> None:
+    # a → b, a → c, b → d, c → d
+    cells = {
+        "a": _cell("a"),
+        "b": _cell("b", ("a",)),
+        "c": _cell("c", ("a",)),
+        "d": _cell("d", ("b", "c")),
+    }
+    waves = topological_waves(cells)
+    assert [sorted(c.key for c in w) for w in waves] == [["a"], ["b", "c"], ["d"]]
+
+
+# ---------------------------------------------------------------- worktree_for
+
+
+def test_worktree_for_uses_jira_key(tmp_path: Path) -> None:
+    spec = load_spec(_write_spec(tmp_path, _minimal_spec_yaml()))
+    wt = worktree_for(spec, spec.cells["platform-proto"])
+    assert wt.name == "TEST-1-platform-proto"
+    assert wt.parent.name == "worktrees"
+
+
+def test_worktree_for_falls_back_to_name_when_no_jira(tmp_path: Path) -> None:
+    body = """\
+apiVersion: opentdf.io/v1alpha1
+kind: Feature
+metadata: { name: ad_hoc, title: t, created: 2026-05-18 }
+repos:
+  platform-proto:
+    path: platform
+    branch: ad-hoc-proto
+    todo: []
+"""
+    spec = load_spec(_write_spec(tmp_path, body))
+    wt = worktree_for(spec, spec.cells["platform-proto"])
+    assert wt.name == "ad_hoc-platform-proto"
diff --git a/xtest/features/CLAUDE.md b/xtest/features/CLAUDE.md
index 9f5e9a7e3..5dd2f9275 100644
--- a/xtest/features/CLAUDE.md
+++ b/xtest/features/CLAUDE.md
@@ -3,11 +3,11 @@
 This directory is owned by two skills:
 
 - **`feature-design`** drafts new spec files here from a Jira ticket (or free-form description) using propose-then-iterate authoring. It also writes the tests-side artifacts that have to land first: the `feature_type` entry in `xtest/tdfs.py`, the scenario under `xtest/scenarios/`, and (if needed) a draft pytest.
-- **`feature-orchestrate`** reads spec files and fans out per-repo subagents that implement the feature in each touched repo and open draft PRs.
+- **`feature-orchestrate`** reads spec files and fans out per-cell subagents (one `claude -p` per cell, each in its own git worktree at `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/`) that implement the cell's work and open draft PRs. Cells run in parallel within each dependency wave.
 
 When you see a `xtest/features/<name>.yaml` referenced:
 
-- It is canonical for the feature's flag name, scope, and per-repo todos.
-- It is NOT canonical for status — query `gh pr list --search "head:<branch>"` per repo.
+- It is canonical for the feature's flag name, scope, per-cell todos, and `depends_on` edges.
+- It is NOT canonical for status — query `gh pr list --search "head:<branch>"` per cell.
 
 Don't hand-author spec files in this directory unless you've also done what `feature-design` would do (add the entry to `feature_type` in `xtest/tdfs.py`, generate the scenario + draft test). Those side effects keep the spec consistent with the tests it depends on.
diff --git a/xtest/features/README.md b/xtest/features/README.md
index 2a1f55510..2d1989857 100644
--- a/xtest/features/README.md
+++ b/xtest/features/README.md
@@ -6,8 +6,8 @@ Each `<feature-name>.yaml` captures:
 
 - The feature flag name — the `supports("<name>")` gate string in `xtest/tdfs.py`.
 - The Jira ticket driving the work, if any.
-- Per-repo todo lists and the shared branch name to use across them.
-- The scenario(s) under `xtest/scenarios/` that exercise the feature once each repo's PR lands.
+- A list of *cells of effort*, each with a target repo (`path:`), a branch, a todo list, and an optional `depends_on:` edge to other cells. A single feature can have multiple cells in the same repo (e.g. `platform-proto`, `platform-service`, `platform-go-sdk` all targeting `platform`), which the orchestrator runs in separate git worktrees.
+- The scenario(s) under `xtest/scenarios/` that exercise the feature once each cell's PR lands.
 
 Specs are declarative — they describe intent, not status. PR state (open / merged / CI passing) is auto-discovered from `gh pr list --search "head:<branch>"` per repo, not stored here.
 

From 4a05aea70d543d46ff1310772253c8f941d38b21 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 19 May 2026 08:58:46 -0400
Subject: [PATCH 38/64] feat(xtest,otdf-sdk-mgr): mechanism-mlkem feature
 design + orchestrate fixes (DSPX-2399/DSPX-3302)

Add pure ML-KEM-768 (FIPS 203) as a new TDF key-wrapping mechanism:
- feature_type "mechanism-mlkem" in tdfs.py (platform gate >= 0.15.0)
- mlkem:768 algorithm + enum 13 in abac.py
- key_mlkem768 / attribute_with_mlkem768_key fixtures in fixtures/keys.py
- test_mlkem768_roundtrip in test_pqc.py (dormant until SDK supports land)
- xtest/features/mechanism-mlkem.yaml spec (DSPX-2399, 5 cells)
- xtest/scenarios/mechanism-mlkem.yaml scenario

Fix feature-orchestrate unattended-run failures:
- Add golangci-lint to platform/otdfctl REPO_ALLOW (was blocking platform-service)
- Disable commit.gpgsign in new worktrees (was blocking java-sdk via 1Password)
- Add deferred signing section to final report with retroactive sign commands

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 .../src/otdf_sdk_mgr/cli_orchestrate.py       | 33 ++++++++++-
 xtest/abac.py                                 |  1 +
 xtest/features/mechanism-mlkem.yaml           | 59 +++++++++++++++++++
 xtest/scenarios/mechanism-mlkem.yaml          | 51 ++++++++++++++++
 xtest/tdfs.py                                 |  6 ++
 xtest/test_pqc.py                             |  5 +-
 6 files changed, 151 insertions(+), 4 deletions(-)
 create mode 100644 xtest/features/mechanism-mlkem.yaml
 create mode 100644 xtest/scenarios/mechanism-mlkem.yaml

diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
index 0a0483278..28c404d7a 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
@@ -193,6 +193,12 @@ def ensure_worktree(spec: FeatureSpec, cell: Cell) -> Path:
     subprocess.check_call(
         ["git", "-C", str(repo), "worktree", "add", str(wt), "-b", cell.branch],
     )
+    # Disable commit signing for unattended runs — no interactive 1Password/GPG
+    # dialog available. The user should re-sign before merging; see sign-off note
+    # in the final report.
+    subprocess.check_call(
+        ["git", "-C", str(wt), "config", "--local", "commit.gpgsign", "false"],
+    )
     return wt
 
 
@@ -210,10 +216,16 @@ def ensure_worktree(spec: FeatureSpec, cell: Cell) -> Path:
 )
 
 REPO_ALLOW: dict[str, tuple[str, ...]] = {
-    "platform": ("Bash(go *)", "Bash(make *)", "Bash(buf *)", "Bash(yq *)"),
+    "platform": (
+        "Bash(go *)",
+        "Bash(make *)",
+        "Bash(buf *)",
+        "Bash(yq *)",
+        "Bash(golangci-lint *)",
+    ),
     "java-sdk": ("Bash(mvn *)", "Bash(./mvnw *)"),
     "web-sdk": ("Bash(npm *)", "Bash(pnpm *)", "Bash(node *)"),
-    "otdfctl": ("Bash(go *)", "Bash(make *)"),
+    "otdfctl": ("Bash(go *)", "Bash(make *)", "Bash(golangci-lint *)"),
 }
 
 
@@ -256,6 +268,8 @@ def ensure_subagent_settings(worktree: Path, repo_path: str | None) -> None:
 2. Run the repo's local checks before committing (unit tests, linters, build).
 3. Commit using house-style subject: `<type>({path}): <description> ({jira})`.
    No `Jira:` footer. Add `Co-Authored-By: Claude` to the message.
+   Note: commit.gpgsign has been set to false in this worktree — commit normally
+   without any signing flags. The user will sign commits before merging.
 4. Open a draft PR via `gh pr create --draft --title "<same as commit subject>" --body "..."`.
    PR body references the parent Jira (https://virtru.atlassian.net/browse/{jira})
    and the tests-side scenario(s): {scenarios}.
@@ -447,5 +461,20 @@ def run(
         rhs = r.pr_url or r.error or "?"
         typer.echo(f"{r.cell.key:<24} {status:<6} {rhs}")
 
+    signed_off = [r for r in results if r.success and r.worktree != Path()]
+    if signed_off:
+        typer.echo("")
+        typer.echo("=== Deferred signing ===")
+        typer.echo(
+            "Commits were made with commit.gpgsign=false (unattended run).\n"
+            "To retroactively sign all commits on each branch before merging,\n"
+            "run the following for each worktree:"
+        )
+        for r in signed_off:
+            typer.echo(
+                f"  git -C {r.worktree} rebase HEAD~$(git -C {r.worktree} rev-list"
+                f" --count origin/HEAD..HEAD) --exec 'git commit --amend --no-edit -S'"
+            )
+
     if any(not r.success for r in results):
         raise typer.Exit(1)
diff --git a/xtest/abac.py b/xtest/abac.py
index bfb322e38..523436dfd 100644
--- a/xtest/abac.py
+++ b/xtest/abac.py
@@ -187,6 +187,7 @@ class KasGrantValue(BaseModelIgnoreExtra):
 KAS_PUBLIC_KEY_ALG_ENUM_HPQT_XWING = 10
 KAS_PUBLIC_KEY_ALG_ENUM_HPQT_SECP256R1_MLKEM768 = 11
 KAS_PUBLIC_KEY_ALG_ENUM_HPQT_SECP384R1_MLKEM1024 = 12
+KAS_PUBLIC_KEY_ALG_ENUM_MLKEM_768 = 13
 
 # Pure ML-KEM enums match protobuf ALGORITHM_MLKEM_768/1024 in platform PR #3537.
 KAS_PUBLIC_KEY_ALG_ENUM_MLKEM_768 = 20
diff --git a/xtest/features/mechanism-mlkem.yaml b/xtest/features/mechanism-mlkem.yaml
new file mode 100644
index 000000000..d2d527c6a
--- /dev/null
+++ b/xtest/features/mechanism-mlkem.yaml
@@ -0,0 +1,59 @@
+apiVersion: opentdf.io/v1alpha1
+kind: Feature
+metadata:
+  name: mechanism-mlkem
+  jira: DSPX-2399
+  title: "Pure ML-KEM-768 post-quantum key encapsulation mechanism"
+  created: 2026-05-18
+repos:
+  tests:
+    branch: DSPX-2399-tests
+    todo:
+      - Add "mechanism-mlkem" to feature_type Literal in xtest/tdfs.py (alphabetically after mechanism-ec-curves-384-521)
+      - Add platform version gate (self.semver >= (0, 15, 0)) in PlatformFeatureSet.__init__ — version TBD
+      - Add "mlkem:768" to kas_algorithm_type in xtest/abac.py + KAS_PUBLIC_KEY_ALG_ENUM_MLKEM_768 = 13 + mapping entries
+      - Add key_mlkem768 fixture in xtest/fixtures/keys.py
+      - Add attribute_with_mlkem768_key fixture in xtest/fixtures/keys.py
+      - Add test_mlkem768_roundtrip in xtest/test_pqc.py
+      - Wire format — KAO type "wrapped"; wrappedKey = base64(ml_kem_ciphertext [1088 bytes] || aes_wrapped_dek); no ephemeralPublicKey
+  platform-proto:
+    path: platform
+    branch: DSPX-2399-platform-proto
+    todo:
+      - Add KAS_PUBLIC_KEY_ALG_ENUM_MLKEM_768 = 13 to KasPublicKeyAlgEnum in service/policy/objects.proto
+      - Run buf generate; commit regenerated Go/Java/JS stubs
+  platform-service:
+    path: platform
+    branch: DSPX-2399-platform-service
+    depends_on: [platform-proto]
+    todo:
+      - Add mlkem:768 KeyType to lib/ocrypto (or integrate a Go ML-KEM library)
+      - Implement ML-KEM-768 decapsulation in service/kas/access/rewrap.go; split wrappedKey at byte 1088 to extract ciphertext; decapsulate to recover shared secret; unwrap DEK from remainder
+      - Add convertAlgEnum2Simple / convertStringToAlgorithm mappings for KAS_PUBLIC_KEY_ALG_ENUM_MLKEM_768
+      - Gate behind preview flag in opentdf.yaml / opentdf-dev.yaml if needed; ensure test harness enables it
+  platform-go-sdk:
+    path: platform
+    branch: DSPX-2399-platform-go-sdk
+    depends_on: [platform-proto, platform-service]
+    todo:
+      - Implement ML-KEM-768 client-side encapsulation; emit KAO type "wrapped" with wrappedKey = base64(ml_kem_ciphertext [1088 bytes] || aes_wrapped_dek); no ephemeralPublicKey field
+      - Add `supports mechanism-mlkem` case to xtest/sdk/go/cli.sh (grep for mlkem:768 in `help policy kas-registry key create`)
+  java-sdk:
+    path: java-sdk
+    branch: DSPX-2399-java-sdk
+    depends_on: [platform-proto]
+    todo:
+      - Add MLKEM_768 entry to KeyType.java enum + fromPublicKeyAlgorithm / fromAlgorithm mappings
+      - Implement ML-KEM-768 encapsulation (Bouncy Castle post-quantum provider); same wire format as Go SDK
+      - Add `supports mechanism-mlkem` case to xtest/sdk/java/cli.sh
+  web-sdk:
+    path: web-sdk
+    branch: DSPX-2399-web-sdk
+    depends_on: [platform-proto]
+    todo:
+      - Add "mlkem:768" to KasPublicKeyAlgorithm union in lib/src/access.ts
+      - Add ML-KEM-768 enum entry in lib/src/crypto/enums.ts
+      - Implement encapsulation/decapsulation via @noble/post-quantum or WASM library; same wire format
+      - Add `supports mechanism-mlkem` case to xtest/sdk/js/cli.sh
+scenarios:
+  - xtest/scenarios/mechanism-mlkem.yaml
diff --git a/xtest/scenarios/mechanism-mlkem.yaml b/xtest/scenarios/mechanism-mlkem.yaml
new file mode 100644
index 000000000..4416ef1db
--- /dev/null
+++ b/xtest/scenarios/mechanism-mlkem.yaml
@@ -0,0 +1,51 @@
+apiVersion: opentdf.io/v1alpha1
+kind: Scenario
+metadata:
+  id: mechanism-mlkem
+  title: "Pure ML-KEM-768 post-quantum key encapsulation mechanism (DSPX-2399)"
+  created: "2026-05-18"
+instance:
+  metadata:
+    name: mechanism-mlkem
+  platform:
+    source:
+      ref: main
+  ports:
+    base: 8080
+  kas:
+    alpha:
+      source:
+        ref: main
+      mode: standard
+    km1:
+      source:
+        ref: main
+      mode: key_management
+    km2:
+      source:
+        ref: main
+      mode: key_management
+sdks:
+  encrypt:
+    go: { version: main }
+    java: { version: main }
+    js: { version: main }
+  decrypt:
+    go: { version: main }
+    java: { version: main }
+    js: { version: main }
+suite:
+  select: "xtest/test_pqc.py::test_mlkem768_roundtrip"
+  containers: ztdf
+expected: >-
+  test_mlkem768_roundtrip passes for each SDK pair: the SDK encrypts a TDF
+  with the mlkem:768 key assigned to the attribute, producing a KAO with
+  type "wrapped" and wrappedKey containing the ML-KEM-768 ciphertext (1088 bytes)
+  concatenated with the AES-wrapped DEK; no ephemeralPublicKey is present.
+  Every other SDK decrypts successfully and the roundtrip file comparison passes.
+actual: >-
+  Feature not implemented. No supports mechanism-mlkem gate exists in any SDK
+  wrapper; mlkem:768 is not yet a supported algorithm in platform or any SDK;
+  tests skip uniformly (platform version gate requires >= 0.15.0 and SDK-level
+  supports check fails) until platform-proto, platform-service, platform-go-sdk,
+  java-sdk, and web-sdk PRs all land.
diff --git a/xtest/tdfs.py b/xtest/tdfs.py
index 560ea5a8b..9ab9b9bce 100644
--- a/xtest/tdfs.py
+++ b/xtest/tdfs.py
@@ -119,6 +119,8 @@ def is_sdk_type(val: str) -> TypeIs[sdk_type]:
     "mechanism-rsa-4096",
     # Support for encrypting with EC curves secp384r1 and secp521r1 managed keys.
     "mechanism-ec-curves-384-521",
+    # Support for encrypting with pure ML-KEM-768 post-quantum KEM (FIPS 203 / CRYSTALS-Kyber-768).
+    "mechanism-mlkem",
     # Support for encrypting with X-Wing hybrid post-quantum/traditional KEM.
     "mechanism-xwing",
     # Support for encrypting with hybrid post-quantum/traditional KEM with NIST Elliptic Curves.
@@ -221,6 +223,10 @@ def __init__(self, **kwargs: dict[str, Any]):
             if any(a.startswith("mlkem:") for a in algs):
                 self.features.add("mechanism-mlkem")
 
+        # Pure ML-KEM-768 KEM support (FIPS 203 / CRYSTALS-Kyber-768)
+        if self.semver >= (0, 15, 0):  # version TBD — update when platform milestone is set
+            self.features.add("mechanism-mlkem")
+
         print(f"PLATFORM_VERSION '{v}' supports [{', '.join(self.features)}]")
 
     def skip_if_unsupported(self, *features: feature_type):
diff --git a/xtest/test_pqc.py b/xtest/test_pqc.py
index b2fe7d6dd..6af33b96f 100644
--- a/xtest/test_pqc.py
+++ b/xtest/test_pqc.py
@@ -1,7 +1,8 @@
-"""Tests for hybrid post-quantum/traditional KEM.
+"""Tests for hybrid and pure post-quantum KEM mechanisms.
 
 These tests verify that TDF encryption and decryption work correctly when
-X-Wing and NIST approved hybrid managed keys are assigned to attributes via the policy service.
+X-Wing, NIST-curve hybrid, and pure ML-KEM managed keys are assigned to attributes
+via the policy service.
 """
 
 import base64

From 21a85b5d9826a060bbe9b23db8ce4927eda22a76 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 19 May 2026 14:56:17 -0400
Subject: [PATCH 39/64] feat(otdf-sdk-mgr,.claude): push tests-side draft PR in
 Wave 1 for TDD workflow (DSPX-3302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The orchestrator now handles the `tests` cell directly — push branch + open
draft PR — in Wave 1 alongside `platform-proto`, rather than skipping it.
This makes the dormant test definitions visible to downstream SDK CI jobs early,
enabling a TDD/BDD approach where each per-repo PR can validate against the
test suite as it adds its `supports <feature>` case.

- Add TESTS_REPO constant and run_tests_cell() (push + idempotent gh pr create)
- Default skip set is now empty; --only still works as before
- Dry-run labels the tests cell action=push+draft-PR
- _dispatch() routes tests cell to run_tests_cell, others to run_cell
- Deferred signing section excludes the tests cell (user signed those commits)
- Update SKILL.md description and body to reflect TDD lifecycle + new behavior
- Fix module docstring (no longer says tests cell is skipped)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .claude/skills/feature-orchestrate/SKILL.md   |   8 +-
 .../src/otdf_sdk_mgr/cli_orchestrate.py       | 118 ++++++++++++++----
 2 files changed, 100 insertions(+), 26 deletions(-)

diff --git a/.claude/skills/feature-orchestrate/SKILL.md b/.claude/skills/feature-orchestrate/SKILL.md
index 4732abece..bf31715f1 100644
--- a/.claude/skills/feature-orchestrate/SKILL.md
+++ b/.claude/skills/feature-orchestrate/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: feature-orchestrate
-description: Fan out per-cell subagents to implement a multi-repo feature described by `xtest/features/<name>.yaml`. Reads the spec, creates one git worktree per cell at `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/`, topologically sorts cells by `depends_on`, and launches `claude -p` subagents in parallel within each wave. Each subagent implements its cell and opens a draft PR. Use after `feature-design` has produced the spec and the tests-side PR is in flight (or merged).
+description: Coordinate a TDD multi-repo feature implementation. Pushes the tests-side draft PR in Wave 1 (so SDK subagents can run CI against the test definitions), then fans out one `claude -p` subagent per implementation cell — each in its own git worktree — to implement, commit, and open draft PRs across platform, java-sdk, web-sdk, and other repos in dependency order. Use when `feature-design` has finished and you're ready to dispatch cross-repo implementation.
 allowed-tools: Bash, Read
 ---
 
@@ -26,7 +26,7 @@ Before dispatching, run a dry-run so the user can confirm the topology and pinni
 uv run otdf-sdk-mgr orchestrate run xtest/features/<name>.yaml --dry-run
 ```
 
-The output names each cell, its target repo path, the branch it'll work on, and the worktree path the orchestrator will create. Each wave is a set of cells with no dependencies between them; cells in a later wave have at least one `depends_on` edge into an earlier wave.
+The output names each cell, its target repo path, the branch it'll work on, and the worktree path the orchestrator will create (or `action=push+draft-PR` for the `tests` cell). Each wave is a set of cells with no dependencies between them; cells in a later wave have at least one `depends_on` edge into an earlier wave.
 
 Surface the dry-run output to the user verbatim. If anything looks wrong (a cell going to the wrong repo, a missing `depends_on` edge, a stale branch name), ask the user to fix the spec via `feature-design` (or edit it directly) before proceeding.
 
@@ -53,6 +53,7 @@ When the orchestrator finishes, it prints a final table:
 
 ```
 CELL                     STATUS PR / ERROR
+tests                    OK     https://github.com/opentdf/tests/pull/123
 platform-proto           OK     https://github.com/opentdf/platform/pull/1234
 platform-service         OK     https://github.com/opentdf/platform/pull/1235
 java-sdk                 OK     https://github.com/opentdf/java-sdk/pull/567
@@ -68,7 +69,8 @@ Pass the table on to the user, plus the JSONL transcript paths for any FAIL rows
 
 ## Notes
 
-- This skill **does not edit the `tests/` repo**. The `tests` cell in the spec is owned by `feature-design`; the orchestrator skips it. If the tests-side PR isn't merged yet, that's fine — the subagent PRs will run their CI against the SDK changes, and the dormant tests in `tests/main` only activate once each repo's `supports("<feature>")` case lands.
+- **TDD/BDD lifecycle.** The `tests` cell is handled differently from all other cells: the orchestrator pushes the branch and opens a draft PR directly (no subagent) in Wave 1, alongside `platform-proto`. This makes the dormant tests visible to CI early — each SDK's per-repo PR can link back to the tests PR, and once that repo adds a `supports <feature>` case to its CLI wrapper, its CI activates the relevant tests automatically. No cross-PR lockstep coordination is needed.
+- **The `tests` cell is never skipped automatically.** If `feature-design` produced the tests-side artifacts on the current branch, the orchestrator pushes that branch and opens the draft PR. If the tests repo is on a different branch, the orchestrator reports an error rather than silently skipping.
 - Worktrees live at `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/` regardless of which repo they came from. The user's main checkouts (`~/Documents/GitHub/opentdf/{platform,java-sdk,web-sdk,otdfctl}/`) are never modified.
 - Subagents print the PR URL on their last line of output as a contract — the orchestrator parses it with a regex. If a subagent doesn't print one, the orchestrator reports the cell as "no PR URL" but doesn't mark it failed (the subagent may have done useful work even if the PR step failed).
 - The orchestrator dispatches subagents in parallel within a wave, so per-cell logs interleave in real time but each cell's full transcript lands in its own JSONL file. Inspect transcripts under `.claude/tmp/runs/`.
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
index 28c404d7a..9e1e1665c 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
@@ -1,13 +1,13 @@
 """`otdf-sdk-mgr orchestrate` subcommands.
 
 Read a multi-repo feature spec from `xtest/features/<name>.yaml`, topologically
-sort the cells by `depends_on`, create one git worktree per cell at
-`~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/`, and fan out `claude -p`
-subagents to implement each cell in parallel within each wave. Each subagent
-opens a draft PR and prints its URL as the last line of stdout.
+sort the cells by `depends_on`, and drive implementation in dependency waves.
 
-The `tests` cell is skipped — `feature-design` already produced its artifacts
-(scenario, draft test, `feature_type` entry).
+TDD lifecycle: the `tests` cell is handled in Wave 1 — the orchestrator pushes
+the branch and opens a draft PR directly (no subagent), so SDK CI jobs can
+reference the test definitions as they land. All other cells get a git worktree
+at `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/` and a `claude -p`
+subagent that implements, commits, and opens a draft PR.
 """
 
 from __future__ import annotations
@@ -158,6 +158,7 @@ def topological_waves(
 
 OPENTDF_ROOT = Path.home() / "Documents/GitHub/opentdf"
 WORKTREES_ROOT = Path.home() / "Documents/GitHub/worktrees"
+TESTS_REPO = OPENTDF_ROOT / "tests"
 
 
 def worktree_for(spec: FeatureSpec, cell: Cell) -> Path:
@@ -357,6 +358,71 @@ def run_cell(
     return CellResult(cell, wt, transcript, True, pr_url, None)
 
 
+def run_tests_cell(spec: FeatureSpec, cell: Cell) -> CellResult:
+    """Push the tests branch and open a draft PR without launching a subagent.
+
+    feature-design already wrote the tests-side artifacts; this step makes them
+    visible to downstream CI by pushing the branch and opening a PR. Commits
+    were made by the user (signed normally), so deferred signing doesn't apply.
+    """
+    repo = TESTS_REPO
+    if not repo.is_dir():
+        return CellResult(cell, Path(), Path(), False, None, f"tests repo not found: {repo}")
+
+    try:
+        current = subprocess.check_output(
+            ["git", "-C", str(repo), "branch", "--show-current"], text=True
+        ).strip()
+    except subprocess.CalledProcessError as e:
+        return CellResult(cell, Path(), Path(), False, None, f"git branch check failed: {e}")
+
+    if current != cell.branch:
+        return CellResult(
+            cell, Path(), Path(), False, None,
+            f"tests repo is on branch '{current}', expected '{cell.branch}' — "
+            "did feature-design run on this branch?",
+        )
+
+    try:
+        subprocess.check_call(
+            ["git", "-C", str(repo), "push", "-u", "origin", cell.branch],
+        )
+    except subprocess.CalledProcessError as e:
+        return CellResult(cell, Path(), Path(), False, None, f"git push failed: {e}")
+
+    # Reuse an existing PR rather than creating a duplicate.
+    existing = subprocess.run(
+        ["gh", "pr", "list", "--head", cell.branch, "--json", "url", "--jq", ".[0].url"],
+        cwd=str(repo),
+        capture_output=True,
+        text=True,
+    )
+    if existing.returncode == 0 and existing.stdout.strip():
+        return CellResult(cell, Path(), Path(), True, existing.stdout.strip(), None)
+
+    jira = spec.jira or spec.name
+    pr_title = f"test(tests): {spec.title} ({jira})"
+    jira_url = f"https://virtru.atlassian.net/browse/{jira}"
+    scenarios_str = ", ".join(spec.scenarios) or "(none)"
+    pr_body = (
+        f"Tests-side artifacts for [{jira}]({jira_url}).\n\n"
+        f"Scenarios: {scenarios_str}\n\n"
+        "Tests land dormant — they stay skipped until each per-repo PR adds a "
+        "`supports <feature>` case to its SDK CLI wrapper."
+    )
+    try:
+        out = subprocess.check_output(
+            ["gh", "pr", "create", "--draft", "--title", pr_title, "--body", pr_body],
+            cwd=str(repo),
+            text=True,
+        )
+    except subprocess.CalledProcessError as e:
+        return CellResult(cell, Path(), Path(), False, None, f"gh pr create failed: {e}")
+
+    m = PR_URL_RE.search(out)
+    return CellResult(cell, Path(), Path(), True, m.group(0) if m else None, None)
+
+
 # ---------------------------------------------------------------------- CLI
 
 
@@ -394,14 +460,14 @@ def run(
         typer.echo(f"Error: {e}", err=True)
         raise typer.Exit(1) from e
 
-    skip: set[str] = {"tests"}
+    skip: set[str] = set()
     if only:
         only_set = set(only)
         unknown = only_set - set(spec.cells)
         if unknown:
             typer.echo(f"Error: --only references unknown cell(s): {sorted(unknown)}", err=True)
             raise typer.Exit(1)
-        skip = skip | (set(spec.cells) - only_set)
+        skip = set(spec.cells) - only_set
 
     try:
         waves = topological_waves(spec.cells, skip=skip)
@@ -414,10 +480,16 @@ def run(
         for i, wave in enumerate(waves, 1):
             typer.echo(f"  Wave {i}:")
             for cell in wave:
-                wt = worktree_for(spec, cell)
-                typer.echo(
-                    f"    - {cell.key}: path={cell.path} branch={cell.branch} worktree={wt}"
-                )
+                if cell.key == "tests":
+                    typer.echo(
+                        f"    - {cell.key}: path=(tests repo) branch={cell.branch}"
+                        f" action=push+draft-PR"
+                    )
+                else:
+                    wt = worktree_for(spec, cell)
+                    typer.echo(
+                        f"    - {cell.key}: path={cell.path} branch={cell.branch} worktree={wt}"
+                    )
         return
 
     failed: set[str] = set()
@@ -432,18 +504,18 @@ def run(
             )
             failed.add(skipped.key)
 
+        def _dispatch(c: Cell) -> CellResult:
+            if c.key == "tests":
+                return run_tests_cell(spec, c)
+            return run_cell(
+                spec, c,
+                transcripts_dir=transcripts_dir,
+                timeout_s=timeout_s,
+                model=model,
+            )
+
         with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, len(runnable))) as ex:
-            futures = {
-                ex.submit(
-                    run_cell,
-                    spec,
-                    c,
-                    transcripts_dir=transcripts_dir,
-                    timeout_s=timeout_s,
-                    model=model,
-                ): c
-                for c in runnable
-            }
+            futures = {ex.submit(_dispatch, c): c for c in runnable}
             for fut in concurrent.futures.as_completed(futures):
                 r = fut.result()
                 results.append(r)

From d1d48c949e8d49ecf51b5d20460eb4ba2ecc5392 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 19 May 2026 15:00:03 -0400
Subject: [PATCH 40/64] feat(otdf-sdk-mgr,.claude): idempotent orchestrate run
 + --force flag (DSPX-3302)

Re-running `orchestrate run` after a partial failure now resumes from where
it left off: cells whose branch already has an open PR are skipped (reported
as OK with the existing URL), and only failed/pending cells are dispatched.

- Add check_existing_pr() helper (gh pr list --head <branch>)
- run_cell() checks for existing PR before creating worktree or launching subagent
- --force flag bypasses the idempotency check (re-run even with existing PR)
- Dry-run annotates already-done cells with [PR EXISTS: <url>]
- SKILL.md: update Step 1/2 + replace "When to use partial runs" with
  "Resumption and partial runs" covering fix-and-retry, staging, and --force

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .claude/skills/feature-orchestrate/SKILL.md   | 20 +++++++---
 .../src/otdf_sdk_mgr/cli_orchestrate.py       | 37 ++++++++++++++++++-
 2 files changed, 50 insertions(+), 7 deletions(-)

diff --git a/.claude/skills/feature-orchestrate/SKILL.md b/.claude/skills/feature-orchestrate/SKILL.md
index bf31715f1..ba12155df 100644
--- a/.claude/skills/feature-orchestrate/SKILL.md
+++ b/.claude/skills/feature-orchestrate/SKILL.md
@@ -26,7 +26,7 @@ Before dispatching, run a dry-run so the user can confirm the topology and pinni
 uv run otdf-sdk-mgr orchestrate run xtest/features/<name>.yaml --dry-run
 ```
 
-The output names each cell, its target repo path, the branch it'll work on, and the worktree path the orchestrator will create (or `action=push+draft-PR` for the `tests` cell). Each wave is a set of cells with no dependencies between them; cells in a later wave have at least one `depends_on` edge into an earlier wave.
+The output names each cell, its target repo path, the branch it'll work on, and the worktree path the orchestrator will create (or `action=push+draft-PR` for the `tests` cell). Cells that already have an open PR are annotated with `[PR EXISTS: <url>]` — those will be skipped on the real run (no subagent launched). Each wave is a set of cells with no dependencies between them; cells in a later wave have at least one `depends_on` edge into an earlier wave.
 
 Surface the dry-run output to the user verbatim. If anything looks wrong (a cell going to the wrong repo, a missing `depends_on` edge, a stale branch name), ask the user to fix the spec via `feature-design` (or edit it directly) before proceeding.
 
@@ -38,7 +38,9 @@ When the user confirms, run for real:
 uv run otdf-sdk-mgr orchestrate run xtest/features/<name>.yaml
 ```
 
-For each cell, the orchestrator:
+The run is **idempotent**: cells whose branch already has an open PR are reported as `OK` with the existing PR URL and no subagent is launched. Re-running after a partial failure resumes from where it left off — already-done cells are skipped, failed or not-yet-started cells are dispatched. Use `--force` to re-run a cell even if it already has a PR (e.g. to incorporate spec changes into an existing draft).
+
+For each cell that needs work, the orchestrator:
 
 1. Creates `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/` as a worktree of `~/Documents/GitHub/opentdf/<path>` on branch `<cell.branch>`. Idempotent — reuses an existing worktree if it's already on the right branch, bails if it's on a different one.
 2. Writes a minimal `.claude/settings.json` into the worktree (allowing `git`, `gh pr create`, and the repo-type-appropriate test commands: `go`/`make`/`buf` for platform, `mvn` for java-sdk, `npm` for web-sdk).
@@ -62,10 +64,18 @@ web-sdk                  FAIL   exit 1
 
 Pass the table on to the user, plus the JSONL transcript paths for any FAIL rows so they can inspect what went wrong.
 
-## When to use partial runs
+## Resumption and partial runs
+
+**Resuming after a failure** — just re-run the same command. The orchestrator skips cells that already have open PRs and only dispatches the ones that failed or were skipped due to upstream failures. The dependency check still runs: if a cell's `depends_on` failed in the previous wave, it will be skipped again rather than dispatched into a broken state. Fix the upstream cell first (see below), then re-run.
+
+**Fixing a failed cell** — inspect the transcript at `.claude/tmp/runs/<JIRA-KEY>-<cell-key>.jsonl`, identify the problem, fix it (in the worktree at `~/Documents/GitHub/worktrees/<JIRA-KEY>-<cell-key>/` or by patching the spec), then re-run. If the fix was in the worktree (e.g. the subagent left partial commits), you may want `--only <cell-key>` to avoid redundant PR-existence checks across many cells.
 
-- `--only platform-proto` — proto change has to ship before anything else can adopt the new bindings. Run the proto cell alone first, review the PR, merge it, then run the rest.
-- `--only java-sdk` — re-launch a single failed cell after fixing whatever broke. The dependency check still runs; if `java-sdk`'s `depends_on` failed earlier, the orchestrator will refuse rather than racing.
+**Staging a cell before its dependents** — `--only platform-proto` runs only the proto cell. Once its PR is reviewed and merged, re-run without `--only` and the orchestrator picks up from the next wave (proto cell already has a PR, so it's skipped; service/SDK cells proceed).
+
+**Forcing a re-run** — `--force` makes the orchestrator ignore existing PRs and dispatch a fresh subagent for every non-skipped cell. Combine with `--only` to force just one cell:
+```bash
+uv run otdf-sdk-mgr orchestrate run xtest/features/<name>.yaml --only java-sdk --force
+```
 
 ## Notes
 
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
index 9e1e1665c..0c514e467 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
@@ -299,6 +299,19 @@ def build_prompt(spec: FeatureSpec, cell: Cell) -> str:
 PR_URL_RE = re.compile(r"https://github\.com/[^\s]+/pull/\d+")
 
 
+def check_existing_pr(repo: Path, branch: str) -> str | None:
+    """Return the URL of an open PR for this branch in the given repo, or None."""
+    result = subprocess.run(
+        ["gh", "pr", "list", "--head", branch, "--json", "url", "--jq", ".[0].url"],
+        cwd=str(repo),
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip()
+    return None
+
+
 @dataclass
 class CellResult:
     cell: Cell
@@ -316,7 +329,16 @@ def run_cell(
     transcripts_dir: Path,
     timeout_s: int,
     model: str,
+    force: bool = False,
 ) -> CellResult:
+    # Idempotency: skip cells whose branch already has an open PR, unless --force.
+    if not force:
+        repo = OPENTDF_ROOT / (cell.path or "")
+        if repo.is_dir():
+            existing_pr = check_existing_pr(repo, cell.branch)
+            if existing_pr:
+                return CellResult(cell, Path(), Path(), True, existing_pr, None)
+
     try:
         wt = ensure_worktree(spec, cell)
     except Exception as e:
@@ -442,6 +464,10 @@ def run(
     model: Annotated[
         str, typer.Option("--model", help="Sub-agent model alias.")
     ] = "sonnet",
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Re-run cells even if they already have open PRs."),
+    ] = False,
     transcripts_dir: Annotated[
         Path,
         typer.Option(
@@ -481,14 +507,20 @@ def run(
             typer.echo(f"  Wave {i}:")
             for cell in wave:
                 if cell.key == "tests":
+                    existing = check_existing_pr(TESTS_REPO, cell.branch)
+                    pr_note = f" [PR EXISTS: {existing}]" if existing else ""
                     typer.echo(
                         f"    - {cell.key}: path=(tests repo) branch={cell.branch}"
-                        f" action=push+draft-PR"
+                        f" action=push+draft-PR{pr_note}"
                     )
                 else:
+                    repo = OPENTDF_ROOT / (cell.path or "")
+                    existing = check_existing_pr(repo, cell.branch) if repo.is_dir() else None
+                    pr_note = f" [PR EXISTS: {existing}]" if existing else ""
                     wt = worktree_for(spec, cell)
                     typer.echo(
-                        f"    - {cell.key}: path={cell.path} branch={cell.branch} worktree={wt}"
+                        f"    - {cell.key}: path={cell.path} branch={cell.branch}"
+                        f" worktree={wt}{pr_note}"
                     )
         return
 
@@ -512,6 +544,7 @@ def _dispatch(c: Cell) -> CellResult:
                 transcripts_dir=transcripts_dir,
                 timeout_s=timeout_s,
                 model=model,
+                force=force,
             )
 
         with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, len(runnable))) as ex:

From 402ef4bd5d836ea2338744f1a5b3d5290b520c97 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 19 May 2026 15:14:52 -0400
Subject: [PATCH 41/64] feat(otdf-sdk-mgr): add xtest feature detection context
 to subagent prompt (DSPX-3302)

Subagents now receive an explanation of why `supports <feature>` must be added
to the SDK CLI wrapper and how xtest uses it to activate dormant tests. Includes
the pattern for probing SDK capabilities and a reminder that the scenario(s) are
listed in the PR body.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/otdf_sdk_mgr/cli_orchestrate.py       | 22 ++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
index 0c514e467..feefe8131 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
@@ -264,7 +264,27 @@ def ensure_subagent_settings(worktree: Path, repo_path: str | None) -> None:
 {body}
 --- END SPEC ---
 
-Instructions:
+## xtest feature detection
+
+The `tests` repo has a draft PR with dormant integration tests for this feature.
+The tests stay skipped until the SDK CLI wrapper reports support. xtest detects
+support by running:
+
+    <sdk-cli> supports {name}
+
+and expecting exit 0. Your todo list includes adding a `supports {name}` case
+to the SDK's `xtest/sdk/<lang>/cli.sh` wrapper. This is what activates the
+integration tests when your PR's CI runs — do not skip it.
+
+Look at existing `supports` cases already in the file for the pattern (they
+typically grep the SDK's own help or capability output for a feature string,
+e.g. `grep -q "mlkem:768" <<< "$(cli help ...)"` or a direct SDK call). The
+specific probe to use is noted in your todo list item.
+
+Related test scenario(s): {scenarios}
+
+## Instructions
+
 1. Implement every item in `repos.{cell_key}.todo`. Don't switch branches.
 2. Run the repo's local checks before committing (unit tests, linters, build).
 3. Commit using house-style subject: `<type>({path}): <description> ({jira})`.

From 13424da56f5f705c95d306c3679cf77e3eb01bcf Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 12:22:44 -0400
Subject: [PATCH 42/64] fix(otdf-sdk-mgr): resolve tests repo from CWD in
 orchestrate run (DSPX-3302)

run_tests_cell previously hardcoded TESTS_REPO = ~/Documents/GitHub/opentdf/tests,
which caused [FAIL] tests: tests repo is on branch 'main', expected '<branch>'
when orchestrate was invoked from a tests worktree (the canonical checkout
typically stays on main while the user works from a worktree on the feature
branch). Now both run_tests_cell and the dry-run path resolve the repo via
git rev-parse --show-toplevel, so orchestrate works from any tests worktree
on the cell branch.

Wrong-branch errors are preserved with a clearer message pointing the user
to run from a tests worktree on the feature branch.

Tests added in test_orchestrate.py mock subprocess to cover both the success
path (CWD-resolved repo pushes + opens draft PR) and the wrong-branch error.

ruff format also normalized several pre-existing wrap points in
cli_orchestrate.py / tests/test_schema_sync.py to fit within line-length=100;
included here so the next commit isn't polluted by them.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../src/otdf_sdk_mgr/cli_orchestrate.py       | 74 +++++++++------
 otdf-sdk-mgr/tests/test_orchestrate.py        | 89 ++++++++++++++++++-
 2 files changed, 137 insertions(+), 26 deletions(-)

diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
index feefe8131..3e4d84ced 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_orchestrate.py
@@ -89,9 +89,7 @@ def load_spec(path: Path) -> FeatureSpec:
             raise ValueError(f"{path}: repos.{key}.depends_on must be a list")
         repo_path = entry.get("path")
         if key != "tests" and not isinstance(repo_path, str):
-            raise ValueError(
-                f"{path}: repos.{key}.path is required for non-tests cells"
-            )
+            raise ValueError(f"{path}: repos.{key}.path is required for non-tests cells")
         cells[key] = Cell(
             key=key,
             path=repo_path,
@@ -120,9 +118,7 @@ def load_spec(path: Path) -> FeatureSpec:
 # ------------------------------------------------------------------ topo sort
 
 
-def topological_waves(
-    cells: dict[str, Cell], *, skip: Iterable[str] = ()
-) -> list[list[Cell]]:
+def topological_waves(cells: dict[str, Cell], *, skip: Iterable[str] = ()) -> list[list[Cell]]:
     """Group cells into dependency waves; cells within a wave are independent.
 
     Skipped cells are treated as already-done (their dependents see them as
@@ -158,7 +154,6 @@ def topological_waves(
 
 OPENTDF_ROOT = Path.home() / "Documents/GitHub/opentdf"
 WORKTREES_ROOT = Path.home() / "Documents/GitHub/worktrees"
-TESTS_REPO = OPENTDF_ROOT / "tests"
 
 
 def worktree_for(spec: FeatureSpec, cell: Cell) -> Path:
@@ -370,10 +365,14 @@ def run_cell(
     transcript = transcripts_dir / f"{spec.jira or spec.name}-{cell.key}.jsonl"
 
     cmd = [
-        "claude", "-p",
-        "--model", model,
-        "--permission-mode", "acceptEdits",
-        "--output-format", "stream-json",
+        "claude",
+        "-p",
+        "--model",
+        model,
+        "--permission-mode",
+        "acceptEdits",
+        "--output-format",
+        "stream-json",
         "--verbose",
         build_prompt(spec, cell),
     ]
@@ -403,13 +402,27 @@ def run_cell(
 def run_tests_cell(spec: FeatureSpec, cell: Cell) -> CellResult:
     """Push the tests branch and open a draft PR without launching a subagent.
 
+    The tests repo is resolved from the orchestrator's CWD via
+    `git rev-parse --show-toplevel` — orchestrate is meant to run from a tests
+    worktree already on the feature branch, not from a hardcoded checkout.
+
     feature-design already wrote the tests-side artifacts; this step makes them
     visible to downstream CI by pushing the branch and opening a PR. Commits
     were made by the user (signed normally), so deferred signing doesn't apply.
     """
-    repo = TESTS_REPO
-    if not repo.is_dir():
-        return CellResult(cell, Path(), Path(), False, None, f"tests repo not found: {repo}")
+    try:
+        repo = Path(
+            subprocess.check_output(["git", "rev-parse", "--show-toplevel"], text=True).strip()
+        )
+    except subprocess.CalledProcessError as e:
+        return CellResult(
+            cell,
+            Path(),
+            Path(),
+            False,
+            None,
+            f"could not resolve current git repo (run from a tests worktree): {e}",
+        )
 
     try:
         current = subprocess.check_output(
@@ -420,9 +433,13 @@ def run_tests_cell(spec: FeatureSpec, cell: Cell) -> CellResult:
 
     if current != cell.branch:
         return CellResult(
-            cell, Path(), Path(), False, None,
-            f"tests repo is on branch '{current}', expected '{cell.branch}' — "
-            "did feature-design run on this branch?",
+            cell,
+            Path(),
+            Path(),
+            False,
+            None,
+            f"current repo {repo} is on branch '{current}', expected '{cell.branch}' — "
+            "run orchestrate from a tests worktree on the feature branch.",
         )
 
     try:
@@ -478,12 +495,8 @@ def run(
         list[str] | None,
         typer.Option("--only", help="Only run these cell keys (repeatable)."),
     ] = None,
-    timeout_s: Annotated[
-        int, typer.Option("--timeout", help="Per-cell timeout (seconds).")
-    ] = 1800,
-    model: Annotated[
-        str, typer.Option("--model", help="Sub-agent model alias.")
-    ] = "sonnet",
+    timeout_s: Annotated[int, typer.Option("--timeout", help="Per-cell timeout (seconds).")] = 1800,
+    model: Annotated[str, typer.Option("--model", help="Sub-agent model alias.")] = "sonnet",
     force: Annotated[
         bool,
         typer.Option("--force", help="Re-run cells even if they already have open PRs."),
@@ -523,11 +536,21 @@ def run(
 
     if dry_run:
         typer.echo(f"Feature: {spec.name} ({spec.jira or 'no Jira'}) — {spec.title}")
+        try:
+            tests_repo: Path | None = Path(
+                subprocess.check_output(["git", "rev-parse", "--show-toplevel"], text=True).strip()
+            )
+        except subprocess.CalledProcessError:
+            tests_repo = None
         for i, wave in enumerate(waves, 1):
             typer.echo(f"  Wave {i}:")
             for cell in wave:
                 if cell.key == "tests":
-                    existing = check_existing_pr(TESTS_REPO, cell.branch)
+                    existing = (
+                        check_existing_pr(tests_repo, cell.branch)
+                        if tests_repo is not None
+                        else None
+                    )
                     pr_note = f" [PR EXISTS: {existing}]" if existing else ""
                     typer.echo(
                         f"    - {cell.key}: path=(tests repo) branch={cell.branch}"
@@ -560,7 +583,8 @@ def _dispatch(c: Cell) -> CellResult:
             if c.key == "tests":
                 return run_tests_cell(spec, c)
             return run_cell(
-                spec, c,
+                spec,
+                c,
                 transcripts_dir=transcripts_dir,
                 timeout_s=timeout_s,
                 model=model,
diff --git a/otdf-sdk-mgr/tests/test_orchestrate.py b/otdf-sdk-mgr/tests/test_orchestrate.py
index 0507ccba0..d573bb8d4 100644
--- a/otdf-sdk-mgr/tests/test_orchestrate.py
+++ b/otdf-sdk-mgr/tests/test_orchestrate.py
@@ -7,12 +7,13 @@
 
 from __future__ import annotations
 
+import subprocess
 from pathlib import Path
 
 import pytest
+from otdf_sdk_mgr import cli_orchestrate
 from otdf_sdk_mgr.cli_orchestrate import (
     Cell,
-    FeatureSpec,
     load_spec,
     topological_waves,
     worktree_for,
@@ -184,3 +185,89 @@ def test_worktree_for_falls_back_to_name_when_no_jira(tmp_path: Path) -> None:
     spec = load_spec(_write_spec(tmp_path, body))
     wt = worktree_for(spec, spec.cells["platform-proto"])
     assert wt.name == "ad_hoc-platform-proto"
+
+
+# ------------------------------------------------------------ run_tests_cell
+#
+# These tests mock subprocess to verify that run_tests_cell resolves the tests
+# repo from the current working directory (via `git rev-parse --show-toplevel`)
+# rather than from a hardcoded path. The orchestrator is invoked from a tests
+# worktree on the feature branch, not from the canonical tests checkout.
+
+
+def test_run_tests_cell_resolves_repo_from_cwd(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fake_repo = tmp_path / "worktrees" / "TEST-1-tests" / "tests"
+    fake_repo.mkdir(parents=True)
+
+    check_output_calls: list[list[str]] = []
+    check_call_calls: list[list[str]] = []
+    run_calls: list[list[str]] = []
+
+    def fake_check_output(args: list[str], text: bool = False, **kwargs: object) -> str:
+        check_output_calls.append(list(args))
+        if list(args[:3]) == ["git", "rev-parse", "--show-toplevel"]:
+            return f"{fake_repo}\n"
+        if "branch" in args and "--show-current" in args:
+            return "TEST-1-tdd\n"
+        if args[0] == "gh" and "pr" in args and "create" in args:
+            return "Draft PR created: https://github.com/org/repo/pull/42\n"
+        raise AssertionError(f"unexpected check_output args: {args}")
+
+    def fake_check_call(args: list[str], **kwargs: object) -> int:
+        check_call_calls.append(list(args))
+        return 0
+
+    def fake_run(args: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        run_calls.append(list(args))
+        # gh pr list — return no existing PR.
+        return subprocess.CompletedProcess(args, 0, stdout="", stderr="")
+
+    monkeypatch.setattr(cli_orchestrate.subprocess, "check_output", fake_check_output)
+    monkeypatch.setattr(cli_orchestrate.subprocess, "check_call", fake_check_call)
+    monkeypatch.setattr(cli_orchestrate.subprocess, "run", fake_run)
+
+    spec = load_spec(_write_spec(tmp_path, _minimal_spec_yaml()))
+    result = cli_orchestrate.run_tests_cell(spec, spec.cells["tests"])
+
+    assert result.success is True, f"expected success, got error={result.error}"
+    assert result.pr_url == "https://github.com/org/repo/pull/42"
+
+    # All git/gh interactions must target the CWD-resolved repo, not TESTS_REPO.
+    fake_repo_str = str(fake_repo)
+    branch_check = ["git", "-C", fake_repo_str, "branch", "--show-current"]
+    push = ["git", "-C", fake_repo_str, "push", "-u", "origin", "TEST-1-tdd"]
+    assert branch_check in check_output_calls
+    assert push in check_call_calls
+    # gh subprocess.run / check_output calls run with cwd=fake_repo (not asserted
+    # explicitly — fake_run/fake_check_output don't capture cwd — but the
+    # branch check + push above prove the resolved path flows through).
+
+
+def test_run_tests_cell_errors_on_wrong_branch(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fake_repo = tmp_path / "opentdf" / "tests"
+    fake_repo.mkdir(parents=True)
+
+    def fake_check_output(args: list[str], text: bool = False, **kwargs: object) -> str:
+        if list(args[:3]) == ["git", "rev-parse", "--show-toplevel"]:
+            return f"{fake_repo}\n"
+        if "branch" in args and "--show-current" in args:
+            return "main\n"
+        raise AssertionError(f"unexpected check_output args: {args}")
+
+    def fail_call(args: list[str], **kwargs: object) -> int:
+        raise AssertionError(f"push must not happen on wrong branch: {args}")
+
+    monkeypatch.setattr(cli_orchestrate.subprocess, "check_output", fake_check_output)
+    monkeypatch.setattr(cli_orchestrate.subprocess, "check_call", fail_call)
+
+    spec = load_spec(_write_spec(tmp_path, _minimal_spec_yaml()))
+    result = cli_orchestrate.run_tests_cell(spec, spec.cells["tests"])
+
+    assert result.success is False
+    assert result.error is not None
+    assert "TEST-1-tdd" in result.error
+    assert "main" in result.error

From d11ea92e32fcf631c60a1eca68637b99232162ce Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 10:04:15 -0400
Subject: [PATCH 43/64] spec: scaffold for DSPX-3397

kc26 dpop
---
 spec/DSPX-3397.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 spec/DSPX-3397.md

diff --git a/spec/DSPX-3397.md b/spec/DSPX-3397.md
new file mode 100644
index 000000000..bb63245ab
--- /dev/null
+++ b/spec/DSPX-3397.md
@@ -0,0 +1,48 @@
+---
+ticket: DSPX-3397
+title: Add DPoP support to Java SDK (Keycloak v26 enforcement)
+status: draft
+authors:
+    - dmihalcik@virtru.com
+branches:
+    - opentdf/tests:DSPX-3397-kc26-dpop
+    - opentdf/java-sdk:DSPX-3397-kc26-dpop
+    - opentdf/platform:DSPX-3397-kc26-dpop
+    - opentdf/web-sdk:DSPX-3397-kc26-dpop
+prs: []
+created: 2026-06-08T00:00:00Z
+updated: 2026-06-08T00:00:00Z
+jira_priority: Medium
+---
+
+
+# Add DPoP support to Java SDK (Keycloak v26 enforcement)
+
+## Summary
+Keycloak v26 enforces DPoP (Demonstrating Proof of Possession) by default. This broke the Email Gateway because the Java SDK doesn't support DPoP yet. A workaround disabling DPoP on the Gateway client is in place (AB-2235), but that's a security trade-off — DPoP prevents token theft and replay attacks.
+ContextKC v26 enforces DPoP by default
+Gateway workaround: dpop_bound_access_tokens: "false" on the dsp-email-gateway client
+Java SDK issue: https://github.com/opentdf/java-sdk/issues/295
+Platform issue: https://github.com/opentdf/platform/issues/3216
+Ryan confirmed this should be prioritized; Dave M available to support
+ScopeAdd DPoP support to the Java SDK so consumers behind KC v26+ don't need to disable DPoP as a workaround.
+Raised by Ken He, JP Ayyappan. Ryan Schumacher confirmed prioritization.
+
+## Problem / Motivation
+_Why does this work need to happen? What is the user/business pain?_
+
+## Proposed Solution
+_What will you build, at a functional level? Sketch the approach._
+
+## Inputs / Outputs / Contracts
+_Function signatures, data shapes, API contracts, CLI flags._
+
+## Edge Cases & Constraints
+_Boundary conditions, error states, performance limits, security considerations._
+
+## Out of Scope
+_What this work item explicitly does not cover._
+
+## Acceptance Criteria
+- [ ] _Clear, testable condition_
+- [ ] _…_

From 4e306f1a5951af11bd9b377936abbb2c3ba64ca1 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 10:16:54 -0400
Subject: [PATCH 44/64] docs(spec): add Keycloak 26 and DPoP support
 specification

Upgrades the DSPX-3397 specification to detail a generic requirement
to update to Keycloak 26 and implement comprehensive DPoP support
across OpenTDF Java SDK, Web SDK, Platform services, and integration
tests.

Includes references summarizing:
- Keycloak 26 DPoP features and configuration settings
- RFC 9449 technical specifications (headers, claims, and flows)
---
 .../keycloak-v26-release-notes.md             |  62 +++++
 spec/DSPX-3397-refs/rfc9449-dpop-spec.md      | 156 +++++++++++++
 spec/DSPX-3397.md                             | 211 ++++++++++++++++--
 3 files changed, 410 insertions(+), 19 deletions(-)
 create mode 100644 spec/DSPX-3397-refs/keycloak-v26-release-notes.md
 create mode 100644 spec/DSPX-3397-refs/rfc9449-dpop-spec.md

diff --git a/spec/DSPX-3397-refs/keycloak-v26-release-notes.md b/spec/DSPX-3397-refs/keycloak-v26-release-notes.md
new file mode 100644
index 000000000..73f51d5a1
--- /dev/null
+++ b/spec/DSPX-3397-refs/keycloak-v26-release-notes.md
@@ -0,0 +1,62 @@
+# Keycloak 26 DPoP & Security Enforcement Reference Notes
+
+Keycloak v26 promotes **DPoP (OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer, RFC 9449)** from a preview feature to **fully supported (v26.4.0)** and encourages its enforcement across OAuth clients. This change is aimed at mitigating token replay attacks by ensuring that standard Bearer tokens can no longer be used if intercepted without the associated private cryptographic key.
+
+---
+
+## 1. Key DPoP Features & Enforcement in Keycloak v26
+
+### 1.1 Promotion to Full Support (v26.4.0)
+- **Production-Ready:** DPoP is no longer an experimental or "preview" feature. It is officially supported and integrated into the core security profiles.
+- **Ecosystem Adoption:** Because DPoP is fully supported, Keycloak-based enterprise setups (e.g., in OpenTDF deployment environments) can now globally mandate DPoP. Under high-security profiles, standard Bearer tokens are rejected outright, breaking clients that have not upgraded to support DPoP.
+
+### 1.2 Expanded Grant Type Support
+- DPoP support is now extended beyond the standard `authorization_code` flow to **all OAuth 2.0 grant types** supported by Keycloak, including:
+  - `client_credentials` (the primary flow used by machine-to-machine integrations like the OpenTDF Email Gateway)
+  - `refresh_token`
+  - `authorization_code`
+  - `urn:ietf:params:oauth:grant-type:token-exchange` (Token Exchange)
+
+### 1.3 UserInfo and Endpoints Support
+- The `/protocol/openid-connect/userinfo` endpoint has been upgraded to support DPoP-bound tokens.
+- All Keycloak-internal endpoints (such as token revocation, token introspection, and user info) accept DPoP-bound tokens and validate DPoP proofs.
+
+### 1.4 Pushed Authorization Requests (PAR) & Authorization Code Binding
+- Keycloak 26 supports binding the authorization code itself to a DPoP key during Pushed Authorization Requests (PAR), preventing code-injection/interception attacks.
+
+### 1.5 FAPI 2.0 Security Profiles
+- Keycloak v26 introduces formal client profiles:
+  - `fapi-2-dpop-security-profile`
+  - `fapi-2-dpop-message-signing`
+- These profiles make DPoP mandatory for client communication, aligning with the Financial-grade API (FAPI) 2.0 security specifications.
+
+---
+
+## 2. Admin Console & Client Configuration
+
+Administrators can enforce DPoP on a per-client or realm-wide basis.
+
+### 2.1 Enforcing DPoP on a Client
+1. Navigate to **Clients** in the Keycloak Admin Console.
+2. Select the target client (e.g., `dsp-email-gateway`).
+3. Scroll to **Advanced Settings**.
+4. Locate the configuration: **"Require DPoP bound tokens"** (key: `dpop.bound.access.tokens`).
+5. When turned **ON** (`true`):
+   - Keycloak will **reject** any token request from this client that lacks a valid `DPoP` header containing a DPoP proof.
+   - Any access tokens issued to this client will be bound to the public key supplied in the proof.
+   - Keycloak will only accept that access token at its own endpoints (like UserInfo) if accompanied by a corresponding DPoP proof.
+
+### 2.2 Workarounds & Deprecations
+- **The Workaround (AB-2235):** Disabling DPoP binding on the client via `dpop.bound.access.tokens = "false"` allows legacy clients to connect using standard Bearer tokens. This introduces a security gap, as it defeats sender-constraint protections.
+- **Goal:** Enable `dpop.bound.access.tokens = "true"` and have the SDK/client automatically generate DPoP proof JWTs to authenticate securely.
+
+---
+
+## 3. Impact on OpenTDF Components
+
+- **Java SDK:** The Java SDK must be enhanced to support generating DPoP proofs during token requests (`POST /token`) and subsequent API resource requests (e.g., interacting with KAS or Platform services).
+- **Platform (KAS & Services):** The OpenTDF Platform's internal services, specifically KAS, must be able to:
+  1. Detect when Keycloak returns a `DPoP` token type (indicated by `token_type: "DPoP"` in the token response).
+  2. Handle authentication headers prefixed with `DPoP ` instead of `Bearer `.
+  3. Validate the `DPoP` proof header sent alongside the token, verifying the `jkt` (JWK Thumbprint) contained in the access token's `cnf` claim matches the public key that signed the DPoP proof.
+- **Web SDK & Others:** Must maintain parity with DPoP requirements to support deployment under FAPI 2.0 / Keycloak 26 environments.
diff --git a/spec/DSPX-3397-refs/rfc9449-dpop-spec.md b/spec/DSPX-3397-refs/rfc9449-dpop-spec.md
new file mode 100644
index 000000000..2cedbdfce
--- /dev/null
+++ b/spec/DSPX-3397-refs/rfc9449-dpop-spec.md
@@ -0,0 +1,156 @@
+# RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession (DPoP) Technical Reference
+
+**OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)** is an IETF standard (RFC 9449) designed to prevent token reuse and replay attacks. DPoP ensures that access and refresh tokens are sender-constrained, meaning they can only be used by the client that holds the private cryptographic key associated with the token.
+
+---
+
+## 1. DPoP Proof JWT Structure
+
+A **DPoP Proof** is a short-lived JSON Web Token (JWT) sent by the client in the `DPoP` HTTP header. It is signed by an asymmetric private key belonging to the client. The public key is embedded directly in the JWT's header.
+
+### 1.1 JWT Header
+The header of a DPoP Proof JWT must contain:
+- `typ`: Must be exactly `"dpop+jwt"`.
+- `alg`: The digital signature algorithm (e.g., `ES256`, `RS256`, `PS256`, `EdDSA`).
+- `jwk`: The public key corresponding to the private key used to sign the JWT, formatted as a JSON Web Key (JWK). Must **not** contain any private key parameters.
+
+*Example Header:*
+```json
+{
+  "typ": "dpop+jwt",
+  "alg": "ES256",
+  "jwk": {
+    "kty": "EC",
+    "crv": "P-256",
+    "x": "f83OJ3D2xF1Bg8vub9t61_Vn_M8v6j8v6j8v6j8v6j8",
+    "y": "x_da4Nf_y_V6m289J1Q33835K0q_FAbD2W6fGv6b8sY"
+  }
+}
+```
+
+### 1.2 JWT Payload
+The payload contains claims that bind the proof to the specific HTTP request, preventing replay:
+- `jti`: A unique identifier for the JWT. Used to prevent replay attacks within a short time window.
+- `htm`: The HTTP method of the request (e.g., `"GET"`, `"POST"`, `"PUT"`), in uppercase.
+- `htu`: The HTTP target URI of the request, without query or fragment components (e.g., `"https://as.example.com/token"`).
+- `iat`: The time at which the JWT was issued (Unix epoch timestamp).
+- `ath`: **Required** when making resource requests. It is the Base64url-encoded SHA-256 hash of the ASCII representation of the access token. (Must **not** be included when requesting a new token, as no token exists yet).
+- `nonce`: **Required if provided by the server.** An opaque string supplied by the authorization server or resource server in a `DPoP-Nonce` HTTP response header.
+
+*Example Payload (Token Request - no access token yet):*
+```json
+{
+  "jti": "g3bZ9-8A1b2c",
+  "htm": "POST",
+  "htu": "https://as.example.com/protocol/openid-connect/token",
+  "iat": 1780000000
+}
+```
+
+*Example Payload (Resource Request - with access token):*
+```json
+{
+  "jti": "v9X8-1a2b3c4d",
+  "htm": "GET",
+  "htu": "https://api.example.com/kas/v2/keys",
+  "iat": 1780000100,
+  "ath": "fU_S9_8Z9_8Z9_8Z9_8Z9_8Z9_8Z9_8Z9_8Z9_8Z9_8"
+}
+```
+
+---
+
+## 2. Core Protocol Flows
+
+### 2.1 Flow A: Requesting an Access Token (e.g., Client Credentials)
+1. **Client Key Pair Generation:** The client generates or retrieves an asymmetric key pair (e.g., EC P-256 or RSA 2048).
+2. **Client DPoP Proof Generation:** The client creates a DPoP Proof JWT.
+   - Header: Contains `typ: "dpop+jwt"`, the signature algorithm, and the public key `jwk`.
+   - Payload: Contains `jti`, `htm: "POST"`, `htu: "https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token"`, and `iat`.
+   - Signature: Signed with the client's private key.
+3. **Client HTTP Request:**
+   - Header added: `DPoP: <DPoP-Proof-JWT>`
+   - Body: `grant_type=client_credentials&client_id=<id>&client_secret=<secret>`
+4. **Server Validation:**
+   - Keycloak validates the signature using the embedded `jwk`.
+   - Validates `htm` matches `"POST"` and `htu` matches the token endpoint URI.
+   - Validates `typ` is exactly `"dpop+jwt"`.
+   - Ensures `jti` is unique (uniqueness check/cache) and `iat` is within a narrow window.
+5. **Server Token Emission:**
+   - Keycloak generates the access token.
+   - Keycloak computes the JWK thumbprint (`jkt`) of the client's public key (per RFC 7638).
+   - Keycloak embeds the thumbprint into the access token payload as:
+     `"cnf": { "jkt": "<base64url-thumbprint>" }`
+   - Keycloak responds with a JSON body:
+     ```json
+     {
+       "access_token": "eyJhbGciOi...",
+       "token_type": "DPoP",
+       "expires_in": 300,
+       "refresh_token": "..."
+     }
+     ```
+     *Notice that `token_type` is `"DPoP"`, indicating that resource servers must require DPoP proofs for this token.*
+
+---
+
+### 2.2 Flow B: Requesting a Protected Resource (e.g., KAS Endpoint)
+1. **Compute Access Token Hash (`ath`):**
+   - The client takes the raw access token string (e.g., `"eyJhbGciOi..."`).
+   - Computes the SHA-256 hash of its ASCII bytes.
+   - Encodes the hash using Base64url (no padding). This string is the `ath` claim.
+2. **Client DPoP Proof Generation:**
+   - Header: Contains `typ: "dpop+jwt"`, signature `alg`, and public key `jwk`.
+   - Payload: Contains `jti`, `htm` (e.g., `"POST"`), `htu` (e.g., `"https://kas.example.com/api/kas/v2/rewrap"`), `iat`, and `ath` (computed in Step 1).
+   - Signature: Signed with the client's private key.
+3. **Client HTTP Request:**
+   - Header added: `Authorization: DPoP <access_token>`
+   - Header added: `DPoP: <DPoP-Proof-JWT>`
+4. **Resource Server (RS) Validation:**
+   - The RS extracts the Access Token from `Authorization` and the proof from `DPoP`.
+   - RS validates the DPoP proof JWT:
+     - Header `typ` is `"dpop+jwt"`.
+     - Signature is valid using the embedded `jwk` in the header.
+     - `htm` matches the incoming request method and `htu` matches the request URI (excluding query/fragment).
+     - `ath` claim in the payload matches the Base64url SHA-256 hash of the incoming access token.
+     - `iat` is within range; `jti` is unique/cached.
+   - RS validates the Access Token:
+     - Token signature, expiration, and active status.
+     - Extracts the public key thumbprint from `"cnf": { "jkt": "..." }`.
+     - Computes the thumbprint of the embedded `jwk` in the DPoP proof header.
+     - **Crucial Match Check:** Asserts that the computed thumbprint of the DPoP proof's public key matches the `jkt` claim inside the access token. If they do not match, the request is rejected with `401 Unauthorized` (sender constraint failed).
+
+---
+
+## 3. Server Nonce Support (DPoP-Nonce)
+
+To defend against clocks that are out-of-sync or replay attacks across long windows, servers can issue a custom "nonce" that the client must echo in its next DPoP proof.
+
+1. **Server Challenge:**
+   - If the client sends a DPoP proof without a `nonce` or with an expired `nonce`, the server responds with a `401 Unauthorized` or standard error response, and includes a `DPoP-Nonce` header:
+     `DPoP-Nonce: eyJhbGciOi... (opaque string)`
+2. **Client Retry:**
+   - The client extracts the value of the `DPoP-Nonce` header.
+   - It constructs a **new** DPoP proof JWT, adding the `nonce` claim set to that exact value.
+   - It signs and retries the HTTP request with the new proof.
+3. **Server Verification:**
+   - The server verifies that the `nonce` claim matches its current issued/expected nonce.
+
+---
+
+## 4. Client Implementation Requirements (Java & Web SDKs)
+
+### 4.1 Cryptographic Operations
+- **Key Pair Management:** SDKs must manage an asymmetric key pair. For maximum compatibility and performance, **EC P-256 (ES256)** is the recommended default. RSA is acceptable but produces larger signatures.
+- **JWK Serialisation:** The client must serialize the public key into standard JWK format to place in the `jwk` header parameter.
+- **JWK Thumbprint (RFC 7638):** To support caching or internal state matching, the client can compute the SHA-256 JWK thumbprint. Keycloak will also do this to populate the `cnf.jkt` claim.
+- **JWT Signing:** The client signs the DPoP proof JWT using the private key.
+
+### 4.2 HTTP Interceptors
+- SDKs typically use HTTP clients (e.g., `HttpClient` or `OkHttp` in Java; `fetch` or `axios` in Web SDKs).
+- Creating a generic **interceptor** is highly recommended. The interceptor should:
+  1. Dynamically read the request HTTP method and target URI.
+  2. Retrieve the access token and compute its SHA-256 hash (`ath`) if the token is present (for resource requests).
+  3. Create, sign, and inject the `DPoP` header.
+  4. Swap the `Authorization: Bearer <token>` header to `Authorization: DPoP <token>`.
+  5. Intercept `401` errors containing `DPoP-Nonce` headers, save the nonce, regenerate the proof, and retry the request automatically.
diff --git a/spec/DSPX-3397.md b/spec/DSPX-3397.md
index bb63245ab..be36d4e00 100644
--- a/spec/DSPX-3397.md
+++ b/spec/DSPX-3397.md
@@ -1,6 +1,6 @@
 ---
 ticket: DSPX-3397
-title: Add DPoP support to Java SDK (Keycloak v26 enforcement)
+title: Keycloak v26 Upgrade and Comprehensive DPoP Support
 status: draft
 authors:
     - dmihalcik@virtru.com
@@ -12,37 +12,210 @@ branches:
 prs: []
 created: 2026-06-08T00:00:00Z
 updated: 2026-06-08T00:00:00Z
-jira_priority: Medium
+jira_priority: High
 ---
 
-
-# Add DPoP support to Java SDK (Keycloak v26 enforcement)
+# Keycloak v26 Upgrade and Comprehensive DPoP Support
 
 ## Summary
-Keycloak v26 enforces DPoP (Demonstrating Proof of Possession) by default. This broke the Email Gateway because the Java SDK doesn't support DPoP yet. A workaround disabling DPoP on the Gateway client is in place (AB-2235), but that's a security trade-off — DPoP prevents token theft and replay attacks.
-ContextKC v26 enforces DPoP by default
-Gateway workaround: dpop_bound_access_tokens: "false" on the dsp-email-gateway client
-Java SDK issue: https://github.com/opentdf/java-sdk/issues/295
-Platform issue: https://github.com/opentdf/platform/issues/3216
-Ryan confirmed this should be prioritized; Dave M available to support
-ScopeAdd DPoP support to the Java SDK so consumers behind KC v26+ don't need to disable DPoP as a workaround.
-Raised by Ken He, JP Ayyappan. Ryan Schumacher confirmed prioritization.
+Keycloak v26 has promoted **DPoP (OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer, RFC 9449)** from a preview feature to **fully supported (v26.4.0)** and encourages its enforcement across OAuth clients. In high-security environments, or when utilizing modern security profiles like FAPI 2.0, Keycloak v26 enforces DPoP bound tokens by default. 
+
+Currently, our core clients and SDKs (specifically the **Java SDK**) do not natively support DPoP. This gap broke down-stream components—such as the **OpenTDF Email Gateway**—when deployed in Keycloak 26 environments. To restore connectivity, a temporary security trade-off workaround was implemented (AB-2235) to explicitly disable DPoP binding (`dpop_bound_access_tokens: "false"`) on the Keycloak client. 
+
+This specification defines a comprehensive, generic effort to:
+1. Upgrade the OpenTDF architecture to fully align with Keycloak 26.
+2. Implement first-class DPoP support in the **Java SDK** and verify/harden DPoP support in other SDKs (e.g., Web SDK).
+3. Update and verify the **OpenTDF Platform (KAS & Services)** to validate and process DPoP-bound tokens correctly.
+4. Integrate e2e verification in the **Integration Test Suite (`xtest`)** under a Keycloak 26 environment with DPoP enforced.
+
+By achieving these goals, OpenTDF deployments will benefit from sender-constrained access and refresh tokens, neutralizing token theft and replay attacks without requiring security-degrading client workarounds.
+
+---
 
 ## Problem / Motivation
-_Why does this work need to happen? What is the user/business pain?_
+In typical OAuth 2.0 deployments, access tokens are **Bearer tokens**. Anyone who possesses a bearer token can use it to access protected resources. If an access token is leaked (via application logs, browser storage, compromised servers, or man-in-the-middle attacks), an attacker can easily replay it against resource servers like KAS.
+
+**DPoP (RFC 9449)** mitigates this vulnerability by establishing **sender constraint**. The client generates an asymmetric key pair and cryptographically proves possession of the private key on every request:
+- During token acquisition, the client signs a short-lived proof (the DPoP Proof JWT) with its private key.
+- Keycloak issues an access token bound to the thumbprint (`jkt`) of the client's public key.
+- During resource requests, the client must present the access token along with a new DPoP proof.
+- The Resource Server (e.g., KAS) validates that the proof's signing key matches the public key thumbprint embedded in the access token.
+
+Keycloak 26 now natively and strictly supports this protocol across all endpoints and grant types (including machine-to-machine `client_credentials` flows). When clients are configured under high-security profiles (e.g., FAPI 2.0), DPoP is strictly required. Without DPoP support, OpenTDF clients and SDKs cannot operate in modern, highly secure enterprise environments.
+
+---
 
 ## Proposed Solution
-_What will you build, at a functional level? Sketch the approach._
+
+The transition to full Keycloak 26 and DPoP support will be executed across three main layers:
+
+```
+  +-----------------------+              +-----------------------+
+  |      Java SDK /       |   (1) Token  |      Keycloak 26      |
+  |     Email Gateway     | ------------>| (Enforces DPoP &      |
+  |  - Generates EC Key   | <------------|  binds cnf.jkt claim) |
+  |  - Signs DPoP Proof   |  (2) Token   +-----------------------+
+  +-----------------------+     (DPoP)
+              |
+              | (3) API Request (Authorization: DPoP <token>)
+              |     with DPoP Proof Header
+              v
+  +-----------------------+
+  |   OpenTDF Platform    |
+  |  (KAS / Go Services)  |
+  |  - Validates DPoP     |
+  |  - Asserts jkt match  |
+  +-----------------------+
+```
+
+### 1. Java SDK Implementation
+The Java SDK will be updated to automatically manage DPoP key pairs and sign DPoP proof JWTs during HTTP exchanges.
+
+- **Cryptographic Engine:** 
+  - Automatically generate an ephemeral **EC P-256 (ES256)** key pair on SDK client initialization, or accept an existing `java.security.PrivateKey` / `KeyPair` for persistence.
+  - Maintain the public key as a standard JWK to include in DPoP Proof headers.
+- **HTTP Interceptor Pattern:**
+  - Create an interceptor compatible with the SDK's internal HTTP clients (e.g., OkHttp or standard `java.net.http.HttpClient`).
+  - **For Token Requests (`POST /token`):**
+    - Generate a DPoP Proof JWT containing `jti`, `htm: "POST"`, `htu: <token-endpoint>`, and `iat`.
+    - Sign it with the private key.
+    - Set the `DPoP` HTTP header.
+  - **For API Resource Requests (KAS, Policy, etc.):**
+    - Retrieve the active access token and verify if its type is `DPoP`.
+    - If so, generate a DPoP Proof JWT containing `jti`, `htm`, `htu`, `iat`, and `ath` (the Base64url SHA-256 hash of the access token string).
+    - Set the `Authorization` header with the scheme `DPoP` (instead of `Bearer`), i.e., `Authorization: DPoP <access_token>`.
+    - Set the `DPoP` HTTP header containing the new proof.
+- **Server Nonce Handling (`DPoP-Nonce`):**
+  - Implement interceptor logic to catch `401 Unauthorized` responses containing a `DPoP-Nonce` header.
+  - Cache the received nonce.
+  - Re-generate the DPoP Proof JWT containing the `nonce` claim and automatically retry the request.
+
+### 2. Platform Services Implementation (Go / KAS)
+The OpenTDF platform services (implemented in Go) must be enhanced to accept and validate DPoP-bound tokens at all resource endpoints.
+
+- **Authentication Middleware Upgrade:**
+  - Update the token parsing and validation middleware to accept either `Bearer` or `DPoP` schemes in the `Authorization` header.
+  - If a `DPoP` token is supplied:
+    1. Require the presence of a valid `DPoP` HTTP header containing the DPoP Proof JWT.
+    2. Extract the public key (`jwk`) from the proof's JWT header.
+    3. Verify the proof signature using that public key.
+    4. Assert that `htm` and `htu` in the payload match the incoming request's HTTP method and normalized URI.
+    5. Assert that `ath` matches the Base64url-encoded SHA-256 hash of the presented access token.
+    6. Extract the access token and parse its `cnf.jkt` (confirmation thumbprint) claim.
+    7. Compute the SHA-256 thumbprint of the proof's public key (per RFC 7638) and verify it matches the `jkt` claim.
+- **Security Assertions:**
+  - Reject requests if there is a mismatch at any stage (e.g., token is DPoP-bound but request lacks `DPoP` header, or thumbprints do not align).
+
+### 3. Integration Testing & E2E Validation (`xtest`)
+To prevent regressions, the pytest-based integration suite must be expanded.
+
+- **Keycloak 26 Service Upgrade:**
+  - Verify that local dev environments and CI configurations run Keycloak 26.
+- **DPoP Scenario Verification:**
+  - Create integration tests that verify token exchange and resource access under clients that have DPoP strictly enabled.
+  - Assert that attempting to use a stolen DPoP access token without a proof, or with a modified proof (e.g., incorrect `htu` or `htm`), is rejected with `401 Unauthorized`.
+  - Validate that DPoP-Nonce challenges and retries function seamlessly.
+
+---
 
 ## Inputs / Outputs / Contracts
-_Function signatures, data shapes, API contracts, CLI flags._
+
+### DPoP Proof JWT Definition (RFC 9449)
+
+#### Header Contract
+```json
+{
+  "typ": "dpop+jwt",
+  "alg": "ES256",
+  "jwk": {
+    "kty": "EC",
+    "crv": "P-256",
+    "x": "...",
+    "y": "..."
+  }
+}
+```
+
+#### Payload Contract (Resource Request)
+```json
+{
+  "jti": "random-uuid-or-secure-string",
+  "htm": "POST",
+  "htu": "https://kas.example.com/api/kas/v2/rewrap",
+  "iat": 1780000000,
+  "ath": "base64url-encoded-sha256-hash-of-access-token",
+  "nonce": "optional-opaque-server-nonce"
+}
+```
+
+### SDK Configuration Interface
+
+The SDK configuration schemas should be updated to support the following parameters:
+
+```yaml
+# SDK Config Extension
+auth:
+  client_id: "dsp-email-gateway"
+  client_secret: "super-secret"
+  token_endpoint: "https://keycloak.example.com/realms/opentdf/protocol/openid-connect/token"
+  dpop:
+    enabled: true                 # Defaults to true or auto-detect
+    algorithm: "ES256"            # ES256 (default), RS256, PS256
+    private_key_path: "/path/key" # Optional; if omitted, an ephemeral key is generated
+```
+
+---
 
 ## Edge Cases & Constraints
-_Boundary conditions, error states, performance limits, security considerations._
+
+1. **Clock Skew:**
+   - Client and authorization server/resource server clocks may be out of sync. 
+   - *Mitigation:* Enforce `DPoP-Nonce` headers so the server can coordinate timelines, and implement a reasonable default grace period (e.g., ±60 seconds) for `iat` validation in the absence of a nonce.
+2. **Key Storage & Ephemeral Keys:**
+   - In containerized environments (like the Email Gateway), generating an ephemeral EC key pair on boot is simple and highly secure because keys are never persisted or exposed.
+   - For long-running interactive clients, persisting the key pair securely in a local keystore or keychain prevents excessive key generation and authorization overhead.
+3. **HTTP URI Normalization:**
+   - The `htu` claim must be normalized (lowercase scheme and host, default ports omitted, query parameters and fragments stripped). Discrepancies in trailing slashes or port declarations will cause validation failures.
+   - *Mitigation:* Use standard HTTP parsing libraries in the SDK and Platform to clean and normalize URIs before generating/verifying proofs.
+4. **gRPC Support:**
+   - OpenTDF services communicate via both REST and gRPC.
+   - For gRPC services, HTTP methods and URIs don't map cleanly to standard HTTP verbs.
+   - *Mitigation:* Per RFC 9449 guidelines for non-HTTP protocols, use `htm: "POST"` (as gRPC runs over HTTP/2 POST) and map `htu` to the full gRPC service path (e.g., `https://kas.example.com/opentdf.v2.kas.KeyAccessServerService/Rewrap`).
+
+---
 
 ## Out of Scope
-_What this work item explicitly does not cover._
+- Migrating external identity providers other than Keycloak to v26.
+- Supporting legacy symmetric-key or static-key proof configurations.
+- Custom hardware token / HSM integration for DPoP keys (only standard software-based asymmetric keys are in scope).
+
+---
+
+## References & Design Notes
+- Complete specifications and message exchange contracts are detailed in:
+  - [Keycloak v26 Release Notes](DSPX-3397-refs/keycloak-v26-release-notes.md)
+  - [RFC 9449 DPoP Spec Summary](DSPX-3397-refs/rfc9449-dpop-spec.md)
+
+---
 
 ## Acceptance Criteria
-- [ ] _Clear, testable condition_
-- [ ] _…_
+
+### SDK Implementation
+- [ ] **Asymmetric Key Support:** The SDK automatically generates a secure EC P-256 key pair upon startup when DPoP is enabled, with options to provide custom keys.
+- [ ] **Proof Generation on Token Request:** The SDK generates valid DPoP proof JWTs for `/protocol/openid-connect/token` requests containing `jti`, `htm: "POST"`, `htu`, and `iat` claims.
+- [ ] **Access Token Binding Recognition:** The SDK parses `token_type: "DPoP"` from the token endpoint response.
+- [ ] **Proof Generation on Resource Request:** For all subsequent KAS/Platform resource calls using a DPoP-bound token, the SDK generates a DPoP Proof containing the `ath` claim, and sends it via the `DPoP` header alongside the `Authorization: DPoP <token>` header.
+- [ ] **Nonce Auto-Retry:** The SDK interceptor catches `401` challenges with a `DPoP-Nonce` header, caches the nonce, and retries the request seamlessly.
+
+### Platform Support
+- [ ] **Dual Auth Middleware:** Platform/KAS services successfully accept and parse both standard `Bearer` and secure `DPoP` Authorization schemas.
+- [ ] **Proof Validation:** Platform services strictly validate incoming DPoP proofs (verifying signature, `htm`, `htu`, `ath`, and `jkt` match).
+- [ ] **Keycloak 26 Compatibility:** Platform can be run and tested successfully against a Keycloak 26 instance.
+
+### Integration & E2E Validation
+- [ ] **Upgraded Test Harness:** The local development/CI environment runs Keycloak 26.
+- [ ] **Happy Path Integration Test:** An integration test verifies that the Java SDK can successfully acquire tokens and wrap/unwrap/rewrap TDFs with DPoP strictly enabled.
+- [ ] **Negative Security Testing:** Integration tests verify that:
+  - Using a DPoP-bound token with a standard `Authorization: Bearer` header is rejected.
+  - Modifying the DPoP proof header (e.g., changing `htu` or tampering with the signature) results in an immediate authorization failure.
+  - Replaying a used DPoP proof `jti` is rejected.

From 5840180bc9ebab613c6ca1a824d838c35b1454d3 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 10:51:34 -0400
Subject: [PATCH 45/64] Clarify DPoP spec security requirements

Signed-off-by: Dave Mihalcik <dmihalcik@virtru.com>
---
 spec/DSPX-3397.md | 47 +++++++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 16 deletions(-)

diff --git a/spec/DSPX-3397.md b/spec/DSPX-3397.md
index be36d4e00..c57ec9f52 100644
--- a/spec/DSPX-3397.md
+++ b/spec/DSPX-3397.md
@@ -18,7 +18,7 @@ jira_priority: High
 # Keycloak v26 Upgrade and Comprehensive DPoP Support
 
 ## Summary
-Keycloak v26 has promoted **DPoP (OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer, RFC 9449)** from a preview feature to **fully supported (v26.4.0)** and encourages its enforcement across OAuth clients. In high-security environments, or when utilizing modern security profiles like FAPI 2.0, Keycloak v26 enforces DPoP bound tokens by default. 
+Keycloak v26 has promoted **DPoP (OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer, RFC 9449)** from a preview feature to **fully supported (v26.4.0)** and encourages its enforcement across OAuth clients. DPoP is not automatically enforced for every Keycloak client; it must be enabled through client configuration or client policies/profiles such as FAPI 2.0 DPoP profiles. In high-security environments where those policies are enabled, clients that cannot produce valid DPoP proofs cannot acquire or use DPoP-bound tokens.
 
 Currently, our core clients and SDKs (specifically the **Java SDK**) do not natively support DPoP. This gap broke down-stream components—such as the **OpenTDF Email Gateway**—when deployed in Keycloak 26 environments. To restore connectivity, a temporary security trade-off workaround was implemented (AB-2235) to explicitly disable DPoP binding (`dpop_bound_access_tokens: "false"`) on the Keycloak client. 
 
@@ -41,7 +41,7 @@ In typical OAuth 2.0 deployments, access tokens are **Bearer tokens**. Anyone wh
 - During resource requests, the client must present the access token along with a new DPoP proof.
 - The Resource Server (e.g., KAS) validates that the proof's signing key matches the public key thumbprint embedded in the access token.
 
-Keycloak 26 now natively and strictly supports this protocol across all endpoints and grant types (including machine-to-machine `client_credentials` flows). When clients are configured under high-security profiles (e.g., FAPI 2.0), DPoP is strictly required. Without DPoP support, OpenTDF clients and SDKs cannot operate in modern, highly secure enterprise environments.
+Keycloak 26 now natively supports this protocol for OAuth clients, including machine-to-machine `client_credentials` flows when the client is configured to require DPoP-bound access tokens. When clients are configured under high-security profiles (e.g., FAPI 2.0 DPoP profiles), DPoP is strictly required. Without DPoP support, OpenTDF clients and SDKs cannot operate in those Keycloak 26 deployments unless administrators disable sender-constrained tokens as a compatibility workaround.
 
 ---
 
@@ -86,25 +86,32 @@ The Java SDK will be updated to automatically manage DPoP key pairs and sign DPo
     - Set the `Authorization` header with the scheme `DPoP` (instead of `Bearer`), i.e., `Authorization: DPoP <access_token>`.
     - Set the `DPoP` HTTP header containing the new proof.
 - **Server Nonce Handling (`DPoP-Nonce`):**
-  - Implement interceptor logic to catch `401 Unauthorized` responses containing a `DPoP-Nonce` header.
-  - Cache the received nonce.
-  - Re-generate the DPoP Proof JWT containing the `nonce` claim and automatically retry the request.
+  - Implement token-endpoint retry logic for authorization-server nonce challenges. Keycloak can reject a token request with an OAuth error response such as `use_dpop_nonce` and a `DPoP-Nonce` header; the SDK must cache that nonce for the token issuer, regenerate the token-request proof with a fresh `jti` and the `nonce` claim, and retry once.
+  - Implement resource-request retry logic for resource-server nonce challenges. Resource servers can reject an API request with `401 Unauthorized`, `WWW-Authenticate: DPoP`, and a `DPoP-Nonce` header; the SDK must cache that nonce for the resource origin or endpoint, regenerate the proof with a fresh `jti`, include the `nonce` claim, and retry only when retrying the request is safe.
+  - Nonce caches must be scoped by issuer/resource origin, not global. A nonce received from Keycloak's token endpoint must not be reused for KAS or another resource server unless the issuer explicitly defines that scope.
+  - Automatic retries must be capped (default: one retry per challenge) to prevent retry loops. Non-idempotent operations require care: the SDK must only retry after a nonce challenge when the original request was rejected before application-level processing, or when the caller has explicitly opted into retry behavior.
 
 ### 2. Platform Services Implementation (Go / KAS)
 The OpenTDF platform services (implemented in Go) must be enhanced to accept and validate DPoP-bound tokens at all resource endpoints.
 
 - **Authentication Middleware Upgrade:**
   - Update the token parsing and validation middleware to accept either `Bearer` or `DPoP` schemes in the `Authorization` header.
+  - If the access token contains a `cnf.jkt` confirmation claim or token introspection identifies the token as DPoP-bound, the request must be treated as DPoP-bound even if the caller used the `Bearer` scheme. DPoP-bound tokens must never fall back to bearer-token validation.
   - If a `DPoP` token is supplied:
-    1. Require the presence of a valid `DPoP` HTTP header containing the DPoP Proof JWT.
-    2. Extract the public key (`jwk`) from the proof's JWT header.
-    3. Verify the proof signature using that public key.
-    4. Assert that `htm` and `htu` in the payload match the incoming request's HTTP method and normalized URI.
-    5. Assert that `ath` matches the Base64url-encoded SHA-256 hash of the presented access token.
-    6. Extract the access token and parse its `cnf.jkt` (confirmation thumbprint) claim.
-    7. Compute the SHA-256 thumbprint of the proof's public key (per RFC 7638) and verify it matches the `jkt` claim.
+    1. Require exactly one `DPoP` HTTP header containing the DPoP Proof JWT.
+    2. Validate the proof header: `typ` must be `dpop+jwt`; `alg` must be allowlisted for this release (`ES256` initially); `alg: none` and symmetric algorithms must be rejected; `jwk` must be an asymmetric public key and must not contain private key parameters.
+    3. Extract the public key (`jwk`) from the proof's JWT header and verify that the proof signature matches the declared algorithm and key.
+    4. Validate required claims: `jti`, `htm`, `htu`, and `iat` must be present; resource requests must also include `ath`; nonce must be present when the server has challenged for one.
+    5. Assert that `htm` and `htu` in the payload match the incoming request's HTTP method and normalized URI.
+    6. Assert that `ath` matches the Base64url-encoded SHA-256 hash of the presented access token.
+    7. Validate `iat` against a narrow acceptance window (default: ±60 seconds unless nonce policy is stricter).
+    8. Enforce replay protection by rejecting reused proof identifiers. The replay cache key should include the proof public-key thumbprint plus `jti`; entries should expire no later than the accepted proof lifetime plus clock-skew allowance. In multi-instance deployments, the cache must be shared or otherwise consistent enough that replaying a proof against another platform instance is rejected.
+    9. Limit replay-cache resource usage: enforce a maximum `jti` length, store a hash of cache keys rather than raw attacker-controlled values, and evict entries by TTL to avoid memory exhaustion.
+    10. Extract the access token and parse its `cnf.jkt` (confirmation thumbprint) claim.
+    11. Compute the SHA-256 thumbprint of the proof's public key (per RFC 7638) and verify it matches the `jkt` claim.
 - **Security Assertions:**
   - Reject requests if there is a mismatch at any stage (e.g., token is DPoP-bound but request lacks `DPoP` header, or thumbprints do not align).
+  - Return a DPoP challenge with `WWW-Authenticate: DPoP` and a `DPoP-Nonce` header when the resource server requires a nonce. Do not disclose which specific validation check failed beyond the standard authentication error detail.
 
 ### 3. Integration Testing & E2E Validation (`xtest`)
 To prevent regressions, the pytest-based integration suite must be expanded.
@@ -114,7 +121,7 @@ To prevent regressions, the pytest-based integration suite must be expanded.
 - **DPoP Scenario Verification:**
   - Create integration tests that verify token exchange and resource access under clients that have DPoP strictly enabled.
   - Assert that attempting to use a stolen DPoP access token without a proof, or with a modified proof (e.g., incorrect `htu` or `htm`), is rejected with `401 Unauthorized`.
-  - Validate that DPoP-Nonce challenges and retries function seamlessly.
+  - Validate that token-endpoint and resource-server DPoP nonce challenges are handled with scoped nonce caches, fresh proofs, and capped retries.
 
 ---
 
@@ -170,7 +177,7 @@ auth:
 
 1. **Clock Skew:**
    - Client and authorization server/resource server clocks may be out of sync. 
-   - *Mitigation:* Enforce `DPoP-Nonce` headers so the server can coordinate timelines, and implement a reasonable default grace period (e.g., ±60 seconds) for `iat` validation in the absence of a nonce.
+   - *Mitigation:* Implement a reasonable default grace period (e.g., ±60 seconds) for `iat` validation and use `DPoP-Nonce` challenges when a server needs stricter proof freshness or cannot rely on client clock accuracy. Nonce validation does not replace `jti` replay protection.
 2. **Key Storage & Ephemeral Keys:**
    - In containerized environments (like the Email Gateway), generating an ephemeral EC key pair on boot is simple and highly secure because keys are never persisted or exposed.
    - For long-running interactive clients, persisting the key pair securely in a local keystore or keychain prevents excessive key generation and authorization overhead.
@@ -181,6 +188,12 @@ auth:
    - OpenTDF services communicate via both REST and gRPC.
    - For gRPC services, HTTP methods and URIs don't map cleanly to standard HTTP verbs.
    - *Mitigation:* Per RFC 9449 guidelines for non-HTTP protocols, use `htm: "POST"` (as gRPC runs over HTTP/2 POST) and map `htu` to the full gRPC service path (e.g., `https://kas.example.com/opentdf.v2.kas.KeyAccessServerService/Rewrap`).
+5. **DPoP Nonce Scoping:**
+   - Authorization servers and resource servers can issue independent nonces. A nonce from Keycloak's token endpoint is not automatically valid for KAS, and a KAS nonce should not be reused for another resource origin.
+   - *Mitigation:* Cache nonce values by issuer or resource origin/path scope, generate a new proof with a new `jti` for each retry, and cap automatic retries to one challenge cycle unless the caller explicitly opts into additional retry behavior.
+6. **Clustered Replay Protection:**
+   - `jti` replay protection is only effective if the same proof cannot be replayed to a different platform instance before the proof expires.
+   - *Mitigation:* Use a shared replay cache for horizontally scaled KAS/platform deployments, or document that DPoP replay protection is only instance-local until a shared cache is configured.
 
 ---
 
@@ -205,17 +218,19 @@ auth:
 - [ ] **Proof Generation on Token Request:** The SDK generates valid DPoP proof JWTs for `/protocol/openid-connect/token` requests containing `jti`, `htm: "POST"`, `htu`, and `iat` claims.
 - [ ] **Access Token Binding Recognition:** The SDK parses `token_type: "DPoP"` from the token endpoint response.
 - [ ] **Proof Generation on Resource Request:** For all subsequent KAS/Platform resource calls using a DPoP-bound token, the SDK generates a DPoP Proof containing the `ath` claim, and sends it via the `DPoP` header alongside the `Authorization: DPoP <token>` header.
-- [ ] **Nonce Auto-Retry:** The SDK interceptor catches `401` challenges with a `DPoP-Nonce` header, caches the nonce, and retries the request seamlessly.
+- [ ] **Nonce Auto-Retry:** The SDK handles authorization-server nonce challenges (e.g., token-endpoint `use_dpop_nonce` responses) and resource-server `401` nonce challenges separately, scopes nonce caches by issuer/resource origin, regenerates proofs with fresh `jti` values, and caps automatic retries.
 
 ### Platform Support
 - [ ] **Dual Auth Middleware:** Platform/KAS services successfully accept and parse both standard `Bearer` and secure `DPoP` Authorization schemas.
-- [ ] **Proof Validation:** Platform services strictly validate incoming DPoP proofs (verifying signature, `htm`, `htu`, `ath`, and `jkt` match).
+- [ ] **Proof Validation:** Platform services strictly validate incoming DPoP proofs (verifying header constraints, signature, `htm`, `htu`, `ath`, `iat`, replay-safe `jti`, and `jkt` match).
 - [ ] **Keycloak 26 Compatibility:** Platform can be run and tested successfully against a Keycloak 26 instance.
 
 ### Integration & E2E Validation
 - [ ] **Upgraded Test Harness:** The local development/CI environment runs Keycloak 26.
+- [ ] **DPoP Enforcement Configuration:** The Keycloak test client has DPoP-bound access tokens explicitly required (e.g., `dpop.bound.access.tokens=true` / `dpop_bound_access_tokens: "true"`), rather than relying on realm defaults.
 - [ ] **Happy Path Integration Test:** An integration test verifies that the Java SDK can successfully acquire tokens and wrap/unwrap/rewrap TDFs with DPoP strictly enabled.
 - [ ] **Negative Security Testing:** Integration tests verify that:
   - Using a DPoP-bound token with a standard `Authorization: Bearer` header is rejected.
   - Modifying the DPoP proof header (e.g., changing `htu` or tampering with the signature) results in an immediate authorization failure.
   - Replaying a used DPoP proof `jti` is rejected.
+  - Token-endpoint nonce challenges and resource-server nonce challenges are handled separately, each with a fresh proof and capped retry behavior.

From 9802000386296a6678d83a608f6a8eacd50a2a12 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 11:01:02 -0400
Subject: [PATCH 46/64] test(DSPX-3397): scaffold dpop feature spec, scenario,
 and dormant tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the tests-side artifacts for the Keycloak 26 + DPoP rollout:

- xtest/features/DSPX-3397.yaml: feature spec with five cells (tests,
  platform-service, platform-go-sdk, java-sdk, web-sdk). No platform-proto
  (DPoP is HTTP-header only) and no depends_on edges; each cell can land
  its draft PR independently and activate the dormant tests by adding a
  `supports dpop` case to its cli.sh.
- xtest/scenarios/DSPX-3397.yaml: standalone-KAS scenario selecting
  test_dpop.py against a KC26-enforced realm.
- xtest/tdfs.py: register "dpop" in feature_type (alphabetical, between
  connectrpc and ecwrap).
- xtest/test_dpop.py: draft tests gated on pfs/sdk supports("dpop"):
  happy-path roundtrip, server-issued DPoP-Nonce retry (RFC 9449 §8), and
  four direct-HTTP negative skeletons (Bearer-on-DPoP, tampered htu,
  replayed jti, tampered/expired nonce) to flesh out alongside the
  platform-service PR.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 xtest/features/DSPX-3397.yaml  |  53 +++++++++++
 xtest/scenarios/DSPX-3397.yaml |  60 ++++++++++++
 xtest/tdfs.py                  |   5 +
 xtest/test_dpop.py             | 167 +++++++++++++++++++++++++++++++++
 4 files changed, 285 insertions(+)
 create mode 100644 xtest/features/DSPX-3397.yaml
 create mode 100644 xtest/scenarios/DSPX-3397.yaml
 create mode 100644 xtest/test_dpop.py

diff --git a/xtest/features/DSPX-3397.yaml b/xtest/features/DSPX-3397.yaml
new file mode 100644
index 000000000..e54b649cd
--- /dev/null
+++ b/xtest/features/DSPX-3397.yaml
@@ -0,0 +1,53 @@
+apiVersion: opentdf.io/v1alpha1
+kind: Feature
+metadata:
+  name: dpop
+  jira: DSPX-3397
+  title: "Keycloak v26 upgrade and comprehensive DPoP (RFC 9449) support"
+  created: 2026-06-08
+repos:
+  tests:
+    branch: DSPX-3397-kc26-dpop
+    todo:
+      - "\"dpop\" is already registered in xtest/tdfs.py feature_type (alphabetical, between connectrpc and ecwrap) — verify."
+      - Update otdf-local to default to Keycloak 26 unconditionally (bump container/version pin, refresh realm import). Validate `uv run otdf-local up` boots KC26 and the platform authenticates. Document the bump in otdf-local/README.md.
+      - Bump any docker-compose / helm / CI workflow files in xtest/ that reference an older Keycloak version so the entire test harness defaults to KC26.
+      - Flesh out xtest/test_dpop.py negatives (Bearer-on-DPoP, tampered htu, replayed jti, tampered/expired nonce) — direct-HTTP cases against the platform's KAS endpoint with hand-minted proofs (see python `cryptography` and `jwcrypto` already in the dev deps).
+      - PR description should link to the four implementation PRs once they exist (`gh pr list --search "head:DSPX-3397"`).
+  platform-service:
+    path: platform
+    branch: DSPX-3397-platform-service
+    todo:
+      - Audit `service/pkg/auth/` (or wherever the access-token middleware lives). `enforceDPoP: false` already exists in opentdf-*.yaml plus `Dpop` listed in auth mechanisms — extend rather than rewrite. Reuse the DPoP key+proof helpers in `test/integration/oauth/oauth_test.go`.
+      - Update the middleware to accept both `Authorization: Bearer <token>` and `Authorization: DPoP <token>` schemes.
+      - For `DPoP` scheme, validate the proof end-to-end per RFC 9449 §4.3 + §7.1 — header `typ=dpop+jwt` + `alg=ES256/RS256/PS256`; jwk extraction; verify signature; `htm` matches the request method; `htu` matches the normalized URI (lowercase scheme/host, default ports stripped, query+fragment stripped per spec §HTTP URI Normalization); `ath = base64url(SHA-256(access_token))`; RFC 7638 JWK thumbprint matches `cnf.jkt` in the access token.
+      - "Server-issued DPoP-Nonce challenges (RFC 9449 §8) — gated by a new config key `services.kas.dpop.require_nonce` (default false). When enabled, the middleware mints a short-lived opaque nonce, returns it via the `DPoP-Nonce` response header on every successful response *and* in 401 challenges (`use_dpop_nonce` error) when a proof arrives without the expected `nonce` claim. Validate the proof's `nonce` claim against the active nonce window (current + previous), rotate on a configurable interval, and reject tampered/expired nonces with 401 + fresh `DPoP-Nonce`."
+      - For gRPC paths, map `htm: \"POST\"` and `htu` to the full gRPC service path (spec §Edge Cases). Propagate `DPoP-Nonce` via response headers/trailers.
+      - Verify the platform boots and authenticates against a local KC26 once the tests-cell otdf-local bump lands. Add at least one Go unit test per validation rule (signature, htm, htu, ath, jkt, nonce-current, nonce-rotated, nonce-tampered).
+      - Add `supports dpop` case to the platform's policy/KAS-side feature gate so `pfs.skip_if_unsupported(\"dpop\")` in tests sees it.
+  platform-go-sdk:
+    path: platform
+    branch: DSPX-3397-platform-go-sdk
+    todo:
+      - Add DPoP client support to the Go SDK auth layer (likely `sdk/auth/` or `sdk/oauth/`). Generate an ephemeral EC P-256 (ES256) key per SDK instance by default; accept a caller-supplied `crypto.Signer` for persistence (HSM is out of scope).
+      - "HTTP interceptor compatible with the SDK's HTTP client. Token endpoint: emit proof with claims `jti, htm=\"POST\", htu=<token-endpoint>, iat`. Resource endpoints (KAS / policy / kasregistry): when the access token is DPoP-bound (`token_type=DPoP`), emit proof with added `ath = base64url(SHA-256(token))`, set `Authorization: DPoP <token>` instead of `Bearer`."
+      - "Handle server-issued nonce: on 401 with a `DPoP-Nonce` response header, cache the nonce (per-origin), regenerate the proof with the `nonce` claim, retry once. Refresh cached nonces from successful responses too."
+      - Add `supports dpop` case to xtest/sdk/go/cli.sh source — the awk predicate should match a stable DPoP-related flag or feature string introduced by this PR.
+  java-sdk:
+    path: java-sdk
+    branch: DSPX-3397-java-sdk
+    todo:
+      - Same shape as the Go SDK but for Java. Use Nimbus JOSE+JWT (already a likely dep) or BouncyCastle for EC P-256 + ES256 signing. Audit existing `DefaultSrtSigner` scaffolding in `sdk/src/test/java/io/opentdf/platform/sdk/{KASClientTest,SDKBuilderTest}.java` — extend or align with the production flow rather than introducing a parallel signer abstraction.
+      - HTTP interceptor for the SDK's OkHttp client (or `java.net.http.HttpClient`) with the same proof-generation rules (`htm/htu/iat/jti` always; `ath` on resource calls; `nonce` retry on 401+DPoP-Nonce).
+      - Surface a `DpopConfig` (or similar) in `SDKBuilder` so callers can pass a `KeyPair` or `PrivateKey`, or rely on the SDK's auto-generated ephemeral key.
+      - Add `supports dpop` case to xtest/sdk/java/cli.sh source.
+  web-sdk:
+    path: web-sdk
+    branch: DSPX-3397-web-sdk
+    todo:
+      - Audit existing DPoP integration in `lib/src/session.ts` (uses the `dpop` npm package). Confirm proofs for both the token endpoint and KAS exchanges include `ath` on resource calls and that the JWK thumbprint flows through to `cnf.jkt`.
+      - Implement / verify the `DPoP-Nonce` 401 retry loop in the SDK's HTTP layer (not just the OIDC client). Refresh the cached nonce from successful responses' `DPoP-Nonce` header.
+      - Ensure every KAS-facing client (rewrap, policy, kasregistry — `lib/src/access.ts` and related) propagates DPoP headers, not only the OIDC token-exchange path.
+      - Add `supports dpop` case to xtest/sdk/js/cli.sh source. Coordinate the CLI flag exposure in `cli/src/cli.ts` (currently `--dpop` is wired up — verify and document).
+scenarios:
+  - xtest/scenarios/DSPX-3397.yaml
diff --git a/xtest/scenarios/DSPX-3397.yaml b/xtest/scenarios/DSPX-3397.yaml
new file mode 100644
index 000000000..645e1f2b1
--- /dev/null
+++ b/xtest/scenarios/DSPX-3397.yaml
@@ -0,0 +1,60 @@
+apiVersion: opentdf.io/v1alpha1
+kind: Scenario
+metadata:
+  id: DSPX-3397
+  title: "Keycloak v26 + DPoP-enforced clients (DSPX-3397)"
+  created: 2026-06-08
+instance:
+  metadata:
+    name: DSPX-3397
+  platform:
+    source:
+      ref: main
+  ports:
+    base: 8080
+  kas:
+    alpha:
+      source:
+        ref: main
+      mode: standard
+sdks:
+  encrypt:
+    - sdk: go
+      version: main
+    - sdk: java
+      version: main
+    - sdk: js
+      version: main
+  decrypt:
+    - sdk: go
+      version: main
+    - sdk: java
+      version: main
+    - sdk: js
+      version: main
+suite:
+  targets:
+    - xtest/test_dpop.py
+  containers:
+    - ztdf
+expected: >-
+  Against a Keycloak 26 realm whose OAuth client requires DPoP-bound access
+  tokens (and with `services.kas.dpop.require_nonce: true` on the platform),
+  every SDK pair passes test_dpop.py — the encrypt SDK acquires a DPoP-bound
+  token, signs a fresh DPoP proof for every KAS rewrap call (with the `ath`
+  claim binding the proof to the access token), and the decrypt SDK rewraps
+  successfully. The server-issued nonce flow works end-to-end (first request
+  returns 401 + DPoP-Nonce; SDK retries with the nonce claim; second request
+  succeeds). Negative cases (Authorization: Bearer on a DPoP-bound token,
+  tampered htu, replayed jti, tampered/expired nonce) all return 401 with a
+  fresh DPoP-Nonce challenge.
+actual: >-
+  Feature not yet implemented end-to-end. The platform-service PR
+  (DSPX-3397-platform-service) is needed to wire DPoP validation + nonce
+  issuance into the KAS auth middleware. Each SDK cell PR
+  (DSPX-3397-{platform-go-sdk,java-sdk,web-sdk}) is needed to mint DPoP
+  proofs, set `Authorization: DPoP <token>`, and handle 401+DPoP-Nonce
+  retries. The tests-cell PR (DSPX-3397-kc26-dpop) is needed to bump
+  otdf-local to Keycloak 26 and to flesh out the direct-HTTP negative
+  cases. Until each SDK PR adds its `supports dpop` case to its cli.sh and
+  the platform PR exposes `pfs.supports("dpop")`, the suite skips uniformly.
diff --git a/xtest/tdfs.py b/xtest/tdfs.py
index 9ab9b9bce..72177dd58 100644
--- a/xtest/tdfs.py
+++ b/xtest/tdfs.py
@@ -107,6 +107,11 @@ def is_sdk_type(val: str) -> TypeIs[sdk_type]:
     "better-messages-2024",
     "bulk_rewrap",
     "connectrpc",
+    # DPoP (RFC 9449): sender-constrained access tokens. SDK signs a DPoP proof
+    # JWT per request; KAS validates the proof and binds the access token to
+    # the proof's JWK thumbprint (cnf.jkt). Includes server-issued DPoP-Nonce
+    # challenge flow (RFC 9449 §8) when the KAS is configured to require nonces.
+    "dpop",
     "ecwrap",
     "hexless",
     "hexaflexible",
diff --git a/xtest/test_dpop.py b/xtest/test_dpop.py
new file mode 100644
index 000000000..996a372ef
--- /dev/null
+++ b/xtest/test_dpop.py
@@ -0,0 +1,167 @@
+"""DPoP (RFC 9449) integration tests against a Keycloak 26 + DPoP-enforced realm.
+
+Draft tests for DSPX-3397. They land dormant — each test skips unless both the
+platform exposes `pfs.supports("dpop")` AND the participating SDK exposes
+`sdk.supports("dpop")` via its cli.sh shim. As each per-repo PR lands the
+required `supports dpop` case, the corresponding lane activates.
+
+The happy-path roundtrip exercises the SDK end-to-end. The negative cases use
+direct HTTP against the KAS endpoint with hand-minted proofs because the SDKs
+intentionally do not expose hooks to mis-sign or tamper with their own proofs
+— that's the right shape for a security test.
+"""
+
+import base64
+import filecmp
+import os
+import time
+import urllib.request
+from pathlib import Path
+
+import pytest
+
+import tdfs
+from abac import Attribute
+from fixtures.encryption import EncryptFactory
+
+
+def _kas_url() -> str:
+    """KAS endpoint for direct-HTTP negative tests. Mirrors test.env."""
+    return os.getenv(
+        "KASURL", os.getenv("PLATFORMURL", "http://localhost:8080") + "/kas"
+    )
+
+
+def test_dpop_happy_path_roundtrip(
+    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    encrypt_sdk: tdfs.SDK,
+    decrypt_sdk: tdfs.SDK,
+    pt_file: Path,
+    in_focus: set[tdfs.SDK],
+    encrypted_tdf: EncryptFactory,
+):
+    """Encrypt + decrypt via a KAS that requires DPoP-bound access tokens.
+
+    Verifies the SDK transparently:
+      1. mints a DPoP proof for the token request,
+      2. recognizes the resulting `token_type: DPoP`,
+      3. mints a fresh DPoP proof (with `ath` claim) for the KAS rewrap,
+      4. sends `Authorization: DPoP <token>` instead of `Bearer`.
+    """
+    if not in_focus & {encrypt_sdk, decrypt_sdk}:
+        pytest.skip("Not in focus")
+    pfs = tdfs.get_platform_features()
+    pfs.skip_if_unsupported("dpop")
+    encrypt_sdk.skip_if_unsupported("dpop")
+    decrypt_sdk.skip_if_unsupported("dpop")
+
+    attr, _ = attribute_single_kas_grant
+    ct_file = encrypted_tdf(
+        encrypt_sdk,
+        attr_values=attr.value_fqns,
+        target_mode=tdfs.select_target_version(encrypt_sdk, decrypt_sdk),
+    )
+    rt_file = encrypted_tdf.rt_file(ct_file, decrypt_sdk)
+    decrypt_sdk.decrypt(ct_file, rt_file, "ztdf")
+    assert filecmp.cmp(pt_file, rt_file)
+
+
+def test_dpop_server_issued_nonce_retry(
+    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    encrypt_sdk: tdfs.SDK,
+    decrypt_sdk: tdfs.SDK,
+    pt_file: Path,
+    in_focus: set[tdfs.SDK],
+    encrypted_tdf: EncryptFactory,
+):
+    """Roundtrip when KAS has `services.kas.dpop.require_nonce: true`.
+
+    The first KAS call from the SDK arrives without a `nonce` claim, so KAS
+    responds 401 + `DPoP-Nonce: <opaque>`. The SDK is expected to cache the
+    nonce, re-sign the proof with the nonce claim, and retry once — without
+    surfacing the 401 to the caller. End result: a successful roundtrip.
+
+    TODO(tests-cell): once a nonce-observability hook exists (KAS log line or
+    response header counter), assert that exactly one 401+DPoP-Nonce challenge
+    was issued and successfully retried.
+    """
+    if not in_focus & {encrypt_sdk, decrypt_sdk}:
+        pytest.skip("Not in focus")
+    pfs = tdfs.get_platform_features()
+    pfs.skip_if_unsupported("dpop")
+    encrypt_sdk.skip_if_unsupported("dpop")
+    decrypt_sdk.skip_if_unsupported("dpop")
+
+    attr, _ = attribute_single_kas_grant
+    ct_file = encrypted_tdf(
+        encrypt_sdk,
+        attr_values=attr.value_fqns,
+        target_mode=tdfs.select_target_version(encrypt_sdk, decrypt_sdk),
+    )
+    rt_file = encrypted_tdf.rt_file(ct_file, decrypt_sdk)
+    decrypt_sdk.decrypt(ct_file, rt_file, "ztdf")
+    assert filecmp.cmp(pt_file, rt_file)
+
+
+def _b64u(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+@pytest.mark.skip(
+    reason="TODO(tests-cell, DSPX-3397): wire up direct-HTTP DPoP negative tests once the platform-service PR lands."
+)
+def test_dpop_rejects_bearer_scheme_on_dpop_token():
+    """A DPoP-bound access token presented with `Authorization: Bearer` MUST be rejected.
+
+    Plan:
+      1. Acquire a DPoP-bound access token (mint a proof for the token endpoint).
+      2. Hit KAS /rewrap with `Authorization: Bearer <token>` and no DPoP header.
+      3. Expect 401 (and a `WWW-Authenticate: DPoP error=\"invalid_token\"` challenge).
+    """
+    pfs = tdfs.get_platform_features()
+    pfs.skip_if_unsupported("dpop")
+    pytest.fail("Not yet implemented")
+
+
+@pytest.mark.skip(
+    reason="TODO(tests-cell, DSPX-3397): wire up direct-HTTP DPoP negative tests once the platform-service PR lands."
+)
+def test_dpop_rejects_tampered_proof_htu():
+    """A DPoP proof whose `htu` claim does not match the request URI MUST be rejected."""
+    pfs = tdfs.get_platform_features()
+    pfs.skip_if_unsupported("dpop")
+    # 1. Acquire a DPoP-bound token.
+    # 2. Mint a proof with htu=https://kas.example.com/wrong-path, ath=correct.
+    # 3. POST to _kas_url() + "/v2/rewrap" with that proof.
+    # 4. Expect 401.
+    _ = _kas_url()
+    pytest.fail("Not yet implemented")
+
+
+@pytest.mark.skip(
+    reason="TODO(tests-cell, DSPX-3397): wire up direct-HTTP DPoP negative tests once the platform-service PR lands."
+)
+def test_dpop_rejects_replayed_jti():
+    """Replaying the same DPoP proof `jti` MUST be rejected the second time."""
+    pfs = tdfs.get_platform_features()
+    pfs.skip_if_unsupported("dpop")
+    # 1. Acquire a DPoP-bound token.
+    # 2. Mint a proof with a fixed jti and submit it. Expect 200.
+    # 3. Submit the byte-identical proof again. Expect 401.
+    pytest.fail("Not yet implemented")
+
+
+@pytest.mark.skip(
+    reason="TODO(tests-cell, DSPX-3397): wire up direct-HTTP DPoP negative tests once the platform-service PR lands."
+)
+def test_dpop_rejects_tampered_or_expired_nonce():
+    """When `require_nonce: true`, an unknown/tampered/expired nonce MUST 401 with a fresh DPoP-Nonce."""
+    pfs = tdfs.get_platform_features()
+    pfs.skip_if_unsupported("dpop")
+    # 1. Trigger the nonce challenge (request without nonce → 401 + DPoP-Nonce).
+    # 2. Submit a proof with nonce="not-the-issued-one".
+    # 3. Expect 401 and a `DPoP-Nonce: <fresh>` header on the response.
+    _ = time.time()
+    _ = urllib.request  # silence linter on stub; used by the real impl
+    _ = _b64u
+    pytest.fail("Not yet implemented")

From 5624554a9f80d61df71e5f7232bfd46ba1d52b76 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 11:02:20 -0400
Subject: [PATCH 47/64] test(DSPX-3397): single-quote feature spec todos so the
 YAML loader accepts colons

The orchestrator's ruamel-based loader rejects unquoted scalars that look
like nested mappings (e.g. `Authorization: Bearer <token>`,
`token_type=DPoP`, `services.kas.dpop.require_nonce`). Re-quote all
todo entries so the spec round-trips through orchestrate run.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 xtest/features/DSPX-3397.yaml | 48 +++++++++++++++++------------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/xtest/features/DSPX-3397.yaml b/xtest/features/DSPX-3397.yaml
index e54b649cd..005e99568 100644
--- a/xtest/features/DSPX-3397.yaml
+++ b/xtest/features/DSPX-3397.yaml
@@ -9,45 +9,45 @@ repos:
   tests:
     branch: DSPX-3397-kc26-dpop
     todo:
-      - "\"dpop\" is already registered in xtest/tdfs.py feature_type (alphabetical, between connectrpc and ecwrap) — verify."
-      - Update otdf-local to default to Keycloak 26 unconditionally (bump container/version pin, refresh realm import). Validate `uv run otdf-local up` boots KC26 and the platform authenticates. Document the bump in otdf-local/README.md.
-      - Bump any docker-compose / helm / CI workflow files in xtest/ that reference an older Keycloak version so the entire test harness defaults to KC26.
-      - Flesh out xtest/test_dpop.py negatives (Bearer-on-DPoP, tampered htu, replayed jti, tampered/expired nonce) — direct-HTTP cases against the platform's KAS endpoint with hand-minted proofs (see python `cryptography` and `jwcrypto` already in the dev deps).
-      - PR description should link to the four implementation PRs once they exist (`gh pr list --search "head:DSPX-3397"`).
+      - '"dpop" is already registered in xtest/tdfs.py feature_type (alphabetical, between connectrpc and ecwrap) — verify.'
+      - 'Update otdf-local to default to Keycloak 26 unconditionally (bump container/version pin, refresh realm import). Validate `uv run otdf-local up` boots KC26 and the platform authenticates. Document the bump in otdf-local/README.md.'
+      - 'Bump any docker-compose / helm / CI workflow files in xtest/ that reference an older Keycloak version so the entire test harness defaults to KC26.'
+      - 'Flesh out xtest/test_dpop.py negatives (Bearer-on-DPoP, tampered htu, replayed jti, tampered/expired nonce) — direct-HTTP cases against the platform''s KAS endpoint with hand-minted proofs (see python `cryptography` and `jwcrypto` already in the dev deps).'
+      - 'PR description should link to the four implementation PRs once they exist (`gh pr list --search "head:DSPX-3397"`).'
   platform-service:
     path: platform
     branch: DSPX-3397-platform-service
     todo:
-      - Audit `service/pkg/auth/` (or wherever the access-token middleware lives). `enforceDPoP: false` already exists in opentdf-*.yaml plus `Dpop` listed in auth mechanisms — extend rather than rewrite. Reuse the DPoP key+proof helpers in `test/integration/oauth/oauth_test.go`.
-      - Update the middleware to accept both `Authorization: Bearer <token>` and `Authorization: DPoP <token>` schemes.
-      - For `DPoP` scheme, validate the proof end-to-end per RFC 9449 §4.3 + §7.1 — header `typ=dpop+jwt` + `alg=ES256/RS256/PS256`; jwk extraction; verify signature; `htm` matches the request method; `htu` matches the normalized URI (lowercase scheme/host, default ports stripped, query+fragment stripped per spec §HTTP URI Normalization); `ath = base64url(SHA-256(access_token))`; RFC 7638 JWK thumbprint matches `cnf.jkt` in the access token.
-      - "Server-issued DPoP-Nonce challenges (RFC 9449 §8) — gated by a new config key `services.kas.dpop.require_nonce` (default false). When enabled, the middleware mints a short-lived opaque nonce, returns it via the `DPoP-Nonce` response header on every successful response *and* in 401 challenges (`use_dpop_nonce` error) when a proof arrives without the expected `nonce` claim. Validate the proof's `nonce` claim against the active nonce window (current + previous), rotate on a configurable interval, and reject tampered/expired nonces with 401 + fresh `DPoP-Nonce`."
-      - For gRPC paths, map `htm: \"POST\"` and `htu` to the full gRPC service path (spec §Edge Cases). Propagate `DPoP-Nonce` via response headers/trailers.
-      - Verify the platform boots and authenticates against a local KC26 once the tests-cell otdf-local bump lands. Add at least one Go unit test per validation rule (signature, htm, htu, ath, jkt, nonce-current, nonce-rotated, nonce-tampered).
-      - Add `supports dpop` case to the platform's policy/KAS-side feature gate so `pfs.skip_if_unsupported(\"dpop\")` in tests sees it.
+      - 'Audit `service/pkg/auth/` (or wherever the access-token middleware lives). `enforceDPoP: false` already exists in opentdf-*.yaml plus `Dpop` listed in auth mechanisms — extend rather than rewrite. Reuse the DPoP key+proof helpers in `test/integration/oauth/oauth_test.go`.'
+      - 'Update the middleware to accept both `Authorization: Bearer <token>` and `Authorization: DPoP <token>` schemes.'
+      - 'For `DPoP` scheme, validate the proof end-to-end per RFC 9449 §4.3 + §7.1 — header `typ=dpop+jwt` + `alg=ES256/RS256/PS256`; jwk extraction; verify signature; `htm` matches the request method; `htu` matches the normalized URI (lowercase scheme/host, default ports stripped, query+fragment stripped per spec §HTTP URI Normalization); `ath = base64url(SHA-256(access_token))`; RFC 7638 JWK thumbprint matches `cnf.jkt` in the access token.'
+      - 'Server-issued DPoP-Nonce challenges (RFC 9449 §8) — gated by a new config key `services.kas.dpop.require_nonce` (default false). When enabled, the middleware mints a short-lived opaque nonce, returns it via the `DPoP-Nonce` response header on every successful response *and* in 401 challenges (`use_dpop_nonce` error) when a proof arrives without the expected `nonce` claim. Validate the proof''s `nonce` claim against the active nonce window (current + previous), rotate on a configurable interval, and reject tampered/expired nonces with 401 + fresh `DPoP-Nonce`.'
+      - 'For gRPC paths, map `htm: "POST"` and `htu` to the full gRPC service path (spec §Edge Cases). Propagate `DPoP-Nonce` via response headers/trailers.'
+      - 'Verify the platform boots and authenticates against a local KC26 once the tests-cell otdf-local bump lands. Add at least one Go unit test per validation rule (signature, htm, htu, ath, jkt, nonce-current, nonce-rotated, nonce-tampered).'
+      - 'Add `supports dpop` case to the platform''s policy/KAS-side feature gate so `pfs.skip_if_unsupported("dpop")` in tests sees it.'
   platform-go-sdk:
     path: platform
     branch: DSPX-3397-platform-go-sdk
     todo:
-      - Add DPoP client support to the Go SDK auth layer (likely `sdk/auth/` or `sdk/oauth/`). Generate an ephemeral EC P-256 (ES256) key per SDK instance by default; accept a caller-supplied `crypto.Signer` for persistence (HSM is out of scope).
-      - "HTTP interceptor compatible with the SDK's HTTP client. Token endpoint: emit proof with claims `jti, htm=\"POST\", htu=<token-endpoint>, iat`. Resource endpoints (KAS / policy / kasregistry): when the access token is DPoP-bound (`token_type=DPoP`), emit proof with added `ath = base64url(SHA-256(token))`, set `Authorization: DPoP <token>` instead of `Bearer`."
-      - "Handle server-issued nonce: on 401 with a `DPoP-Nonce` response header, cache the nonce (per-origin), regenerate the proof with the `nonce` claim, retry once. Refresh cached nonces from successful responses too."
-      - Add `supports dpop` case to xtest/sdk/go/cli.sh source — the awk predicate should match a stable DPoP-related flag or feature string introduced by this PR.
+      - 'Add DPoP client support to the Go SDK auth layer (likely `sdk/auth/` or `sdk/oauth/`). Generate an ephemeral EC P-256 (ES256) key per SDK instance by default; accept a caller-supplied `crypto.Signer` for persistence (HSM is out of scope).'
+      - 'HTTP interceptor compatible with the SDK''s HTTP client. Token endpoint: emit proof with claims `jti, htm="POST", htu=<token-endpoint>, iat`. Resource endpoints (KAS / policy / kasregistry): when the access token is DPoP-bound (`token_type=DPoP`), emit proof with added `ath = base64url(SHA-256(token))`, set `Authorization: DPoP <token>` instead of `Bearer`.'
+      - 'Handle server-issued nonce: on 401 with a `DPoP-Nonce` response header, cache the nonce (per-origin), regenerate the proof with the `nonce` claim, retry once. Refresh cached nonces from successful responses too.'
+      - 'Add `supports dpop` case to xtest/sdk/go/cli.sh source — the awk predicate should match a stable DPoP-related flag or feature string introduced by this PR.'
   java-sdk:
     path: java-sdk
     branch: DSPX-3397-java-sdk
     todo:
-      - Same shape as the Go SDK but for Java. Use Nimbus JOSE+JWT (already a likely dep) or BouncyCastle for EC P-256 + ES256 signing. Audit existing `DefaultSrtSigner` scaffolding in `sdk/src/test/java/io/opentdf/platform/sdk/{KASClientTest,SDKBuilderTest}.java` — extend or align with the production flow rather than introducing a parallel signer abstraction.
-      - HTTP interceptor for the SDK's OkHttp client (or `java.net.http.HttpClient`) with the same proof-generation rules (`htm/htu/iat/jti` always; `ath` on resource calls; `nonce` retry on 401+DPoP-Nonce).
-      - Surface a `DpopConfig` (or similar) in `SDKBuilder` so callers can pass a `KeyPair` or `PrivateKey`, or rely on the SDK's auto-generated ephemeral key.
-      - Add `supports dpop` case to xtest/sdk/java/cli.sh source.
+      - 'Same shape as the Go SDK but for Java. Use Nimbus JOSE+JWT (already a likely dep) or BouncyCastle for EC P-256 + ES256 signing. Audit existing `DefaultSrtSigner` scaffolding in `sdk/src/test/java/io/opentdf/platform/sdk/{KASClientTest,SDKBuilderTest}.java` — extend or align with the production flow rather than introducing a parallel signer abstraction.'
+      - 'HTTP interceptor for the SDK''s OkHttp client (or `java.net.http.HttpClient`) with the same proof-generation rules (`htm/htu/iat/jti` always; `ath` on resource calls; `nonce` retry on 401+DPoP-Nonce).'
+      - 'Surface a `DpopConfig` (or similar) in `SDKBuilder` so callers can pass a `KeyPair` or `PrivateKey`, or rely on the SDK''s auto-generated ephemeral key.'
+      - 'Add `supports dpop` case to xtest/sdk/java/cli.sh source.'
   web-sdk:
     path: web-sdk
     branch: DSPX-3397-web-sdk
     todo:
-      - Audit existing DPoP integration in `lib/src/session.ts` (uses the `dpop` npm package). Confirm proofs for both the token endpoint and KAS exchanges include `ath` on resource calls and that the JWK thumbprint flows through to `cnf.jkt`.
-      - Implement / verify the `DPoP-Nonce` 401 retry loop in the SDK's HTTP layer (not just the OIDC client). Refresh the cached nonce from successful responses' `DPoP-Nonce` header.
-      - Ensure every KAS-facing client (rewrap, policy, kasregistry — `lib/src/access.ts` and related) propagates DPoP headers, not only the OIDC token-exchange path.
-      - Add `supports dpop` case to xtest/sdk/js/cli.sh source. Coordinate the CLI flag exposure in `cli/src/cli.ts` (currently `--dpop` is wired up — verify and document).
+      - 'Audit existing DPoP integration in `lib/src/session.ts` (uses the `dpop` npm package). Confirm proofs for both the token endpoint and KAS exchanges include `ath` on resource calls and that the JWK thumbprint flows through to `cnf.jkt`.'
+      - 'Implement / verify the `DPoP-Nonce` 401 retry loop in the SDK''s HTTP layer (not just the OIDC client). Refresh the cached nonce from successful responses'' `DPoP-Nonce` header.'
+      - 'Ensure every KAS-facing client (rewrap, policy, kasregistry — `lib/src/access.ts` and related) propagates DPoP headers, not only the OIDC token-exchange path.'
+      - 'Add `supports dpop` case to xtest/sdk/js/cli.sh source. Coordinate the CLI flag exposure in `cli/src/cli.ts` (currently `--dpop` is wired up — verify and document).'
 scenarios:
   - xtest/scenarios/DSPX-3397.yaml

From 9292cd5abf860e9da04dbf91526d3b705946d7d8 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 11:16:26 -0400
Subject: [PATCH 48/64] test(DSPX-3397): pin nonce + Go interceptor decisions
 in feature spec

First orchestrate dispatch had platform-service and platform-go-sdk
subagents stop at clarifying questions instead of committing. Embed the
decisions directly in the cell todos so a `--force --only` re-dispatch
picks them up:

- platform-service: use the standard RFC 9449 challenge-then-accept
  pattern for nonces (first request without nonce gets 401+DPoP-Nonce,
  client retries with nonce, succeeds). Strict-from-start would break
  interop with every standard DPoP client.
- platform-go-sdk: implement the resource-side proof generation as an
  http.RoundTripper (idiomatic Go, composes into any *http.Client).
  Extend the existing TokenAddingInterceptor only for symmetry.

Both todos now also say "make decisions and proceed; do not stop to
clarify" so subagents commit instead of asking.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 xtest/features/DSPX-3397.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/xtest/features/DSPX-3397.yaml b/xtest/features/DSPX-3397.yaml
index 005e99568..975669b88 100644
--- a/xtest/features/DSPX-3397.yaml
+++ b/xtest/features/DSPX-3397.yaml
@@ -21,7 +21,7 @@ repos:
       - 'Audit `service/pkg/auth/` (or wherever the access-token middleware lives). `enforceDPoP: false` already exists in opentdf-*.yaml plus `Dpop` listed in auth mechanisms — extend rather than rewrite. Reuse the DPoP key+proof helpers in `test/integration/oauth/oauth_test.go`.'
       - 'Update the middleware to accept both `Authorization: Bearer <token>` and `Authorization: DPoP <token>` schemes.'
       - 'For `DPoP` scheme, validate the proof end-to-end per RFC 9449 §4.3 + §7.1 — header `typ=dpop+jwt` + `alg=ES256/RS256/PS256`; jwk extraction; verify signature; `htm` matches the request method; `htu` matches the normalized URI (lowercase scheme/host, default ports stripped, query+fragment stripped per spec §HTTP URI Normalization); `ath = base64url(SHA-256(access_token))`; RFC 7638 JWK thumbprint matches `cnf.jkt` in the access token.'
-      - 'Server-issued DPoP-Nonce challenges (RFC 9449 §8) — gated by a new config key `services.kas.dpop.require_nonce` (default false). When enabled, the middleware mints a short-lived opaque nonce, returns it via the `DPoP-Nonce` response header on every successful response *and* in 401 challenges (`use_dpop_nonce` error) when a proof arrives without the expected `nonce` claim. Validate the proof''s `nonce` claim against the active nonce window (current + previous), rotate on a configurable interval, and reject tampered/expired nonces with 401 + fresh `DPoP-Nonce`.'
+      - 'Server-issued DPoP-Nonce challenges (RFC 9449 §8) — gated by a new config key `services.kas.dpop.require_nonce` (default false). Use the standard RFC 9449 challenge-then-accept pattern: a first request without a `nonce` claim is met with 401 + `DPoP-Nonce: <opaque>` + `WWW-Authenticate: DPoP error="use_dpop_nonce"`; the client retries with the nonce claim and succeeds. Do NOT require nonces from the first request — that variant breaks interop with every standard DPoP client (including the SDKs being built in this same feature). Validate the proof''s `nonce` claim against the active nonce window (current + previous, to allow graceful rotation), rotate on a configurable interval (default ~5 minutes), and reject tampered/expired nonces with 401 + a fresh `DPoP-Nonce`. Make decisions about edge cases and proceed without asking; do not stop to clarify.'
       - 'For gRPC paths, map `htm: "POST"` and `htu` to the full gRPC service path (spec §Edge Cases). Propagate `DPoP-Nonce` via response headers/trailers.'
       - 'Verify the platform boots and authenticates against a local KC26 once the tests-cell otdf-local bump lands. Add at least one Go unit test per validation rule (signature, htm, htu, ath, jkt, nonce-current, nonce-rotated, nonce-tampered).'
       - 'Add `supports dpop` case to the platform''s policy/KAS-side feature gate so `pfs.skip_if_unsupported("dpop")` in tests sees it.'
@@ -30,7 +30,7 @@ repos:
     branch: DSPX-3397-platform-go-sdk
     todo:
       - 'Add DPoP client support to the Go SDK auth layer (likely `sdk/auth/` or `sdk/oauth/`). Generate an ephemeral EC P-256 (ES256) key per SDK instance by default; accept a caller-supplied `crypto.Signer` for persistence (HSM is out of scope).'
-      - 'HTTP interceptor compatible with the SDK''s HTTP client. Token endpoint: emit proof with claims `jti, htm="POST", htu=<token-endpoint>, iat`. Resource endpoints (KAS / policy / kasregistry): when the access token is DPoP-bound (`token_type=DPoP`), emit proof with added `ath = base64url(SHA-256(token))`, set `Authorization: DPoP <token>` instead of `Bearer`.'
+      - 'Implement the resource-side proof generation as a `http.RoundTripper` that wraps the default transport and can be composed into any `*http.Client`. This is the idiomatic Go pattern and the most flexible (REST + Connect/gRPC HTTP2 + raw KAS calls all flow through `http.Client`). Token endpoint: emit proof with claims `jti, htm="POST", htu=<token-endpoint>, iat`. Resource endpoints (KAS / policy / kasregistry): when the access token is DPoP-bound (`token_type=DPoP`), emit proof with added `ath = base64url(SHA-256(token))`, set `Authorization: DPoP <token>` instead of `Bearer`. Extend the existing `TokenAddingInterceptor` (gRPC/Connect path) only if needed for symmetry; the new RoundTripper is the primary surface. Make decisions and proceed; do not stop to clarify.'
       - 'Handle server-issued nonce: on 401 with a `DPoP-Nonce` response header, cache the nonce (per-origin), regenerate the proof with the `nonce` claim, retry once. Refresh cached nonces from successful responses too.'
       - 'Add `supports dpop` case to xtest/sdk/go/cli.sh source — the awk predicate should match a stable DPoP-related flag or feature string introduced by this PR.'
   java-sdk:

From 15874e5ac20f35ad4e1ff928e6a7a7e2557f700c Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 13:12:23 -0400
Subject: [PATCH 49/64] Add direct DPoP negative tests

Signed-off-by: Dave Mihalcik <dmihalcik@virtru.com>
---
 xtest/test_dpop.py | 506 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 457 insertions(+), 49 deletions(-)

diff --git a/xtest/test_dpop.py b/xtest/test_dpop.py
index 996a372ef..36fc65e38 100644
--- a/xtest/test_dpop.py
+++ b/xtest/test_dpop.py
@@ -13,12 +13,23 @@
 
 import base64
 import filecmp
+import hashlib
+import json
 import os
+import secrets
 import time
-import urllib.request
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
 
 import pytest
+import requests
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
 
 import tdfs
 from abac import Attribute
@@ -32,6 +43,314 @@ def _kas_url() -> str:
     )
 
 
+def _env(name: str, default: str) -> str:
+    value = os.getenv(name)
+    if value:
+        return value
+    return default
+
+
+def _token_endpoint() -> str:
+    if endpoint := os.getenv("TOKENENDPOINT"):
+        return endpoint
+    kc_full_url = _env(
+        "KCFULLURL",
+        f"{_env('KCHOST', 'http://localhost:8888')}/auth/realms/{_env('REALM', 'opentdf')}",
+    )
+    return f"{kc_full_url}/protocol/openid-connect/token"
+
+
+def _b64u(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64u_int(value: int) -> str:
+    length = (value.bit_length() + 7) // 8
+    return _b64u(value.to_bytes(length, "big"))
+
+
+def _jwt_payload(token: str) -> dict[str, Any]:
+    parts = token.split(".")
+    if len(parts) < 2:
+        raise AssertionError("expected access token to be a JWT")
+    payload = parts[1] + "=" * (-len(parts[1]) % 4)
+    return json.loads(base64.urlsafe_b64decode(payload))
+
+
+def _sign_jwt(
+    private_key: RSAPrivateKey,
+    header: Mapping[str, Any],
+    payload: Mapping[str, Any],
+) -> str:
+    header_b64 = _b64u(
+        json.dumps(header, separators=(",", ":"), sort_keys=True).encode()
+    )
+    payload_b64 = _b64u(
+        json.dumps(payload, separators=(",", ":"), sort_keys=True).encode()
+    )
+    signing_input = f"{header_b64}.{payload_b64}".encode("ascii")
+    signature = private_key.sign(signing_input, padding.PKCS1v15(), hashes.SHA256())
+    return f"{header_b64}.{payload_b64}.{_b64u(signature)}"
+
+
+@dataclass(frozen=True)
+class DPoPKey:
+    private_key: RSAPrivateKey
+    public_jwk: dict[str, str]
+
+    @classmethod
+    def generate(cls) -> DPoPKey:
+        private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+        public_numbers = private_key.public_key().public_numbers()
+        return cls(
+            private_key=private_key,
+            public_jwk={
+                "kty": "RSA",
+                "n": _b64u_int(public_numbers.n),
+                "e": _b64u_int(public_numbers.e),
+            },
+        )
+
+    @property
+    def thumbprint(self) -> str:
+        # RFC 7638 canonical member set for RSA public keys.
+        canonical = json.dumps(
+            {
+                "e": self.public_jwk["e"],
+                "kty": self.public_jwk["kty"],
+                "n": self.public_jwk["n"],
+            },
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode("ascii")
+        return _b64u(hashlib.sha256(canonical).digest())
+
+    @property
+    def public_pem(self) -> str:
+        return (
+            self.private_key.public_key()
+            .public_bytes(
+                serialization.Encoding.PEM,
+                serialization.PublicFormat.SubjectPublicKeyInfo,
+            )
+            .decode("ascii")
+        )
+
+    def sign(self, payload: Mapping[str, Any], typ: str = "JWT") -> str:
+        return _sign_jwt(
+            self.private_key,
+            {"alg": "RS256", "typ": typ},
+            payload,
+        )
+
+    def sign_dpop_proof(
+        self,
+        *,
+        htm: str,
+        htu: str,
+        access_token: str | None = None,
+        nonce: str | None = None,
+        jti: str | None = None,
+    ) -> str:
+        payload: dict[str, Any] = {
+            "htm": htm,
+            "htu": htu,
+            "iat": int(time_now()),
+            "jti": jti or str(uuid.uuid4()),
+        }
+        if access_token is not None:
+            payload["ath"] = _b64u(
+                hashlib.sha256(access_token.encode("ascii")).digest()
+            )
+        if nonce is not None:
+            payload["nonce"] = nonce
+        return _sign_jwt(
+            self.private_key,
+            {
+                "alg": "RS256",
+                "jwk": self.public_jwk,
+                "typ": "dpop+jwt",
+            },
+            payload,
+        )
+
+
+def time_now() -> int:
+    return int(time.time())
+
+
+@dataclass(frozen=True)
+class DPoPAccessToken:
+    token: str
+    key: DPoPKey
+
+
+@dataclass(frozen=True)
+class RewrapCall:
+    url: str
+    headers: dict[str, str]
+    body: str
+
+
+def _get_dpop_access_token() -> DPoPAccessToken:
+    key = DPoPKey.generate()
+    token_endpoint = _token_endpoint()
+    client_id = _env("CLIENTID", "opentdf")
+    client_secret = _env("CLIENTSECRET", "secret")
+
+    def post_token(nonce: str | None = None) -> requests.Response:
+        proof = key.sign_dpop_proof(
+            htm="POST",
+            htu=token_endpoint,
+            nonce=nonce,
+        )
+        return requests.post(
+            token_endpoint,
+            auth=(client_id, client_secret),
+            data={"grant_type": "client_credentials"},
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/x-www-form-urlencoded",
+                "DPoP": proof,
+            },
+            timeout=15,
+        )
+
+    response = post_token()
+    nonce = response.headers.get("DPoP-Nonce")
+    if response.status_code == 400 and nonce:
+        response = post_token(nonce)
+
+    assert response.status_code == 200, response.text
+    body = response.json()
+    assert body.get("token_type") == "DPoP", body
+    access_token = body["access_token"]
+
+    token_payload = _jwt_payload(access_token)
+    assert token_payload.get("cnf", {}).get("jkt") == key.thumbprint
+    return DPoPAccessToken(token=access_token, key=key)
+
+
+def _connect_rewrap_url(kas_url: str) -> str:
+    parsed = urlparse(kas_url)
+    return f"{parsed.scheme}://{parsed.netloc}/kas.AccessService/Rewrap"
+
+
+def _rewrap_htu() -> str:
+    # This matches the ConnectRPC procedure string used by the platform SDK and
+    # server interceptor for KAS Rewrap.
+    return "/kas.AccessService/Rewrap"
+
+
+def _policy_binding(kao: tdfs.KeyAccessObject) -> dict[str, str]:
+    binding = kao.policyBinding
+    if isinstance(binding, str):
+        return {"hash": binding}
+    return {"alg": binding.alg, "hash": binding.hash}
+
+
+def _key_access_object(kao: tdfs.KeyAccessObject) -> dict[str, Any]:
+    value: dict[str, Any] = {
+        "type": kao.type,
+        "url": kao.url,
+        "protocol": kao.protocol,
+        "wrappedKey": kao.wrappedKey,
+        "policyBinding": _policy_binding(kao),
+    }
+    optional = {
+        "encryptedMetadata": kao.encryptedMetadata,
+        "kid": kao.kid,
+        "sid": kao.sid,
+        "ephemeralPublicKey": kao.ephemeralPublicKey,
+    }
+    value.update({k: v for k, v in optional.items() if v is not None})
+    return value
+
+
+def _rewrap_request_body(
+    tdf_file: Path, session_public_key_pem: str
+) -> tuple[str, str]:
+    manifest = tdfs.manifest(tdf_file)
+    kao = manifest.encryptionInformation.keyAccess[0]
+    request_body = {
+        "clientPublicKey": session_public_key_pem,
+        "requests": [
+            {
+                "keyAccessObjects": [
+                    {
+                        "keyAccessObjectId": "kao-0",
+                        "keyAccessObject": _key_access_object(kao),
+                    }
+                ],
+                "policy": {
+                    "id": "policy",
+                    "body": manifest.encryptionInformation.policy,
+                },
+            }
+        ],
+    }
+    return kao.url, json.dumps(request_body, separators=(",", ":"), sort_keys=True)
+
+
+def _signed_rewrap_request(tdf_file: Path, key: DPoPKey) -> RewrapCall:
+    kas_url, request_body = _rewrap_request_body(tdf_file, key.public_pem)
+    now = time_now()
+    signed_request_token = key.sign(
+        {
+            "exp": now + 60,
+            "iat": now,
+            "requestBody": request_body,
+        }
+    )
+    additional_context = base64.b64encode(
+        json.dumps(
+            {"obligations": {"fulfillableFQNs": []}},
+            separators=(",", ":"),
+        ).encode("ascii")
+    ).decode("ascii")
+    return RewrapCall(
+        url=_connect_rewrap_url(kas_url),
+        headers={
+            "Accept": "application/json",
+            "Connect-Protocol-Version": "1",
+            "Content-Type": "application/json",
+            "X-Rewrap-Additional-Context": additional_context,
+        },
+        body=json.dumps({"signedRequestToken": signed_request_token}),
+    )
+
+
+def _post_rewrap(
+    call: RewrapCall,
+    *,
+    access_token: str,
+    dpop_proof: str | None,
+    auth_scheme: str = "DPoP",
+) -> requests.Response:
+    headers = dict(call.headers)
+    headers["Authorization"] = f"{auth_scheme} {access_token}"
+    if dpop_proof is not None:
+        headers["DPoP"] = dpop_proof
+    return requests.post(
+        call.url,
+        data=call.body,
+        headers=headers,
+        timeout=15,
+    )
+
+
+def _assert_unauthorized(response: requests.Response) -> None:
+    assert response.status_code == 401, response.text
+
+
+def _skip_unless_dpop_enabled(encrypt_sdk: tdfs.SDK, in_focus: set[tdfs.SDK]) -> None:
+    if encrypt_sdk not in in_focus:
+        pytest.skip("Not in focus")
+    pfs = tdfs.get_platform_features()
+    pfs.skip_if_unsupported("dpop")
+    encrypt_sdk.skip_if_unsupported("dpop")
+
+
 def test_dpop_happy_path_roundtrip(
     attribute_single_kas_grant: tuple[Attribute, list[str]],
     encrypt_sdk: tdfs.SDK,
@@ -103,14 +422,12 @@ def test_dpop_server_issued_nonce_retry(
     assert filecmp.cmp(pt_file, rt_file)
 
 
-def _b64u(data: bytes) -> str:
-    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
-
-
-@pytest.mark.skip(
-    reason="TODO(tests-cell, DSPX-3397): wire up direct-HTTP DPoP negative tests once the platform-service PR lands."
-)
-def test_dpop_rejects_bearer_scheme_on_dpop_token():
+def test_dpop_rejects_bearer_scheme_on_dpop_token(
+    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    encrypt_sdk: tdfs.SDK,
+    in_focus: set[tdfs.SDK],
+    encrypted_tdf: EncryptFactory,
+):
     """A DPoP-bound access token presented with `Authorization: Bearer` MUST be rejected.
 
     Plan:
@@ -118,50 +435,141 @@ def test_dpop_rejects_bearer_scheme_on_dpop_token():
       2. Hit KAS /rewrap with `Authorization: Bearer <token>` and no DPoP header.
       3. Expect 401 (and a `WWW-Authenticate: DPoP error=\"invalid_token\"` challenge).
     """
-    pfs = tdfs.get_platform_features()
-    pfs.skip_if_unsupported("dpop")
-    pytest.fail("Not yet implemented")
+    _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
+
+    attr, _ = attribute_single_kas_grant
+    ct_file = encrypted_tdf(encrypt_sdk, attr_values=attr.value_fqns)
+    dpop_access = _get_dpop_access_token()
+    rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
+
+    response = _post_rewrap(
+        rewrap_call,
+        access_token=dpop_access.token,
+        dpop_proof=None,
+        auth_scheme="Bearer",
+    )
+
+    _assert_unauthorized(response)
 
 
-@pytest.mark.skip(
-    reason="TODO(tests-cell, DSPX-3397): wire up direct-HTTP DPoP negative tests once the platform-service PR lands."
-)
-def test_dpop_rejects_tampered_proof_htu():
+def test_dpop_rejects_tampered_proof_htu(
+    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    encrypt_sdk: tdfs.SDK,
+    in_focus: set[tdfs.SDK],
+    encrypted_tdf: EncryptFactory,
+):
     """A DPoP proof whose `htu` claim does not match the request URI MUST be rejected."""
-    pfs = tdfs.get_platform_features()
-    pfs.skip_if_unsupported("dpop")
-    # 1. Acquire a DPoP-bound token.
-    # 2. Mint a proof with htu=https://kas.example.com/wrong-path, ath=correct.
-    # 3. POST to _kas_url() + "/v2/rewrap" with that proof.
-    # 4. Expect 401.
-    _ = _kas_url()
-    pytest.fail("Not yet implemented")
-
-
-@pytest.mark.skip(
-    reason="TODO(tests-cell, DSPX-3397): wire up direct-HTTP DPoP negative tests once the platform-service PR lands."
-)
-def test_dpop_rejects_replayed_jti():
+    _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
+
+    attr, _ = attribute_single_kas_grant
+    ct_file = encrypted_tdf(encrypt_sdk, attr_values=attr.value_fqns)
+    dpop_access = _get_dpop_access_token()
+    rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
+    proof = dpop_access.key.sign_dpop_proof(
+        htm="POST",
+        htu="/kas.AccessService/WrongRewrap",
+        access_token=dpop_access.token,
+    )
+
+    response = _post_rewrap(
+        rewrap_call,
+        access_token=dpop_access.token,
+        dpop_proof=proof,
+    )
+
+    _assert_unauthorized(response)
+
+
+def test_dpop_rejects_replayed_jti(
+    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    encrypt_sdk: tdfs.SDK,
+    in_focus: set[tdfs.SDK],
+    encrypted_tdf: EncryptFactory,
+):
     """Replaying the same DPoP proof `jti` MUST be rejected the second time."""
-    pfs = tdfs.get_platform_features()
-    pfs.skip_if_unsupported("dpop")
-    # 1. Acquire a DPoP-bound token.
-    # 2. Mint a proof with a fixed jti and submit it. Expect 200.
-    # 3. Submit the byte-identical proof again. Expect 401.
-    pytest.fail("Not yet implemented")
+    _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
 
+    attr, _ = attribute_single_kas_grant
+    ct_file = encrypted_tdf(encrypt_sdk, attr_values=attr.value_fqns)
+    dpop_access = _get_dpop_access_token()
+    rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
 
-@pytest.mark.skip(
-    reason="TODO(tests-cell, DSPX-3397): wire up direct-HTTP DPoP negative tests once the platform-service PR lands."
-)
-def test_dpop_rejects_tampered_or_expired_nonce():
+    proof = dpop_access.key.sign_dpop_proof(
+        htm="POST",
+        htu=_rewrap_htu(),
+        access_token=dpop_access.token,
+        jti=f"xtest-{secrets.token_urlsafe(16)}",
+    )
+    first = _post_rewrap(
+        rewrap_call,
+        access_token=dpop_access.token,
+        dpop_proof=proof,
+    )
+    nonce = first.headers.get("DPoP-Nonce")
+    if first.status_code == 401 and nonce:
+        proof = dpop_access.key.sign_dpop_proof(
+            htm="POST",
+            htu=_rewrap_htu(),
+            access_token=dpop_access.token,
+            nonce=nonce,
+            jti=f"xtest-{secrets.token_urlsafe(16)}",
+        )
+        first = _post_rewrap(
+            rewrap_call,
+            access_token=dpop_access.token,
+            dpop_proof=proof,
+        )
+
+    assert first.status_code == 200, first.text
+
+    second = _post_rewrap(
+        rewrap_call,
+        access_token=dpop_access.token,
+        dpop_proof=proof,
+    )
+
+    _assert_unauthorized(second)
+
+
+def test_dpop_rejects_tampered_or_expired_nonce(
+    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    encrypt_sdk: tdfs.SDK,
+    in_focus: set[tdfs.SDK],
+    encrypted_tdf: EncryptFactory,
+):
     """When `require_nonce: true`, an unknown/tampered/expired nonce MUST 401 with a fresh DPoP-Nonce."""
-    pfs = tdfs.get_platform_features()
-    pfs.skip_if_unsupported("dpop")
-    # 1. Trigger the nonce challenge (request without nonce → 401 + DPoP-Nonce).
-    # 2. Submit a proof with nonce="not-the-issued-one".
-    # 3. Expect 401 and a `DPoP-Nonce: <fresh>` header on the response.
-    _ = time.time()
-    _ = urllib.request  # silence linter on stub; used by the real impl
-    _ = _b64u
-    pytest.fail("Not yet implemented")
+    _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
+
+    attr, _ = attribute_single_kas_grant
+    ct_file = encrypted_tdf(encrypt_sdk, attr_values=attr.value_fqns)
+    dpop_access = _get_dpop_access_token()
+    rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
+
+    initial_proof = dpop_access.key.sign_dpop_proof(
+        htm="POST",
+        htu=_rewrap_htu(),
+        access_token=dpop_access.token,
+    )
+    challenge = _post_rewrap(
+        rewrap_call,
+        access_token=dpop_access.token,
+        dpop_proof=initial_proof,
+    )
+    issued_nonce = challenge.headers.get("DPoP-Nonce")
+    if challenge.status_code != 401 or not issued_nonce:
+        pytest.skip("KAS resource-server DPoP nonce enforcement is not enabled")
+
+    tampered_proof = dpop_access.key.sign_dpop_proof(
+        htm="POST",
+        htu=_rewrap_htu(),
+        access_token=dpop_access.token,
+        nonce=f"tampered-{issued_nonce}",
+    )
+    response = _post_rewrap(
+        rewrap_call,
+        access_token=dpop_access.token,
+        dpop_proof=tampered_proof,
+    )
+
+    _assert_unauthorized(response)
+    assert response.headers.get("DPoP-Nonce")

From 3b19a72a14a07af5fe88fc983d7a85985cd3fa04 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 13:17:32 -0400
Subject: [PATCH 50/64] test(DSPX-3397): fix htu bug and tighten dpop negatives
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review against the platform middleware (PR #3582 normalizeURL) and the Go
SDK transport (PR #3581 normalizeURI) showed the test was building `htu`
as a path-only string, while both the server and the production client
build it as the full <scheme>://<host><path> URL. Consequence: the
replayed-jti and tampered-nonce tests never reached their replay/tamper
assertions — every proof 401'd on htu mismatch at the first request.

This commit:

- Replaces every `htu=_rewrap_htu()` callsite with `htu=rewrap_call.url`
  (already the full normalized URL); drops the misleading helper.
- Changes the tampered-htu test to use a well-formed full URL with the
  wrong path so it exercises a real tamper, not a malformed value.
- Strengthens `_assert_unauthorized` to also assert the
  `WWW-Authenticate: DPoP` challenge header, so a misconfigured realm
  returning 401 for unrelated reasons doesn't silently "pass" the test.
- Adds a fresh-proof-same-jti sub-case to test_dpop_rejects_replayed_jti
  to exercise the stronger RFC 9449 §11.1 attack vector (server must
  remember jti values across requests, not just dedupe identical bytes).
- Renames test_dpop_rejects_tampered_or_expired_nonce →
  test_dpop_rejects_tampered_nonce (expiry case deferred for now).
- Switches _get_dpop_access_token to `pytest.skip(...)` when KC hands
  back a Bearer token, so misconfigured local envs produce a clear skip
  instead of an opaque AssertionError dumping the token response.
- Drops the redundant _env helper (os.getenv already does the same).
- Replaces hand-rolled _key_access_object/_policy_binding with
  KeyAccessObject.model_dump(exclude_none=True) — Pydantic field names
  already match Connect-RPC's JSON shape for kas.proto's KeyAccess.
- Moves time_now() above DPoPKey for top-to-bottom readability.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 xtest/test_dpop.py | 115 ++++++++++++++++++++++-----------------------
 1 file changed, 56 insertions(+), 59 deletions(-)

diff --git a/xtest/test_dpop.py b/xtest/test_dpop.py
index 36fc65e38..272a9d64d 100644
--- a/xtest/test_dpop.py
+++ b/xtest/test_dpop.py
@@ -43,19 +43,12 @@ def _kas_url() -> str:
     )
 
 
-def _env(name: str, default: str) -> str:
-    value = os.getenv(name)
-    if value:
-        return value
-    return default
-
-
 def _token_endpoint() -> str:
     if endpoint := os.getenv("TOKENENDPOINT"):
         return endpoint
-    kc_full_url = _env(
+    kc_full_url = os.getenv(
         "KCFULLURL",
-        f"{_env('KCHOST', 'http://localhost:8888')}/auth/realms/{_env('REALM', 'opentdf')}",
+        f"{os.getenv('KCHOST', 'http://localhost:8888')}/auth/realms/{os.getenv('REALM', 'opentdf')}",
     )
     return f"{kc_full_url}/protocol/openid-connect/token"
 
@@ -93,6 +86,10 @@ def _sign_jwt(
     return f"{header_b64}.{payload_b64}.{_b64u(signature)}"
 
 
+def time_now() -> int:
+    return int(time.time())
+
+
 @dataclass(frozen=True)
 class DPoPKey:
     private_key: RSAPrivateKey
@@ -175,10 +172,6 @@ def sign_dpop_proof(
         )
 
 
-def time_now() -> int:
-    return int(time.time())
-
-
 @dataclass(frozen=True)
 class DPoPAccessToken:
     token: str
@@ -195,8 +188,8 @@ class RewrapCall:
 def _get_dpop_access_token() -> DPoPAccessToken:
     key = DPoPKey.generate()
     token_endpoint = _token_endpoint()
-    client_id = _env("CLIENTID", "opentdf")
-    client_secret = _env("CLIENTSECRET", "secret")
+    client_id = os.getenv("CLIENTID", "opentdf")
+    client_secret = os.getenv("CLIENTSECRET", "secret")
 
     def post_token(nonce: str | None = None) -> requests.Response:
         proof = key.sign_dpop_proof(
@@ -223,7 +216,11 @@ def post_token(nonce: str | None = None) -> requests.Response:
 
     assert response.status_code == 200, response.text
     body = response.json()
-    assert body.get("token_type") == "DPoP", body
+    if body.get("token_type") != "DPoP":
+        pytest.skip(
+            f"Keycloak realm not configured for DPoP (token_type={body.get('token_type')!r}); "
+            "set the realm's OAuth client to require DPoP-bound tokens"
+        )
     access_token = body["access_token"]
 
     token_payload = _jwt_payload(access_token)
@@ -236,42 +233,14 @@ def _connect_rewrap_url(kas_url: str) -> str:
     return f"{parsed.scheme}://{parsed.netloc}/kas.AccessService/Rewrap"
 
 
-def _rewrap_htu() -> str:
-    # This matches the ConnectRPC procedure string used by the platform SDK and
-    # server interceptor for KAS Rewrap.
-    return "/kas.AccessService/Rewrap"
-
-
-def _policy_binding(kao: tdfs.KeyAccessObject) -> dict[str, str]:
-    binding = kao.policyBinding
-    if isinstance(binding, str):
-        return {"hash": binding}
-    return {"alg": binding.alg, "hash": binding.hash}
-
-
-def _key_access_object(kao: tdfs.KeyAccessObject) -> dict[str, Any]:
-    value: dict[str, Any] = {
-        "type": kao.type,
-        "url": kao.url,
-        "protocol": kao.protocol,
-        "wrappedKey": kao.wrappedKey,
-        "policyBinding": _policy_binding(kao),
-    }
-    optional = {
-        "encryptedMetadata": kao.encryptedMetadata,
-        "kid": kao.kid,
-        "sid": kao.sid,
-        "ephemeralPublicKey": kao.ephemeralPublicKey,
-    }
-    value.update({k: v for k, v in optional.items() if v is not None})
-    return value
-
-
 def _rewrap_request_body(
     tdf_file: Path, session_public_key_pem: str
 ) -> tuple[str, str]:
     manifest = tdfs.manifest(tdf_file)
     kao = manifest.encryptionInformation.keyAccess[0]
+    # KeyAccessObject's Pydantic field names already match Connect-RPC's JSON
+    # shape for kas.proto's KeyAccess message; the extra tdf_spec_version
+    # field is ignored by the platform's lenient decoder.
     request_body = {
         "clientPublicKey": session_public_key_pem,
         "requests": [
@@ -279,7 +248,7 @@ def _rewrap_request_body(
                 "keyAccessObjects": [
                     {
                         "keyAccessObjectId": "kao-0",
-                        "keyAccessObject": _key_access_object(kao),
+                        "keyAccessObject": kao.model_dump(exclude_none=True),
                     }
                 ],
                 "policy": {
@@ -341,6 +310,10 @@ def _post_rewrap(
 
 def _assert_unauthorized(response: requests.Response) -> None:
     assert response.status_code == 401, response.text
+    # Confirm the rejection is actually a DPoP-related challenge so a 401
+    # from an unrelated misconfiguration doesn't silently "pass" the test.
+    auth = response.headers.get("WWW-Authenticate", "")
+    assert auth.startswith("DPoP"), f"expected DPoP challenge, got: {auth!r}"
 
 
 def _skip_unless_dpop_enabled(encrypt_sdk: tdfs.SDK, in_focus: set[tdfs.SDK]) -> None:
@@ -465,9 +438,13 @@ def test_dpop_rejects_tampered_proof_htu(
     ct_file = encrypted_tdf(encrypt_sdk, attr_values=attr.value_fqns)
     dpop_access = _get_dpop_access_token()
     rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
+    # Well-formed full URL pointing at a wrong path — exercises "tampered to
+    # a valid-shape but wrong endpoint" rather than "malformed string".
+    tampered_htu = rewrap_call.url.replace("/Rewrap", "/WrongRewrap")
+    assert tampered_htu != rewrap_call.url, "htu tamper must actually differ"
     proof = dpop_access.key.sign_dpop_proof(
         htm="POST",
-        htu="/kas.AccessService/WrongRewrap",
+        htu=tampered_htu,
         access_token=dpop_access.token,
     )
 
@@ -486,7 +463,9 @@ def test_dpop_rejects_replayed_jti(
     in_focus: set[tdfs.SDK],
     encrypted_tdf: EncryptFactory,
 ):
-    """Replaying the same DPoP proof `jti` MUST be rejected the second time."""
+    """Replaying a DPoP proof `jti` MUST be rejected — both as a byte-identical
+    replay and as a freshly signed proof reusing the known jti (RFC 9449 §11.1).
+    """
     _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
 
     attr, _ = attribute_single_kas_grant
@@ -494,11 +473,12 @@ def test_dpop_rejects_replayed_jti(
     dpop_access = _get_dpop_access_token()
     rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
 
+    replayed_jti = f"xtest-{secrets.token_urlsafe(16)}"
     proof = dpop_access.key.sign_dpop_proof(
         htm="POST",
-        htu=_rewrap_htu(),
+        htu=rewrap_call.url,
         access_token=dpop_access.token,
-        jti=f"xtest-{secrets.token_urlsafe(16)}",
+        jti=replayed_jti,
     )
     first = _post_rewrap(
         rewrap_call,
@@ -507,12 +487,13 @@ def test_dpop_rejects_replayed_jti(
     )
     nonce = first.headers.get("DPoP-Nonce")
     if first.status_code == 401 and nonce:
+        # KAS is enforcing nonces — retry once with the issued nonce.
         proof = dpop_access.key.sign_dpop_proof(
             htm="POST",
-            htu=_rewrap_htu(),
+            htu=rewrap_call.url,
             access_token=dpop_access.token,
             nonce=nonce,
-            jti=f"xtest-{secrets.token_urlsafe(16)}",
+            jti=replayed_jti,
         )
         first = _post_rewrap(
             rewrap_call,
@@ -522,22 +503,38 @@ def test_dpop_rejects_replayed_jti(
 
     assert first.status_code == 200, first.text
 
+    # 1. Byte-identical replay of the accepted proof.
     second = _post_rewrap(
         rewrap_call,
         access_token=dpop_access.token,
         dpop_proof=proof,
     )
-
     _assert_unauthorized(second)
 
+    # 2. Fresh proof reusing the same jti — the server must remember jti values
+    # across requests, not just deduplicate identical bytes.
+    fresh_proof_same_jti = dpop_access.key.sign_dpop_proof(
+        htm="POST",
+        htu=rewrap_call.url,
+        access_token=dpop_access.token,
+        nonce=nonce,
+        jti=replayed_jti,
+    )
+    third = _post_rewrap(
+        rewrap_call,
+        access_token=dpop_access.token,
+        dpop_proof=fresh_proof_same_jti,
+    )
+    _assert_unauthorized(third)
+
 
-def test_dpop_rejects_tampered_or_expired_nonce(
+def test_dpop_rejects_tampered_nonce(
     attribute_single_kas_grant: tuple[Attribute, list[str]],
     encrypt_sdk: tdfs.SDK,
     in_focus: set[tdfs.SDK],
     encrypted_tdf: EncryptFactory,
 ):
-    """When `require_nonce: true`, an unknown/tampered/expired nonce MUST 401 with a fresh DPoP-Nonce."""
+    """When `require_nonce: true`, a tampered nonce MUST 401 with a fresh DPoP-Nonce."""
     _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
 
     attr, _ = attribute_single_kas_grant
@@ -547,7 +544,7 @@ def test_dpop_rejects_tampered_or_expired_nonce(
 
     initial_proof = dpop_access.key.sign_dpop_proof(
         htm="POST",
-        htu=_rewrap_htu(),
+        htu=rewrap_call.url,
         access_token=dpop_access.token,
     )
     challenge = _post_rewrap(
@@ -561,7 +558,7 @@ def test_dpop_rejects_tampered_or_expired_nonce(
 
     tampered_proof = dpop_access.key.sign_dpop_proof(
         htm="POST",
-        htu=_rewrap_htu(),
+        htu=rewrap_call.url,
         access_token=dpop_access.token,
         nonce=f"tampered-{issued_nonce}",
     )

From b37d2ef682e4765965c0f85953b4beddda137c76 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 14:00:12 -0400
Subject: [PATCH 51/64] ci(DSPX-3397): include test_dpop.py in xtest workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Without this, test_dpop.py is collected nowhere in CI and the dormant
DPoP tests never even attempt to skip-or-run as each SDK lands its
`supports dpop` case. Add it alongside test_tdfs.py / test_policytypes.py
in both the all-SDK and focused-SDK invocations — the existing
sdk.skip_if_unsupported("dpop") gate keeps it inert on platforms/SDKs
that haven't shipped DPoP yet.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/workflows/xtest.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/xtest.yml b/.github/workflows/xtest.yml
index 8abb8c25d..23a7bcd63 100644
--- a/.github/workflows/xtest.yml
+++ b/.github/workflows/xtest.yml
@@ -529,7 +529,7 @@ jobs:
         if: ${{ env.FOCUS_SDK == 'all' }}
         run: |-
           skip_flag=$([[ "$SKIP_RELEASED_PAIRS" == "true" ]] && echo "--skip-released-pairs" || echo "")
-          uv run pytest -n auto --dist loadscope --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v $skip_flag test_tdfs.py test_policytypes.py
+          uv run pytest -n auto --dist loadscope --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v $skip_flag test_tdfs.py test_policytypes.py test_dpop.py
         working-directory: otdftests/xtest
         env:
           PLATFORM_DIR: "../../${{ steps.run-platform.outputs.platform-working-dir }}"
@@ -540,7 +540,7 @@ jobs:
         if: ${{ env.FOCUS_SDK != 'all' }}
         run: |-
           skip_flag=$([[ "$SKIP_RELEASED_PAIRS" == "true" ]] && echo "--skip-released-pairs" || echo "")
-          uv run pytest -n auto --dist loadscope --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v --focus "$FOCUS_SDK" $skip_flag test_tdfs.py test_policytypes.py
+          uv run pytest -n auto --dist loadscope --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v --focus "$FOCUS_SDK" $skip_flag test_tdfs.py test_policytypes.py test_dpop.py
         working-directory: otdftests/xtest
         env:
           PLATFORM_DIR: "../../${{ steps.run-platform.outputs.platform-working-dir }}"

From e9cc7137acafd5ac8b8de8f946ef51fca5de6478 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 14:46:46 -0400
Subject: [PATCH 52/64] fixup gitignore more tmps

---
 .gitignore | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index 6fa376ceb..0cb1afef1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,7 +12,6 @@ vulnerability/tilt_modules/
 
 /xtest/node_modules/
 /xtest/tilt_modules/
-/xtest/tmp/
 /xtest/sdk/js/web/dist/
 /xtest/.helm
 
@@ -31,11 +30,10 @@ xtest/sdk/java/cmdline.jar
 /xtest/sdk/go/platform-src/
 /xtest/otdfctl/
 
-/tmp/
+tmp/
 
 # Multi-instance test harness state (DSPX-3302). Per-instance config, logs, and
 # keys live under tests/instances/; otdf-sdk-mgr install scenario writes
 # .installed.json next to each scenarios.yaml.
 /instances/
 xtest/scenarios/*.installed.json
-.claude/tmp/

From f18df14b49b7cb38bebfc1d9f2670daa02dd5c4a Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 17:39:12 -0400
Subject: [PATCH 53/64] ci(DSPX-3397): move test_dpop.py to attribute-based
 test step
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

test_dpop.py uses the attribute_single_kas_grant fixture, which depends
on kas_entry_alpha (alpha KAS at port 8181). Alpha isn't started until
the additional-KAS block that runs before the "Run attribute based
configuration tests" step, so test_dpop.py in the standard-xtests step
would either fail to wire up the fixture or produce TDFs the test can't
roundtrip.

Move it from lines 531/542 (standard xtests) to line 646 (attribute
step) alongside test_abac.py / test_pqc.py — both of those also require
the additional KAS instances.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/workflows/xtest.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/xtest.yml b/.github/workflows/xtest.yml
index 23a7bcd63..ed59cb9d4 100644
--- a/.github/workflows/xtest.yml
+++ b/.github/workflows/xtest.yml
@@ -529,7 +529,7 @@ jobs:
         if: ${{ env.FOCUS_SDK == 'all' }}
         run: |-
           skip_flag=$([[ "$SKIP_RELEASED_PAIRS" == "true" ]] && echo "--skip-released-pairs" || echo "")
-          uv run pytest -n auto --dist loadscope --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v $skip_flag test_tdfs.py test_policytypes.py test_dpop.py
+          uv run pytest -n auto --dist loadscope --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v $skip_flag test_tdfs.py test_policytypes.py
         working-directory: otdftests/xtest
         env:
           PLATFORM_DIR: "../../${{ steps.run-platform.outputs.platform-working-dir }}"
@@ -540,7 +540,7 @@ jobs:
         if: ${{ env.FOCUS_SDK != 'all' }}
         run: |-
           skip_flag=$([[ "$SKIP_RELEASED_PAIRS" == "true" ]] && echo "--skip-released-pairs" || echo "")
-          uv run pytest -n auto --dist loadscope --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v --focus "$FOCUS_SDK" $skip_flag test_tdfs.py test_policytypes.py test_dpop.py
+          uv run pytest -n auto --dist loadscope --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v --focus "$FOCUS_SDK" $skip_flag test_tdfs.py test_policytypes.py
         working-directory: otdftests/xtest
         env:
           PLATFORM_DIR: "../../${{ steps.run-platform.outputs.platform-working-dir }}"
@@ -650,7 +650,7 @@ jobs:
             --sdks-encrypt "${ENCRYPT_SDK}" \
             --focus "$FOCUS_SDK" \
             $skip_flag \
-            test_abac.py test_pqc.py
+            test_abac.py test_pqc.py test_dpop.py
         working-directory: otdftests/xtest
         env:
           PLATFORM_DIR: "../../${{ steps.run-platform.outputs.platform-working-dir }}"

From 48b5f5c5e6db7bd6e440759ad388b695539bab8d Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 19:42:15 -0400
Subject: [PATCH 54/64] fixup: ruff format

---
 xtest/tdfs.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/xtest/tdfs.py b/xtest/tdfs.py
index 72177dd58..282d12c60 100644
--- a/xtest/tdfs.py
+++ b/xtest/tdfs.py
@@ -229,7 +229,11 @@ def __init__(self, **kwargs: dict[str, Any]):
                 self.features.add("mechanism-mlkem")
 
         # Pure ML-KEM-768 KEM support (FIPS 203 / CRYSTALS-Kyber-768)
-        if self.semver >= (0, 15, 0):  # version TBD — update when platform milestone is set
+        if self.semver >= (
+            0,
+            15,
+            0,
+        ):  # version TBD — update when platform milestone is set
             self.features.add("mechanism-mlkem")
 
         print(f"PLATFORM_VERSION '{v}' supports [{', '.join(self.features)}]")

From c9c65d30902abfc8a98e3da7ba2cd647c70c2e0e Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Mon, 8 Jun 2026 19:46:42 -0400
Subject: [PATCH 55/64] test(DSPX-3397): pin scenario to DSPX-3397 platform +
 matrix SDKs vs main
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Scenario was running against `main` everywhere — useless for end-to-end
verification of the DSPX-3397 work, since main has no DPoP support yet
and the scenario would skip the whole test_dpop.py suite.

- Platform + alpha KAS now pin to DSPX-3397-platform-service so the
  middleware under test is actually present.
- Each SDK is listed twice in encrypt and decrypt: once at `main`
  (compatibility — verifies the DPoP-validating platform still serves
  pre-DPoP clients; main pairs skip test_dpop.py via the supports gate
  but run the rest of the attribute step) and once at its DSPX-3397
  branch (happy path).
- Cross-SDK pairs (encrypt with one, decrypt with another) fall out of
  the encrypt/decrypt matrix.
- Refreshed `actual:` to point at the five open PRs.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 xtest/scenarios/DSPX-3397.yaml | 47 ++++++++++++++++++++++++----------
 1 file changed, 34 insertions(+), 13 deletions(-)

diff --git a/xtest/scenarios/DSPX-3397.yaml b/xtest/scenarios/DSPX-3397.yaml
index 645e1f2b1..f759a2d8d 100644
--- a/xtest/scenarios/DSPX-3397.yaml
+++ b/xtest/scenarios/DSPX-3397.yaml
@@ -9,29 +9,48 @@ instance:
     name: DSPX-3397
   platform:
     source:
-      ref: main
+      ref: DSPX-3397-platform-service
   ports:
     base: 8080
   kas:
     alpha:
       source:
-        ref: main
+        ref: DSPX-3397-platform-service
       mode: standard
 sdks:
+  # Each SDK is tested at both `main` (compatibility — verifies the
+  # DPoP-validating platform still serves pre-DPoP clients) and its
+  # DSPX-3397 branch (happy path — verifies the DPoP flow end-to-end).
+  # Cross-SDK pairs (encrypt with one, decrypt with another) fall out of
+  # the encrypt/decrypt matrix automatically.
   encrypt:
     - sdk: go
       version: main
+    - sdk: go
+      version: DSPX-3397-platform-go-sdk
+      source: platform
     - sdk: java
       version: main
+    - sdk: java
+      version: DSPX-3397-java-sdk
     - sdk: js
       version: main
+    - sdk: js
+      version: DSPX-3397-web-sdk
   decrypt:
     - sdk: go
       version: main
+    - sdk: go
+      version: DSPX-3397-platform-go-sdk
+      source: platform
     - sdk: java
       version: main
+    - sdk: java
+      version: DSPX-3397-java-sdk
     - sdk: js
       version: main
+    - sdk: js
+      version: DSPX-3397-web-sdk
 suite:
   targets:
     - xtest/test_dpop.py
@@ -46,15 +65,17 @@ expected: >-
   successfully. The server-issued nonce flow works end-to-end (first request
   returns 401 + DPoP-Nonce; SDK retries with the nonce claim; second request
   succeeds). Negative cases (Authorization: Bearer on a DPoP-bound token,
-  tampered htu, replayed jti, tampered/expired nonce) all return 401 with a
-  fresh DPoP-Nonce challenge.
+  tampered htu, replayed jti, tampered nonce) all return 401 with a fresh
+  DPoP-Nonce challenge. Pairs that include a `main`-version SDK on either
+  end skip the test_dpop suite via `sdk.skip_if_unsupported("dpop")` rather
+  than fail — main SDKs predate the supports-dpop gate.
 actual: >-
-  Feature not yet implemented end-to-end. The platform-service PR
-  (DSPX-3397-platform-service) is needed to wire DPoP validation + nonce
-  issuance into the KAS auth middleware. Each SDK cell PR
-  (DSPX-3397-{platform-go-sdk,java-sdk,web-sdk}) is needed to mint DPoP
-  proofs, set `Authorization: DPoP <token>`, and handle 401+DPoP-Nonce
-  retries. The tests-cell PR (DSPX-3397-kc26-dpop) is needed to bump
-  otdf-local to Keycloak 26 and to flesh out the direct-HTTP negative
-  cases. Until each SDK PR adds its `supports dpop` case to its cli.sh and
-  the platform PR exposes `pfs.supports("dpop")`, the suite skips uniformly.
+  In progress. Per-repo PRs are open: opentdf/tests#485 (this scenario +
+  draft tests + otdf-local KC26 bump), opentdf/platform#3582
+  (DSPX-3397-platform-service, DPoP middleware + server-issued nonce),
+  opentdf/platform#3581 (DSPX-3397-platform-go-sdk, http.RoundTripper
+  client), opentdf/java-sdk#374 (DSPX-3397-java-sdk, RS256 DPoP +
+  nonce cache; 401-retry deferred), opentdf/web-sdk#939
+  (DSPX-3397-web-sdk, dpop-nonce.ts + interceptor retry). Until each
+  PR's CI activates its `supports dpop` case in cli.sh, the
+  test_dpop.py lane skips uniformly.

From f7f2844365dc489932cf563ea0e1d2046e4380ef Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 9 Jun 2026 09:50:01 -0400
Subject: [PATCH 56/64] feat(xtest): add --require-features for red-green-red
 TDD on missing gates

PlatformFeatureSet.skip_if_unsupported currently always pytest.skip()s when a
feature isn't in the detected set. For features whose gate code (e.g. semver
detection) isn't wired up yet, that hides real client failures: every parametrization
silently skips, including ones whose SDK doesn't implement the feature at all.

Add --require-features (and matching XTEST_REQUIRE_FEATURES env var, and
suite.require_features in scenarios.yaml) that routes listed-but-missing
features through pytest.fail() instead. Use it during TDD on partially-landed
features to surface "client doesn't implement X" as a red signal, then flip back
to skip once the gate detection lands.

Plumbing:
- xtest/tdfs.py: new require_features set on PlatformFeatureSet; new
  is_feature_type TypeGuard; skip_if_unsupported routes via require_features.
- xtest/conftest.py: --require-features option (reuses is_type_or_list_of_types
  validator) + scenario.suite.require_features fallback + env-var bridge.
- otdf-sdk-mgr/schema.py: additive list[str] field on Suite.
- otdf-local/cli_scenario.py: _build_pytest_args forwards suite.require_features
  as --require-features.

Verified end-to-end against the running DSPX-3397 instance: baseline shows
SKIPPED; --require-features dpop and XTEST_REQUIRE_FEATURES=dpop both flip to
FAILED; --require-features dpopp is rejected at argparse; suite.require_features
in scenarios.yaml propagates correctly through otdf-local scenario run.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 otdf-local/src/otdf_local/cli_scenario.py |  2 ++
 otdf-sdk-mgr/src/otdf_sdk_mgr/schema.py   |  4 +++
 xtest/conftest.py                         | 15 ++++++++
 xtest/tdfs.py                             | 43 ++++++++++++++++++++---
 4 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/otdf-local/src/otdf_local/cli_scenario.py b/otdf-local/src/otdf_local/cli_scenario.py
index cbd9cb227..926d9b1d5 100644
--- a/otdf-local/src/otdf_local/cli_scenario.py
+++ b/otdf-local/src/otdf_local/cli_scenario.py
@@ -48,6 +48,8 @@ def _build_pytest_args(scenario: Scenario, scenario_path: Path) -> list[str]:
         args.extend(["-k", suite.kexpr])
     if suite.markers:
         args.extend(["-m", suite.markers])
+    if suite.require_features:
+        args.extend(["--require-features", " ".join(suite.require_features)])
     args.extend(suite.extra_args)
     return args
 
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/schema.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/schema.py
index 2c634b0a4..f775e5b77 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/schema.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/schema.py
@@ -202,6 +202,10 @@ class Suite(_StrictModel):
         description="Forwarded to --containers as a whitespace-separated list",
     )
     markers: str | None = Field(default=None, description="Forwarded to -m")
+    require_features: list[str] = Field(
+        default_factory=list,
+        description="Forwarded to --require-features; flips skip→fail for listed feature gates",
+    )
     extra_args: list[str] = Field(default_factory=list)
 
 
diff --git a/xtest/conftest.py b/xtest/conftest.py
index e4abd289c..49e71e118 100644
--- a/xtest/conftest.py
+++ b/xtest/conftest.py
@@ -138,6 +138,11 @@ def pytest_addoption(parser: pytest.Parser):
         help="select which sdks to run for encrypt only; accepts same format as --sdks",
         type=sdk_spec_type,
     )
+    parser.addoption(
+        "--require-features",
+        help=f"fail (instead of skip) when these platform features are missing; one or more of {englist(typing.get_args(tdfs.feature_type))}",
+        type=is_type_or_list_of_types(tdfs.feature_type),
+    )
 
 
 def pytest_configure(config: pytest.Config) -> None:
@@ -155,6 +160,13 @@ def pytest_configure(config: pytest.Config) -> None:
     if instance:
         os.environ["OTDF_LOCAL_INSTANCE_NAME"] = instance
 
+    # PlatformFeatureSet reads XTEST_REQUIRE_FEATURES at __init__; pytest
+    # options aren't visible from there. Mirror the CLI option to the env var
+    # before any code path can early-return below.
+    req = config.getoption("--require-features")
+    if req:
+        os.environ["XTEST_REQUIRE_FEATURES"] = req
+
     scenario_path = config.getoption("--scenario")
     if not scenario_path:
         return
@@ -188,6 +200,9 @@ def pytest_configure(config: pytest.Config) -> None:
             config.option.sdks_decrypt = " ".join(tokens["decrypt"])
     if not config.getoption("--containers") and scenario.suite.containers:
         config.option.containers = scenario.suite.containers
+    if not config.getoption("--require-features") and scenario.suite.require_features:
+        config.option.require_features = " ".join(scenario.suite.require_features)
+        os.environ["XTEST_REQUIRE_FEATURES"] = config.option.require_features
     if not instance and scenario.instance.metadata.name:
         os.environ["OTDF_LOCAL_INSTANCE_NAME"] = scenario.instance.metadata.name
 
diff --git a/xtest/tdfs.py b/xtest/tdfs.py
index 282d12c60..d72d16982 100644
--- a/xtest/tdfs.py
+++ b/xtest/tdfs.py
@@ -14,7 +14,7 @@
 
 import jsonschema
 import pytest
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 import assertions as tdfassertions
 
@@ -91,6 +91,10 @@ def is_sdk_type(val: str) -> TypeIs[sdk_type]:
     return val in get_args(sdk_type)
 
 
+def is_feature_type(val: str) -> "TypeIs[feature_type]":
+    return val in get_args(feature_type)
+
+
 focus_type = Literal[sdk_type, "all"]
 
 container_type = Literal[
@@ -151,6 +155,9 @@ class PlatformFeatureSet(BaseModel):
         "autoconfigure",
         "better-messages-2024",
     }
+    # Features whose absence routes through pytest.fail (not pytest.skip).
+    # Populated from --require-features / XTEST_REQUIRE_FEATURES.
+    require_features: set[feature_type] = Field(default_factory=set)
 
     def __init__(self, **kwargs: dict[str, Any]):
         super().__init__(**kwargs)
@@ -238,13 +245,39 @@ def __init__(self, **kwargs: dict[str, Any]):
 
         print(f"PLATFORM_VERSION '{v}' supports [{', '.join(self.features)}]")
 
+        req = os.getenv("XTEST_REQUIRE_FEATURES", "")
+        if req:
+            requested = [f for f in req.split() if f]
+            unknown = [f for f in requested if not is_feature_type(f)]
+            if unknown:
+                raise ValueError(
+                    f"XTEST_REQUIRE_FEATURES contains unknown features {unknown}; "
+                    f"valid features: {sorted(get_args(feature_type))}"
+                )
+            self.require_features = {f for f in requested if is_feature_type(f)}
+            print(
+                f"XTEST_REQUIRE_FEATURES forces [{', '.join(sorted(self.require_features))}]"
+            )
+
     def skip_if_unsupported(self, *features: feature_type):
-        """Skip the current test if any of the given features are unsupported."""
+        """Skip or fail the current test if any of the given features are unsupported.
+
+        Missing features in `require_features` trigger `pytest.fail` so the
+        author sees a real red signal during TDD. Other missing features still
+        `pytest.skip` — the historical behaviour for opt-in feature gates.
+        """
         missing = [f for f in features if f not in self.features]
-        if missing:
-            pytest.skip(
-                f"platform service {self.version} doesn't yet support {missing}"
+        if not missing:
+            return
+        required_missing = [f for f in missing if f in self.require_features]
+        if required_missing:
+            pytest.fail(
+                f"platform service {self.version} is missing required features "
+                f"{required_missing} (declared via --require-features / "
+                f"XTEST_REQUIRE_FEATURES); detected features: "
+                f"{sorted(self.features)}"
             )
+        pytest.skip(f"platform service {self.version} doesn't yet support {missing}")
 
 
 _cached_pfs: PlatformFeatureSet | None = None

From fc50d66d728b6a564bc96b743f28e5031f1a5413 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 9 Jun 2026 12:36:46 -0400
Subject: [PATCH 57/64] feat(xtest): wire dpop + dpop_nonce_challenge gates for
 the DSPX-3397 lane
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two platform feature gates are now probed via /.well-known/opentdf-configuration
instead of guessed by semver — branch builds report stale versions so the
well-known endpoint is the only honest source:
- dpop: presence of dpop_supported_alg_values
- dpop_nonce_challenge: dpop_nonce_required == true

cli.sh for go/java/js grow a `dpop | dpop_nonce_challenge` case that probes
`help encrypt` for the --dpop flag. Same probe covers both gates; nonce-mode
support reuses the same plumbing.

test_dpop.py's CLIENTID default flips to opentdf-dpop (the DPoP-bound
Keycloak client provisioned alongside the Bearer-only opentdf client).
test_dpop_server_issued_nonce_retry additionally gates on
dpop_nonce_challenge so it skips when only the base DPoP middleware is on.

Scenario DSPX-3397 now declares both features as required so the lane
fails (red bar) rather than skipping while per-repo PRs finish landing.

Also includes a one-line port of the otdf-local platform.py logger fix
(already on DSPX-3382-mlkem-scenarios; the warning block referenced a
missing self.logger attribute and broke `otdf-local up` for any
source-pinned instance).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../src/otdf_local/services/platform.py       | 11 ------
 xtest/scenarios/DSPX-3397.yaml                |  3 ++
 xtest/sdk/go/cli.sh                           |  8 ++++
 xtest/sdk/java/cli.sh                         |  4 ++
 xtest/sdk/js/cli.sh                           |  4 ++
 xtest/tdfs.py                                 | 39 ++++++++++++++++---
 xtest/test_dpop.py                            | 11 ++++--
 7 files changed, 59 insertions(+), 21 deletions(-)

diff --git a/otdf-local/src/otdf_local/services/platform.py b/otdf-local/src/otdf_local/services/platform.py
index 390f44b1d..66d61b820 100644
--- a/otdf-local/src/otdf_local/services/platform.py
+++ b/otdf-local/src/otdf_local/services/platform.py
@@ -149,17 +149,6 @@ def start(self) -> bool:
 
         # Build the command — pinned binary when an instance is loaded,
         # legacy `go run ./service` otherwise.
-        instance = self.settings.load_instance()
-        if instance and instance.platform.source:
-            self.logger.warning(
-                "instance uses platform.source; binary builds are ignored",
-                extra={
-                    "instance": instance.metadata.name or self.settings.instance,
-                    "ref": instance.platform.source.ref,
-                    "hint": "run 'otdf-sdk-mgr install scenario <instance.yaml>' to use built binary",
-                },
-            )
-
         instance_paths = self._instance_dist_paths()
         if instance_paths is not None:
             binary, worktree = instance_paths
diff --git a/xtest/scenarios/DSPX-3397.yaml b/xtest/scenarios/DSPX-3397.yaml
index f759a2d8d..2bd0083ec 100644
--- a/xtest/scenarios/DSPX-3397.yaml
+++ b/xtest/scenarios/DSPX-3397.yaml
@@ -56,6 +56,9 @@ suite:
     - xtest/test_dpop.py
   containers:
     - ztdf
+  require_features:
+    - dpop
+    - dpop_nonce_challenge
 expected: >-
   Against a Keycloak 26 realm whose OAuth client requires DPoP-bound access
   tokens (and with `services.kas.dpop.require_nonce: true` on the platform),
diff --git a/xtest/sdk/go/cli.sh b/xtest/sdk/go/cli.sh
index c245b7275..fff46231f 100755
--- a/xtest/sdk/go/cli.sh
+++ b/xtest/sdk/go/cli.sh
@@ -115,6 +115,14 @@ if [ "$1" == "supports" ]; then
       "${cmd[@]}" help policy kas-registry key create | grep -iE 'mlkem:768|mlkem:1024'
       exit $?
       ;;
+    dpop | dpop_nonce_challenge)
+      # DPoP support is signalled by the --dpop / --dpop-key flag on encrypt.
+      # The same probe covers nonce-challenge support: when nonce mode is
+      # required by the server, the SDK's existing 401-retry uses the same
+      # plumbing as the base DPoP path.
+      "${cmd[@]}" help encrypt | grep -iE -- '--dpop'
+      exit $?
+      ;;
     *)
       echo "Unknown feature: $2"
       exit 2
diff --git a/xtest/sdk/java/cli.sh b/xtest/sdk/java/cli.sh
index 46b755391..ea2bff1a4 100755
--- a/xtest/sdk/java/cli.sh
+++ b/xtest/sdk/java/cli.sh
@@ -107,6 +107,10 @@ if [ "$1" == "supports" ]; then
       java -jar "$SCRIPT_DIR"/cmdline.jar help encrypt | grep -i xwing
       exit $?
       ;;
+    dpop | dpop_nonce_challenge)
+      java -jar "$SCRIPT_DIR"/cmdline.jar help encrypt | grep -iE -- '--dpop'
+      exit $?
+      ;;
     *)
       echo "Unknown feature: $2"
       exit 2
diff --git a/xtest/sdk/js/cli.sh b/xtest/sdk/js/cli.sh
index 354596800..d1994e2ae 100755
--- a/xtest/sdk/js/cli.sh
+++ b/xtest/sdk/js/cli.sh
@@ -96,6 +96,10 @@ if [ "$1" == "supports" ]; then
       npx $CTL help | grep -i xwing
       exit $?
       ;;
+    dpop | dpop_nonce_challenge)
+      npx $CTL help encrypt | grep -iE -- '--dpop'
+      exit $?
+      ;;
     *)
       echo "Unknown feature: $2"
       exit 2
diff --git a/xtest/tdfs.py b/xtest/tdfs.py
index d72d16982..a65df58aa 100644
--- a/xtest/tdfs.py
+++ b/xtest/tdfs.py
@@ -63,6 +63,19 @@ def _algs_from_km1_log() -> set[str]:
     return algs
 
 
+def _fetch_well_known() -> dict[str, Any] | None:
+    """Fetch the platform's /.well-known/opentdf-configuration. Returns None on error."""
+    base = os.getenv("PLATFORMURL", "http://localhost:8080")
+    url = f"{base.rstrip('/')}/.well-known/opentdf-configuration"
+    try:
+        with urllib.request.urlopen(url, timeout=5) as resp:
+            if resp.status != 200:
+                return None
+            return json.loads(resp.read())
+    except Exception:
+        return None
+
+
 def _kas_supports_algorithm(algorithm: str) -> bool:
     """HTTP fallback: probe km1 KAS for a specific algorithm when log is unavailable."""
     # PQ managed keys live on km1, not the main platform KAS (KASURL/PLATFORMURL).
@@ -91,10 +104,6 @@ def is_sdk_type(val: str) -> TypeIs[sdk_type]:
     return val in get_args(sdk_type)
 
 
-def is_feature_type(val: str) -> "TypeIs[feature_type]":
-    return val in get_args(feature_type)
-
-
 focus_type = Literal[sdk_type, "all"]
 
 container_type = Literal[
@@ -113,9 +122,12 @@ def is_feature_type(val: str) -> "TypeIs[feature_type]":
     "connectrpc",
     # DPoP (RFC 9449): sender-constrained access tokens. SDK signs a DPoP proof
     # JWT per request; KAS validates the proof and binds the access token to
-    # the proof's JWK thumbprint (cnf.jkt). Includes server-issued DPoP-Nonce
-    # challenge flow (RFC 9449 §8) when the KAS is configured to require nonces.
+    # the proof's JWK thumbprint (cnf.jkt).
     "dpop",
+    # Server-issued DPoP-Nonce challenge flow (RFC 9449 §8). Gated separately
+    # because SDKs can support `dpop` without yet implementing the 401-retry
+    # required by nonce mode (e.g. java-sdk's deferred 401-retry).
+    "dpop_nonce_challenge",
     "ecwrap",
     "hexless",
     "hexaflexible",
@@ -140,6 +152,11 @@ def is_feature_type(val: str) -> "TypeIs[feature_type]":
     "obligations",
 ]
 
+
+def is_feature_type(val: str) -> TypeIs[feature_type]:
+    return val in get_args(feature_type)
+
+
 container_version = Literal["4.2.2", "4.3.0"]
 
 policy_type = Literal["plaintext", "encrypted"]
@@ -243,6 +260,16 @@ def __init__(self, **kwargs: dict[str, Any]):
         ):  # version TBD — update when platform milestone is set
             self.features.add("mechanism-mlkem")
 
+        # DPoP capabilities via well-known. Branch builds report stale semver
+        # so we probe the live endpoint instead of gating by version.
+        wk = _fetch_well_known()
+        if wk:
+            algs = wk.get("dpop_supported_alg_values")
+            if isinstance(algs, list) and algs:
+                self.features.add("dpop")
+            if wk.get("dpop_nonce_required") is True:
+                self.features.add("dpop_nonce_challenge")
+
         print(f"PLATFORM_VERSION '{v}' supports [{', '.join(self.features)}]")
 
         req = os.getenv("XTEST_REQUIRE_FEATURES", "")
diff --git a/xtest/test_dpop.py b/xtest/test_dpop.py
index 272a9d64d..fd15c399f 100644
--- a/xtest/test_dpop.py
+++ b/xtest/test_dpop.py
@@ -188,7 +188,10 @@ class RewrapCall:
 def _get_dpop_access_token() -> DPoPAccessToken:
     key = DPoPKey.generate()
     token_endpoint = _token_endpoint()
-    client_id = os.getenv("CLIENTID", "opentdf")
+    # The dpop-bound client is provisioned alongside the default `opentdf`
+    # client by `service provision keycloak`. We default to it here so tests
+    # that mint DPoP-bound tokens via Keycloak don't need extra env wiring.
+    client_id = os.getenv("CLIENTID", "opentdf-dpop")
     client_secret = os.getenv("CLIENTSECRET", "secret")
 
     def post_token(nonce: str | None = None) -> requests.Response:
@@ -380,9 +383,9 @@ def test_dpop_server_issued_nonce_retry(
     if not in_focus & {encrypt_sdk, decrypt_sdk}:
         pytest.skip("Not in focus")
     pfs = tdfs.get_platform_features()
-    pfs.skip_if_unsupported("dpop")
-    encrypt_sdk.skip_if_unsupported("dpop")
-    decrypt_sdk.skip_if_unsupported("dpop")
+    pfs.skip_if_unsupported("dpop", "dpop_nonce_challenge")
+    encrypt_sdk.skip_if_unsupported("dpop", "dpop_nonce_challenge")
+    decrypt_sdk.skip_if_unsupported("dpop", "dpop_nonce_challenge")
 
     attr, _ = attribute_single_kas_grant
     ct_file = encrypted_tdf(

From 3d58b9a73befad0f0ace1de4d78525fe081aa6bf Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 9 Jun 2026 19:58:31 -0400
Subject: [PATCH 58/64] fix(otdf-sdk-mgr): install scenario source-pin support
 + 3 path-resolution bugs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four targeted fixes that let `install scenario` actually refresh and rebuild
every artifact in a scenario that uses git-ref pins (branches, PR heads, SHAs).
Together they close the source-build path so the SDK matrix lights up the same
way the platform pin already did.

1. cli_scenario.py — pick install_release vs install_source per entry.
   The SDK loop unconditionally called `install_release(sdk, version)` and
   silently dropped any version that didn't resolve to a published artifact
   (the DSPX-3417 gap). Now mutable refs route through a new `install_source`
   helper that wraps `cmd_tip` and returns the dist path. Released semver
   versions stay on the existing download path. `entry.source` field is
   preserved as metadata for the go-from-platform vs go-from-otdfctl-repo
   disambiguation inside cmd_tip — not used as the routing switch since
   `is_mutable_ref` is the better signal.

2. cli_scenario.py — don't clobber Scenario YAMLs.
   The `source → dist` substitution dumped the inner Instance back over the
   path argument. For a Scenario YAML that wiped sdks/suite/expected/actual
   on every install. Gated the dump on `scenario is None` (only Instance-only
   YAMLs); installed.json already records the dist path for downstream
   tooling.

3. platform_installer.py — `_resolve_platform_ref` left branch names alone.
   `DSPX-3397-platform-service` was being treated as a release version and
   prefixed with `service/v`, producing `service/vDSPX-3397-platform-service`
   which git can't resolve. Only apply the infix when the input parses as
   semver (DSPX-3418 fix); plain branch names now pass through unchanged.

4. checkout.py — FETCH_HEAD across bare/worktree boundary.
   `checkout_go_from_platform` fetched into the bare repo then ran
   `git -C <worktree> checkout --force FETCH_HEAD`, but FETCH_HEAD lives in
   the bare's git dir and isn't visible from the worktree. Mirrors the
   pattern checkout_sdk_branch already uses for non-go SDKs: reset --hard
   to the named ref instead.

Verified end-to-end: `install scenario --skip-scripts
xtest/scenarios/DSPX-3397.yaml` (which mixes go from platform monorepo,
java/js from their own repos, all on branches) now builds 1 platform pin +
6 SDK pins and writes a complete installed.json — previously stopped at
the platform pin with empty SDK arrays.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py     |  6 +++-
 otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py | 22 ++++++++++++---
 otdf-sdk-mgr/src/otdf_sdk_mgr/installers.py   | 28 +++++++++++++++++--
 .../src/otdf_sdk_mgr/platform_installer.py    |  9 +++++-
 4 files changed, 56 insertions(+), 9 deletions(-)

diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py
index 9310d8ec9..9b0e402f9 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py
@@ -156,8 +156,12 @@ def checkout_go_from_platform(ref: str) -> Path:
     if worktree_path.exists():
         if is_mutable_ref(ref):
             print(f"Worktree for ref '{ref}' exists at {worktree_path}; resetting.")
+            # Fetch into the bare repo and then reset the worktree to the
+            # freshly-fetched ref. Using `FETCH_HEAD` here doesn't work because
+            # the fetch writes FETCH_HEAD into the bare's git dir, not the
+            # worktree's — git inside the worktree can't see it.
             _run(["git", f"--git-dir={bare_repo_path}", "fetch", "origin", ref, "--tags"])
-            _run(["git", "-C", str(worktree_path), "checkout", "--force", "FETCH_HEAD"])
+            _run(["git", "-C", str(worktree_path), "reset", "--hard", ref])
         else:
             print(f"Worktree for ref '{ref}' already exists at {worktree_path}; reusing.")
     else:
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py
index d8f26e276..dd6ade750 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/cli_scenario.py
@@ -17,7 +17,8 @@
 import typer
 from pydantic import ValidationError
 
-from otdf_sdk_mgr.installers import InstallError, install_release
+from otdf_sdk_mgr.installers import InstallError, install_release, install_source
+from otdf_sdk_mgr.refs import expand_pr_shorthand, is_mutable_ref
 from otdf_sdk_mgr.platform_installer import (
     PlatformInstallError,
     install_helper_scripts,
@@ -107,8 +108,12 @@ def _snapshot(status: str | None = None) -> dict[str, object]:
             install_helper_scripts()
 
         # Convert platform.source → platform.dist after successful build
-        # so otdf-local uses the built binary instead of falling back to go run
-        if instance.platform.source is not None:
+        # so otdf-local uses the built binary instead of falling back to go run.
+        # Only safe to dump when `path` IS an Instance YAML; for Scenario YAMLs
+        # the instance is inline and dumping just the instance clobbers the
+        # surrounding kind/sdks/suite/expected/actual blocks. installed.json
+        # already records the dist path for otdf-local to discover.
+        if scenario is None and instance.platform.source is not None:
             assert isinstance(installed_platform, dict)
             dist_name = Path(str(installed_platform["path"])).name
             typer.echo(f"  Updating instance to use platform dist: {dist_name}")
@@ -118,7 +123,16 @@ def _snapshot(status: str | None = None) -> dict[str, object]:
         if scenario is not None:
             install_paths: dict[tuple[str, str, str | None], str] = {}
             for entry in scenario.sdks.union():
-                dist_dir = install_release(entry.sdk, entry.version)
+                # Branches/PR-heads/SHAs go through the source-build path so
+                # the dist is rebuilt on every install (matching the platform
+                # source-pin behaviour). Semver release tags stay on the
+                # release download path. `entry.source` remains free-text
+                # metadata for the go-from-platform vs go-from-otdfctl-repo
+                # disambiguation inside cmd_tip — not a routing switch here.
+                if is_mutable_ref(expand_pr_shorthand(entry.version)):
+                    dist_dir = install_source(entry.sdk, entry.version)
+                else:
+                    dist_dir = install_release(entry.sdk, entry.version)
                 install_paths[entry.install_key()] = str(dist_dir)
             for role in ("encrypt", "decrypt"):
                 installed_sdks[role] = [
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/installers.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/installers.py
index d20fd3f3d..c7c6a81a2 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/installers.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/installers.py
@@ -206,6 +206,30 @@ def cmd_lts(sdks: list[str]) -> None:
         install_release(sdk, version)
 
 
+def _source_dist_slug(ref: str) -> str:
+    """Compute the dist-dir slug for a source build at `ref`.
+
+    Mirrors the per-SDK `local_name` calculation in checkout.py. Exported so
+    callers (e.g. `install_source`, `install_scenario`) can locate the dist
+    dir produced by a source build without re-running the build.
+    """
+    from otdf_sdk_mgr.refs import expand_pr_shorthand
+
+    expanded = expand_pr_shorthand(ref)
+    return expanded.replace("/", "--").removeprefix("sdk--").removeprefix("otdfctl--")
+
+
+def install_source(sdk: str, ref: str) -> Path:
+    """Source-build a single SDK at `ref` and return its dist directory.
+
+    Mirrors `install_release`'s signature for the source-build path so callers
+    can pick install path based on `source` pin without bespoke slug math.
+    Branch refs are re-fetched and rebuilt every call (see `is_mutable_ref`).
+    """
+    cmd_tip([sdk], ref=ref)
+    return get_sdk_dirs()[sdk] / "dist" / _source_dist_slug(ref)
+
+
 def cmd_tip(sdks: list[str], ref: str = "main") -> None:
     """Delegate to source checkout + make for source builds at `ref`.
 
@@ -220,9 +244,7 @@ def cmd_tip(sdks: list[str], ref: str = "main") -> None:
     from otdf_sdk_mgr.refs import expand_pr_shorthand
 
     expanded = expand_pr_shorthand(ref)
-    # Slug for SDK src/<slug> and dist/<slug> — mirrors the per-SDK
-    # `local_name` calculation in checkout.py.
-    slug = expanded.replace("/", "--").removeprefix("sdk--").removeprefix("otdfctl--")
+    slug = _source_dist_slug(ref)
 
     sdk_dirs = get_sdk_dirs()
     for sdk in sdks:
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/platform_installer.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/platform_installer.py
index 07afea73f..b2d3d9b5c 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/platform_installer.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/platform_installer.py
@@ -120,7 +120,14 @@ def _resolve_platform_ref(version_or_ref: str) -> str:
         return version_or_ref
     if 7 <= len(version_or_ref) <= 39 and _is_hex(version_or_ref):
         return version_or_ref
-    return f"{infix}/{normalize_version(version_or_ref)}"
+    # Only apply the `service/v…` infix when the input parses as semver. Plain
+    # branch names like `DSPX-3397-platform-service` pass through unchanged
+    # so `_ensure_worktree` can resolve them via the standard branch path.
+    from otdf_sdk_mgr.semver import parse_semver
+
+    if parse_semver(version_or_ref) is not None:
+        return f"{infix}/{normalize_version(version_or_ref)}"
+    return version_or_ref
 
 
 def _expand_short_sha(short: str) -> str:

From 1ff12909bb6ac71a541995da50dec89e3ea7e51a Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Tue, 9 Jun 2026 20:14:54 -0400
Subject: [PATCH 59/64] fix(otdf-sdk-mgr): detect and recover from corrupt bare
 clones and orphaned worktrees
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A Ctrl-C'd `git clone --bare` leaves a directory with `config`/`HEAD`/`objects`
but no `refs/`, and git rejects it as "not a git repository" forever after.
Probe with `rev-parse --is-bare-repository` before trusting an existing bare
clone; rm-rf and re-clone on failure.

Re-cloning the bare wipes per-worktree admin dirs at `<bare>/worktrees/<slug>/`,
which orphans any sibling worktree directories (their `.git` file points to a
missing admin location). `_ensure_worktree` / `_drop_orphaned_worktree` now
probe with `rev-parse --git-dir`; an orphan is rmtree'd and re-added rather
than failing on `git -C <worktree> reset --hard`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py     | 100 +++++++++++++-----
 .../src/otdf_sdk_mgr/platform_installer.py    |  37 ++++++-
 2 files changed, 108 insertions(+), 29 deletions(-)

diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py
index 9b0e402f9..de325bf24 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/checkout.py
@@ -28,6 +28,58 @@ def _run(cmd: list[str], **kwargs: Any) -> None:
         )
 
 
+def _ensure_clean_bare_repo(bare_repo_path: Path, repo_url: str) -> None:
+    """Clone the bare repo, replacing it if a previous attempt left it corrupt.
+
+    A Ctrl-C'd `git clone --bare` leaves a directory that has `config`/`HEAD`
+    but no `refs/`, which git rejects as "not a git repository" forever after.
+    Probe with `rev-parse --is-bare-repository` before trusting an existing
+    dir.
+    """
+    if bare_repo_path.exists():
+        probe = subprocess.run(
+            ["git", f"--git-dir={bare_repo_path}", "rev-parse", "--is-bare-repository"],
+            capture_output=True,
+            text=True,
+        )
+        if probe.returncode != 0 or probe.stdout.strip() != "true":
+            print(
+                f"Bare clone at {bare_repo_path} looks corrupt ({probe.stderr.strip()}); removing."
+            )
+            shutil.rmtree(bare_repo_path)
+    if not bare_repo_path.exists():
+        print(f"Cloning {repo_url} as a bare repository into {bare_repo_path}...")
+        _run(["git", "clone", "--bare", repo_url, str(bare_repo_path)])
+    else:
+        print(f"Bare repository already exists at {bare_repo_path}. Fetching updates...")
+        _run(["git", f"--git-dir={bare_repo_path}", "fetch", "--all", "--tags"])
+
+
+def _drop_orphaned_worktree(worktree_path: Path) -> bool:
+    """Remove a worktree dir whose admin metadata is gone.
+
+    Returns True if the dir was orphaned and removed (caller falls through to
+    re-add); False if the worktree is healthy and the caller should reuse it.
+    A bare-clone re-clone wipes the per-worktree admin dirs under
+    `<bare>/worktrees/<slug>/`, leaving sibling worktree dirs as ghosts whose
+    next `git -C` invocation dies with `fatal: not a git repository`.
+    """
+    if not worktree_path.exists():
+        return False
+    probe = subprocess.run(
+        ["git", "-C", str(worktree_path), "rev-parse", "--git-dir"],
+        capture_output=True,
+        text=True,
+    )
+    if probe.returncode != 0:
+        print(
+            f"Worktree at {worktree_path} is orphaned ({probe.stderr.strip()}); removing and re-adding."
+        )
+        shutil.rmtree(worktree_path)
+        return True
+    return False
+
+
 def checkout_sdk_branch(language: str, branch: str) -> str:
     """Clone bare repo and create/update a worktree for the given branch.
 
@@ -64,12 +116,7 @@ def checkout_sdk_branch(language: str, branch: str) -> str:
         local_name = local_name.removeprefix("sdk--")
     worktree_path = sdk_dir / "src" / local_name
 
-    if not bare_repo_path.exists():
-        print(f"Cloning {repo_url} as a bare repository into {bare_repo_path}...")
-        _run(["git", "clone", "--bare", repo_url, str(bare_repo_path)])
-    else:
-        print(f"Bare repository already exists at {bare_repo_path}. Fetching updates...")
-        _run(["git", f"--git-dir={bare_repo_path}", "fetch", "--all", "--tags"])
+    _ensure_clean_bare_repo(bare_repo_path, repo_url)
 
     # PR refs (`refs/pull/N/head`) aren't in the default bare-clone refspec;
     # fetch any explicit `refs/...` ref by name so worktree-add can find it.
@@ -85,7 +132,11 @@ def checkout_sdk_branch(language: str, branch: str) -> str:
             ]
         )
 
-    if worktree_path.exists():
+    # Orphaned worktrees (admin metadata gone after a bare re-clone) are
+    # rmtree'd here, so the worktree_path.exists() branch below sees a fresh
+    # slate and falls through to "add".
+    orphan_removed = _drop_orphaned_worktree(worktree_path)
+    if worktree_path.exists() and not orphan_removed:
         if is_mutable_ref(branch):
             print(f"Worktree exists at {worktree_path}; resetting to '{branch}'.")
             # Worktrees from a bare clone have no `origin` remote, so reset
@@ -94,18 +145,19 @@ def checkout_sdk_branch(language: str, branch: str) -> str:
             _run(["git", "-C", str(worktree_path), "reset", "--hard", "FETCH_HEAD"])
         else:
             print(f"Worktree for '{branch}' already exists at {worktree_path}; reusing.")
-    else:
-        print(f"Setting up worktree for branch '{branch}' at {worktree_path}...")
-        _run(
-            [
-                "git",
-                f"--git-dir={bare_repo_path}",
-                "worktree",
-                "add",
-                str(worktree_path),
-                branch,
-            ]
-        )
+        return local_name
+
+    print(f"Setting up worktree for branch '{branch}' at {worktree_path}...")
+    _run(
+        [
+            "git",
+            f"--git-dir={bare_repo_path}",
+            "worktree",
+            "add",
+            str(worktree_path),
+            branch,
+        ]
+    )
     return local_name
 
 
@@ -132,12 +184,7 @@ def checkout_go_from_platform(ref: str) -> Path:
 
     platform_src_dir.mkdir(parents=True, exist_ok=True)
 
-    if not bare_repo_path.exists():
-        print(f"Cloning {platform_url} as a bare repository into {bare_repo_path}...")
-        _run(["git", "clone", "--bare", platform_url, str(bare_repo_path)])
-    else:
-        print(f"Bare repository already exists at {bare_repo_path}. Fetching updates...")
-        _run(["git", f"--git-dir={bare_repo_path}", "fetch", "--all", "--tags"])
+    _ensure_clean_bare_repo(bare_repo_path, platform_url)
 
     # PR refs (`refs/pull/N/head`) aren't in the default bare-clone refspec;
     # fetch any explicit `refs/...` ref by name so worktree-add can find it.
@@ -153,7 +200,8 @@ def checkout_go_from_platform(ref: str) -> Path:
             ]
         )
 
-    if worktree_path.exists():
+    orphan_removed = _drop_orphaned_worktree(worktree_path)
+    if worktree_path.exists() and not orphan_removed:
         if is_mutable_ref(ref):
             print(f"Worktree for ref '{ref}' exists at {worktree_path}; resetting.")
             # Fetch into the bare repo and then reset the worktree to the
diff --git a/otdf-sdk-mgr/src/otdf_sdk_mgr/platform_installer.py b/otdf-sdk-mgr/src/otdf_sdk_mgr/platform_installer.py
index b2d3d9b5c..2b20e716e 100644
--- a/otdf-sdk-mgr/src/otdf_sdk_mgr/platform_installer.py
+++ b/otdf-sdk-mgr/src/otdf_sdk_mgr/platform_installer.py
@@ -78,9 +78,25 @@ def _run(cmd: list[str], cwd: Path | None = None) -> None:
 
 
 def _ensure_bare_repo() -> Path:
-    """Clone the platform bare repo if missing; fetch updates otherwise."""
+    """Clone the platform bare repo if missing or corrupt; fetch updates otherwise.
+
+    `bare.exists()` alone is too loose: a Ctrl-C'd `git clone --bare` leaves a
+    directory with `config`, `HEAD`, and `objects/` but no `refs/`, and git
+    rejects it as "not a git repository" on every subsequent operation. Probe
+    with `rev-parse --is-bare-repository` and re-clone on failure rather than
+    leaving the user to manually `rm -rf` the dist tree.
+    """
     bare = _platform_bare_repo()
     bare.parent.mkdir(parents=True, exist_ok=True)
+    if bare.exists():
+        probe = subprocess.run(
+            ["git", f"--git-dir={bare}", "rev-parse", "--is-bare-repository"],
+            capture_output=True,
+            text=True,
+        )
+        if probe.returncode != 0 or probe.stdout.strip() != "true":
+            print(f"Bare clone at {bare} looks corrupt ({probe.stderr.strip()}); removing.")
+            shutil.rmtree(bare)
     if not bare.exists():
         url = SDK_GIT_URLS["platform"].removesuffix(".git")
         print(f"Cloning {url} as a bare repository into {bare}...")
@@ -165,6 +181,10 @@ def _ensure_worktree(ref: str) -> Path:
     re-fetched, and we reset the worktree HEAD to the freshly-fetched ref so
     a subsequent install picks up new commits. For immutable refs (tags,
     SHAs) we just reuse.
+
+    An on-disk worktree dir whose `.git` file points to a missing admin
+    location (orphaned by a re-cloned bare repo) is removed and re-added
+    rather than re-used — git treats reuse as fatal.
     """
     bare = _ensure_bare_repo()
     # The bare clone's default refspec is `+refs/heads/*:refs/heads/*` plus
@@ -176,15 +196,26 @@ def _ensure_worktree(ref: str) -> Path:
         _run(["git", f"--git-dir={bare}", "fetch", "origin", f"+{ref}:{ref}"])
     worktree = _worktree_path_for(ref)
     if worktree.exists():
-        if is_mutable_ref(ref):
+        probe = subprocess.run(
+            ["git", "-C", str(worktree), "rev-parse", "--git-dir"],
+            capture_output=True,
+            text=True,
+        )
+        if probe.returncode != 0:
+            print(
+                f"Worktree at {worktree} is orphaned ({probe.stderr.strip()}); removing and re-adding."
+            )
+            shutil.rmtree(worktree)
+        elif is_mutable_ref(ref):
             print(f"Worktree exists at {worktree}; resetting to {ref}.")
             # Worktrees from a bare clone have no `origin` remote, so we
             # reset to the bare repo's just-fetched ref. Mirrors the
             # `install_helper_scripts` pattern below.
             _run(["git", "-C", str(worktree), "reset", "--hard", ref])
+            return worktree
         else:
             print(f"Worktree already exists at {worktree}; reusing.")
-        return worktree
+            return worktree
     print(f"Adding worktree at {worktree} for ref {ref}...")
     _run(["git", f"--git-dir={bare}", "worktree", "add", "--detach", str(worktree), ref])
     return worktree

From f2e898b04ad9483b30e1f8898ef504d7d20d97a0 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 08:24:13 -0400
Subject: [PATCH 60/64] fix(otdf-local): rewrite cryptoProvider key paths to
 absolute at config time
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Platform and KAS binaries both run with `cwd=<platform-worktree>`, but
both opentdf-dev.yaml and opentdf-kas-mode.yaml templates use relative
key paths (`kas-private.pem`, `./keys/kas-private.pem`) intended to
resolve under `instances/<id>/keys/`. The previous workaround was a
manual yq edit per instance — brittle, and broken across worktrees
because absolute paths from one tree leaked into the next.

`rewrite_crypto_keys_to_absolute` resolves each entry under
`server.cryptoProvider.standard.keys` against the instance keys dir and
drops entries whose backing file doesn't exist (e.g. PQC keys not
generated in the bootstrap bundle). Called from
`_provision_instance_dir` (platform config) and `_generate_config`
(per-KAS config).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 otdf-local/src/otdf_local/cli_instance.py | 12 +++++++
 otdf-local/src/otdf_local/services/kas.py | 15 ++++++++-
 otdf-local/src/otdf_local/utils/yaml.py   | 38 +++++++++++++++++++++++
 3 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/otdf-local/src/otdf_local/cli_instance.py b/otdf-local/src/otdf_local/cli_instance.py
index 2463d6a7a..3f301a218 100644
--- a/otdf-local/src/otdf_local/cli_instance.py
+++ b/otdf-local/src/otdf_local/cli_instance.py
@@ -171,6 +171,18 @@ def _provision_instance_dir(instance_dir: Path, instance: Instance) -> None:
         config_path,
         {"services.kas.root_key": generate_root_key()},
     )
+    # Rewrite cryptoProvider key paths against the instance's keys dir.
+    # The platform binary runs with cwd=<worktree>, so the template's
+    # relative paths can't resolve to instances/<id>/keys/.
+    from otdf_local.utils.yaml import (
+        load_yaml,
+        rewrite_crypto_keys_to_absolute,
+        save_yaml,
+    )
+
+    data = load_yaml(config_path)
+    rewrite_crypto_keys_to_absolute(data, keys_dir)
+    save_yaml(config_path, data)
 
 
 def _validate_port_uniqueness(instances_root: Path, new_name: str) -> None:
diff --git a/otdf-local/src/otdf_local/services/kas.py b/otdf-local/src/otdf_local/services/kas.py
index a4b616a63..620c161ca 100644
--- a/otdf-local/src/otdf_local/services/kas.py
+++ b/otdf-local/src/otdf_local/services/kas.py
@@ -12,7 +12,13 @@
     kill_process_on_port,
 )
 from otdf_local.services.base import Service, ServiceInfo, ServiceType
-from otdf_local.utils.yaml import copy_yaml_with_updates, get_nested, load_yaml
+from otdf_local.utils.yaml import (
+    copy_yaml_with_updates,
+    get_nested,
+    load_yaml,
+    rewrite_crypto_keys_to_absolute,
+    save_yaml,
+)
 
 
 class KASService(Service):
@@ -113,6 +119,13 @@ def _generate_config(self) -> Path:
             updates[f"services.kas.preview.{feature_key}"] = feature_val
 
         copy_yaml_with_updates(template_path, config_path, updates)
+        # KAS runs with cwd=<platform-worktree>, so the template's relative
+        # `kas-private.pem` paths can't resolve to instances/<id>/keys/.
+        # Resolve to absolute against the instance keys dir; drop entries
+        # whose backing files don't exist (e.g. PQC keys not provisioned).
+        data = load_yaml(config_path)
+        rewrite_crypto_keys_to_absolute(data, self.settings.instance_dir / "keys")
+        save_yaml(config_path, data)
         return config_path
 
     def start(self) -> bool:
diff --git a/otdf-local/src/otdf_local/utils/yaml.py b/otdf-local/src/otdf_local/utils/yaml.py
index a71653a4b..000ceb0f6 100644
--- a/otdf-local/src/otdf_local/utils/yaml.py
+++ b/otdf-local/src/otdf_local/utils/yaml.py
@@ -122,3 +122,41 @@ def copy_yaml_with_updates(source: Path, dest: Path, updates: dict[str, Any]) ->
     for dot_path, value in updates.items():
         set_nested(data, dot_path, value)
     save_yaml(dest, data)
+
+
+def rewrite_crypto_keys_to_absolute(data: dict[str, Any], keys_dir: Path) -> None:
+    """Rewrite relative `private`/`cert` paths under cryptoProvider.standard.keys to absolute.
+
+    Platform and KAS binaries both run with `cwd=<platform-worktree>` (the
+    Go source dir), not the instance dir, so the template's relative
+    `kas-private.pem` / `./keys/kas-private.pem` paths fail to open.
+    Resolve each entry against `keys_dir` (the instance's `keys/`); leave
+    absolute paths untouched. Entries whose target file isn't on disk are
+    dropped from the list so callers don't ship a broken keyring.
+    """
+    keys_list = get_nested(data, "server.cryptoProvider.standard.keys", None)
+    if not isinstance(keys_list, list):
+        return
+    surviving: list[Any] = []
+    for entry in keys_list:
+        if not isinstance(entry, dict):
+            surviving.append(entry)
+            continue
+        keep = True
+        for field in ("private", "cert"):
+            raw = entry.get(field)
+            if not isinstance(raw, str):
+                continue
+            candidate = Path(raw)
+            if not candidate.is_absolute():
+                # Strip a leading `./keys/` prefix so we don't end up with
+                # `<keys_dir>/keys/...`. Bare filenames pass through.
+                rel = Path(raw.removeprefix("./").removeprefix("keys/"))
+                candidate = keys_dir / rel.name
+            if not candidate.exists():
+                keep = False
+                break
+            entry[field] = str(candidate)
+        if keep:
+            surviving.append(entry)
+    set_nested(data, "server.cryptoProvider.standard.keys", surviving)

From 5c3545cef2f67a66ec7523c403241002d90a4684 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 08:51:29 -0400
Subject: [PATCH 61/64] fix(xtest): test_dpop fixture-shape + scenario target
 path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

attribute_single_kas_grant returns a bare Attribute, not the
(Attribute, list[str]) tuple the test annotated and unpacked. The
existing usages only need attr.value_fqns, so collapse the type
annotation and drop the tuple destructure across all 6 test methods.

scenarios/DSPX-3397.yaml: targets are passed verbatim to pytest with
cwd=xtest/, so write 'test_dpop.py' rather than 'xtest/test_dpop.py'
which gets joined to 'xtest/xtest/test_dpop.py' and fails collection.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 xtest/scenarios/DSPX-3397.yaml |  2 +-
 xtest/test_dpop.py             | 24 ++++++++++++------------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/xtest/scenarios/DSPX-3397.yaml b/xtest/scenarios/DSPX-3397.yaml
index 2bd0083ec..1d4172fe7 100644
--- a/xtest/scenarios/DSPX-3397.yaml
+++ b/xtest/scenarios/DSPX-3397.yaml
@@ -53,7 +53,7 @@ sdks:
       version: DSPX-3397-web-sdk
 suite:
   targets:
-    - xtest/test_dpop.py
+    - test_dpop.py
   containers:
     - ztdf
   require_features:
diff --git a/xtest/test_dpop.py b/xtest/test_dpop.py
index fd15c399f..f6c37dbf5 100644
--- a/xtest/test_dpop.py
+++ b/xtest/test_dpop.py
@@ -328,7 +328,7 @@ def _skip_unless_dpop_enabled(encrypt_sdk: tdfs.SDK, in_focus: set[tdfs.SDK]) ->
 
 
 def test_dpop_happy_path_roundtrip(
-    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    attribute_single_kas_grant: Attribute,
     encrypt_sdk: tdfs.SDK,
     decrypt_sdk: tdfs.SDK,
     pt_file: Path,
@@ -350,7 +350,7 @@ def test_dpop_happy_path_roundtrip(
     encrypt_sdk.skip_if_unsupported("dpop")
     decrypt_sdk.skip_if_unsupported("dpop")
 
-    attr, _ = attribute_single_kas_grant
+    attr = attribute_single_kas_grant
     ct_file = encrypted_tdf(
         encrypt_sdk,
         attr_values=attr.value_fqns,
@@ -362,7 +362,7 @@ def test_dpop_happy_path_roundtrip(
 
 
 def test_dpop_server_issued_nonce_retry(
-    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    attribute_single_kas_grant: Attribute,
     encrypt_sdk: tdfs.SDK,
     decrypt_sdk: tdfs.SDK,
     pt_file: Path,
@@ -387,7 +387,7 @@ def test_dpop_server_issued_nonce_retry(
     encrypt_sdk.skip_if_unsupported("dpop", "dpop_nonce_challenge")
     decrypt_sdk.skip_if_unsupported("dpop", "dpop_nonce_challenge")
 
-    attr, _ = attribute_single_kas_grant
+    attr = attribute_single_kas_grant
     ct_file = encrypted_tdf(
         encrypt_sdk,
         attr_values=attr.value_fqns,
@@ -399,7 +399,7 @@ def test_dpop_server_issued_nonce_retry(
 
 
 def test_dpop_rejects_bearer_scheme_on_dpop_token(
-    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    attribute_single_kas_grant: Attribute,
     encrypt_sdk: tdfs.SDK,
     in_focus: set[tdfs.SDK],
     encrypted_tdf: EncryptFactory,
@@ -413,7 +413,7 @@ def test_dpop_rejects_bearer_scheme_on_dpop_token(
     """
     _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
 
-    attr, _ = attribute_single_kas_grant
+    attr = attribute_single_kas_grant
     ct_file = encrypted_tdf(encrypt_sdk, attr_values=attr.value_fqns)
     dpop_access = _get_dpop_access_token()
     rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
@@ -429,7 +429,7 @@ def test_dpop_rejects_bearer_scheme_on_dpop_token(
 
 
 def test_dpop_rejects_tampered_proof_htu(
-    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    attribute_single_kas_grant: Attribute,
     encrypt_sdk: tdfs.SDK,
     in_focus: set[tdfs.SDK],
     encrypted_tdf: EncryptFactory,
@@ -437,7 +437,7 @@ def test_dpop_rejects_tampered_proof_htu(
     """A DPoP proof whose `htu` claim does not match the request URI MUST be rejected."""
     _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
 
-    attr, _ = attribute_single_kas_grant
+    attr = attribute_single_kas_grant
     ct_file = encrypted_tdf(encrypt_sdk, attr_values=attr.value_fqns)
     dpop_access = _get_dpop_access_token()
     rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
@@ -461,7 +461,7 @@ def test_dpop_rejects_tampered_proof_htu(
 
 
 def test_dpop_rejects_replayed_jti(
-    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    attribute_single_kas_grant: Attribute,
     encrypt_sdk: tdfs.SDK,
     in_focus: set[tdfs.SDK],
     encrypted_tdf: EncryptFactory,
@@ -471,7 +471,7 @@ def test_dpop_rejects_replayed_jti(
     """
     _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
 
-    attr, _ = attribute_single_kas_grant
+    attr = attribute_single_kas_grant
     ct_file = encrypted_tdf(encrypt_sdk, attr_values=attr.value_fqns)
     dpop_access = _get_dpop_access_token()
     rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
@@ -532,7 +532,7 @@ def test_dpop_rejects_replayed_jti(
 
 
 def test_dpop_rejects_tampered_nonce(
-    attribute_single_kas_grant: tuple[Attribute, list[str]],
+    attribute_single_kas_grant: Attribute,
     encrypt_sdk: tdfs.SDK,
     in_focus: set[tdfs.SDK],
     encrypted_tdf: EncryptFactory,
@@ -540,7 +540,7 @@ def test_dpop_rejects_tampered_nonce(
     """When `require_nonce: true`, a tampered nonce MUST 401 with a fresh DPoP-Nonce."""
     _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
 
-    attr, _ = attribute_single_kas_grant
+    attr = attribute_single_kas_grant
     ct_file = encrypted_tdf(encrypt_sdk, attr_values=attr.value_fqns)
     dpop_access = _get_dpop_access_token()
     rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)

From 6a0b89e43f5b5aade3a0c8e6a040a36e5aea80e8 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 09:41:28 -0400
Subject: [PATCH 62/64] fix(xtest): add otdf-sdk-mgr as editable dev dep so
 pyright resolves its imports

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 xtest/pyproject.toml |   4 ++
 xtest/uv.lock        | 106 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 110 insertions(+)

diff --git a/xtest/pyproject.toml b/xtest/pyproject.toml
index 8994e12b4..cd9c2e2d7 100644
--- a/xtest/pyproject.toml
+++ b/xtest/pyproject.toml
@@ -50,10 +50,14 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
+    "otdf-sdk-mgr",
     "pyright>=1.1.408",
     "ruff>=0.15.14",
 ]
 
+[tool.uv.sources]
+otdf-sdk-mgr = { path = "../otdf-sdk-mgr", editable = true }
+
 # Note: This is a test suite, not a distributable package.
 # Use `uv pip install -r pyproject.toml` or `uv sync` for dependencies.
 
diff --git a/xtest/uv.lock b/xtest/uv.lock
index 2616297bd..b8ca9bd9b 100644
--- a/xtest/uv.lock
+++ b/xtest/uv.lock
@@ -2,6 +2,15 @@ version = 1
 revision = 3
 requires-python = ">=3.14"
 
+[[package]]
+name = "annotated-doc"
+version = "0.0.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4", size = 7288, upload-time = "2025-11-10T22:07:42.062Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" },
+]
+
 [[package]]
 name = "annotated-types"
 version = "0.7.0"
@@ -277,6 +286,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
 ]
 
+[[package]]
+name = "markdown-it-py"
+version = "4.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mdurl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49", size = 82454, upload-time = "2026-05-07T12:08:28.36Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" },
+]
+
 [[package]]
 name = "markupsafe"
 version = "3.0.3"
@@ -307,6 +328,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/70/bc/6f1c2f612465f5fa89b95bead1f44dcb607670fd42891d8fdcd5d039f4f4/markupsafe-3.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa", size = 14146, upload-time = "2025-09-27T18:37:28.327Z" },
 ]
 
+[[package]]
+name = "mdurl"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
+]
+
 [[package]]
 name = "nodeenv"
 version = "1.10.0"
@@ -316,6 +346,34 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/88/b2/d0896bdcdc8d28a7fc5717c305f1a861c26e18c05047949fb371034d98bd/nodeenv-1.10.0-py2.py3-none-any.whl", hash = "sha256:5bb13e3eed2923615535339b3c620e76779af4cb4c6a90deccc9e36b274d3827", size = 23438, upload-time = "2025-12-20T14:08:52.782Z" },
 ]
 
+[[package]]
+name = "otdf-sdk-mgr"
+version = "0.1.0"
+source = { editable = "../otdf-sdk-mgr" }
+dependencies = [
+    { name = "gitpython" },
+    { name = "pydantic" },
+    { name = "rich" },
+    { name = "ruamel-yaml" },
+    { name = "typer" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "gitpython", specifier = ">=3.1.50" },
+    { name = "pydantic", specifier = ">=2.6.0" },
+    { name = "rich", specifier = ">=13.7.0" },
+    { name = "ruamel-yaml", specifier = ">=0.18.0" },
+    { name = "typer", specifier = ">=0.12.0" },
+]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "pyright", specifier = ">=1.1.408" },
+    { name = "pytest", specifier = ">=9.0.3" },
+    { name = "ruff", specifier = ">=0.15.14" },
+]
+
 [[package]]
 name = "packaging"
 version = "25.0"
@@ -504,6 +562,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a0/f4/c67b0b3f1b9245e8d266f0f112c500d50e5b4e83cb6f3b71b6528104182a/requests-2.34.2-py3-none-any.whl", hash = "sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0", size = 73075, upload-time = "2026-05-14T19:25:26.443Z" },
 ]
 
+[[package]]
+name = "rich"
+version = "15.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36", size = 230680, upload-time = "2026-04-12T08:24:00.75Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" },
+]
+
 [[package]]
 name = "rpds-py"
 version = "2026.5.1"
@@ -570,6 +641,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/79/cb/966040123eb102371559746908ef2c9471f4d43e17ec9a645a2258dab64b/rpds_py-2026.5.1-cp315-cp315t-win_amd64.whl", hash = "sha256:90bd6630002a1c7f09e7843dd79f0d24f3d2897cc25a753480917865d14f15b3", size = 225441, upload-time = "2026-05-28T12:01:51.408Z" },
 ]
 
+[[package]]
+name = "ruamel-yaml"
+version = "0.19.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/3b/ebda527b56beb90cb7652cb1c7e4f91f48649fbcd8d2eb2fb6e77cd3329b/ruamel_yaml-0.19.1.tar.gz", hash = "sha256:53eb66cd27849eff968ebf8f0bf61f46cdac2da1d1f3576dd4ccee9b25c31993", size = 142709, upload-time = "2026-01-02T16:50:31.84Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b8/0c/51f6841f1d84f404f92463fc2b1ba0da357ca1e3db6b7fbda26956c3b82a/ruamel_yaml-0.19.1-py3-none-any.whl", hash = "sha256:27592957fedf6e0b62f281e96effd28043345e0e66001f97683aa9a40c667c93", size = 118102, upload-time = "2026-01-02T16:50:29.201Z" },
+]
+
 [[package]]
 name = "ruff"
 version = "0.15.14"
@@ -595,6 +675,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/62/d5/bc97ff895ec35cf3925d4bd60f3b39d822f377a446906ec9bcc87405e59b/ruff-0.15.14-py3-none-win_arm64.whl", hash = "sha256:ff47b90a9ef6a40c9e2f3b479c1fb78531adf055b94c1eba0a7ba04b31951826", size = 11208607, upload-time = "2026-05-21T14:34:26.525Z" },
 ]
 
+[[package]]
+name = "shellingham"
+version = "1.5.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de", size = 10310, upload-time = "2023-10-24T04:13:40.426Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
+]
+
 [[package]]
 name = "smmap"
 version = "5.0.2"
@@ -604,6 +693,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/04/be/d09147ad1ec7934636ad912901c5fd7667e1c858e19d355237db0d0cd5e4/smmap-5.0.2-py3-none-any.whl", hash = "sha256:b30115f0def7d7531d22a0fb6502488d879e75b260a9db4d0819cfb25403af5e", size = 24303, upload-time = "2025-01-02T07:14:38.724Z" },
 ]
 
+[[package]]
+name = "typer"
+version = "0.26.7"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "rich" },
+    { name = "shellingham" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5e/ed/ef06584ccdd5c410df0837951ecd7e15d9a6144ea1bd4c73cecab1a89891/typer-0.26.7.tar.gz", hash = "sha256:e314a34c617e419c091b2830dda3ea1f257134ff593061a8f5b9717ab8dddb3a", size = 201709, upload-time = "2026-06-03T07:18:06.843Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/25/2201973529af2c954de0bb725323c3aaed6d7f0ceee8f550dec9185df013/typer-0.26.7-py3-none-any.whl", hash = "sha256:5c87cfbc5d34491c5346ebf49c23e18d56ccb863268d3a8d592b26087c2f5e58", size = 122456, upload-time = "2026-06-03T07:18:05.732Z" },
+]
+
 [[package]]
 name = "typing-extensions"
 version = "4.15.0"
@@ -675,6 +779,7 @@ dependencies = [
 
 [package.optional-dependencies]
 dev = [
+    { name = "otdf-sdk-mgr" },
     { name = "pyright" },
     { name = "ruff" },
 ]
@@ -697,6 +802,7 @@ requires-dist = [
     { name = "jsonschema", specifier = ">=4.25.1" },
     { name = "jsonschema-specifications", specifier = ">=2025.9.1" },
     { name = "markupsafe", specifier = ">=3.0.3" },
+    { name = "otdf-sdk-mgr", marker = "extra == 'dev'", editable = "../otdf-sdk-mgr" },
     { name = "packaging", specifier = ">=25.0" },
     { name = "pluggy", specifier = ">=1.6.0" },
     { name = "pycparser", specifier = ">=3.0" },

From 1828a92c571db9a931195fd8703df3ee7fd36f73 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Wed, 10 Jun 2026 10:11:41 -0400
Subject: [PATCH 63/64] fix(xtest): update dpop well-known field to
 dpop_signing_alg_values_supported

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 xtest/tdfs.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/xtest/tdfs.py b/xtest/tdfs.py
index a65df58aa..4c173cf14 100644
--- a/xtest/tdfs.py
+++ b/xtest/tdfs.py
@@ -264,7 +264,7 @@ def __init__(self, **kwargs: dict[str, Any]):
         # so we probe the live endpoint instead of gating by version.
         wk = _fetch_well_known()
         if wk:
-            algs = wk.get("dpop_supported_alg_values")
+            algs = wk.get("dpop_signing_alg_values_supported")
             if isinstance(algs, list) and algs:
                 self.features.add("dpop")
             if wk.get("dpop_nonce_required") is True:

From d4249249d913ae410789689cbc06300cc7a2fc68 Mon Sep 17 00:00:00 2001
From: Dave Mihalcik <dmihalcik@virtru.com>
Date: Thu, 11 Jun 2026 13:42:05 -0400
Subject: [PATCH 64/64] test(xtest): cover Bearer-vs-DPoP Authorization scheme
 drift
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces the wishful test_dpop_rejects_bearer_scheme_on_dpop_token (which
expected 401 with no DPoP proof, a different scenario) with one that
exercises the actual SDK-drift case: a DPoP-bound token presented under
Bearer scheme with a valid DPoP proof attached.

Current platform behavior is to accept the request (200) and emit a WARN
log per RFC 9449 §7.1. The test asserts both, plus a compliant DPoP-scheme
control. A TODO references DSPX-3573 for flipping to hard rejection once
all SDKs are compliant.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 xtest/test_dpop.py | 54 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 44 insertions(+), 10 deletions(-)

diff --git a/xtest/test_dpop.py b/xtest/test_dpop.py
index f6c37dbf5..56e2394af 100644
--- a/xtest/test_dpop.py
+++ b/xtest/test_dpop.py
@@ -33,6 +33,7 @@
 
 import tdfs
 from abac import Attribute
+from audit_logs import AuditLogAsserter
 from fixtures.encryption import EncryptFactory
 
 
@@ -398,18 +399,25 @@ def test_dpop_server_issued_nonce_retry(
     assert filecmp.cmp(pt_file, rt_file)
 
 
-def test_dpop_rejects_bearer_scheme_on_dpop_token(
+def test_dpop_bearer_scheme_warns_but_accepted_for_dpop_token(
     attribute_single_kas_grant: Attribute,
     encrypt_sdk: tdfs.SDK,
     in_focus: set[tdfs.SDK],
     encrypted_tdf: EncryptFactory,
+    audit_logs: AuditLogAsserter,
 ):
-    """A DPoP-bound access token presented with `Authorization: Bearer` MUST be rejected.
-
-    Plan:
-      1. Acquire a DPoP-bound access token (mint a proof for the token endpoint).
-      2. Hit KAS /rewrap with `Authorization: Bearer <token>` and no DPoP header.
-      3. Expect 401 (and a `WWW-Authenticate: DPoP error=\"invalid_token\"` challenge).
+    """A DPoP-bound access token presented with `Authorization: Bearer` is currently
+    accepted (provided a valid DPoP proof header is attached) but the platform emits
+    a WARN log to surface non-compliant SDK behavior. This is the SDK-drift scenario:
+    the proof is correct, only the Authorization scheme is wrong.
+
+    Per RFC 9449 §7.1 the request SHOULD be rejected with 401. The platform's WARN
+    is the deliberate intermediate state while SDKs are brought into compliance.
+
+    TODO(DSPX-3573): once all SDKs send the correct DPoP scheme, flip this test:
+      - drop the WARN assertion
+      - assert the Bearer-scheme call is rejected with 401 + WWW-Authenticate: DPoP
+      - rename to test_dpop_rejects_bearer_scheme_on_dpop_token
     """
     _skip_unless_dpop_enabled(encrypt_sdk, in_focus)
 
@@ -418,14 +426,40 @@ def test_dpop_rejects_bearer_scheme_on_dpop_token(
     dpop_access = _get_dpop_access_token()
     rewrap_call = _signed_rewrap_request(ct_file, dpop_access.key)
 
-    response = _post_rewrap(
+    bearer_proof = dpop_access.key.sign_dpop_proof(
+        htm="POST",
+        htu=rewrap_call.url,
+        access_token=dpop_access.token,
+    )
+    mark = audit_logs.mark("before_bearer_scheme_request")
+    bearer_response = _post_rewrap(
         rewrap_call,
         access_token=dpop_access.token,
-        dpop_proof=None,
+        dpop_proof=bearer_proof,
         auth_scheme="Bearer",
     )
 
-    _assert_unauthorized(response)
+    # Current (lenient) behavior: accepted. Will become 401 under DSPX-3573.
+    assert bearer_response.status_code == 200, bearer_response.text
+    audit_logs.assert_contains(
+        r"DPoP-bound access token presented under Bearer Authorization scheme",
+        since_mark=mark,
+    )
+
+    # Compliant path control: same proof key, same token, just the right scheme.
+    # Distinct jti via fresh proof so the server's replay cache doesn't reject it.
+    dpop_proof = dpop_access.key.sign_dpop_proof(
+        htm="POST",
+        htu=rewrap_call.url,
+        access_token=dpop_access.token,
+    )
+    dpop_response = _post_rewrap(
+        rewrap_call,
+        access_token=dpop_access.token,
+        dpop_proof=dpop_proof,
+        auth_scheme="DPoP",
+    )
+    assert dpop_response.status_code == 200, dpop_response.text
 
 
 def test_dpop_rejects_tampered_proof_htu(