pactkit 3.1.0__tar.gz → 4.0.0__tar.gz

{pactkit-3.1.0 → pactkit-4.0.0}/.secrets.baseline

@@ -136,15 +136,6 @@
         "line_number": 65
       }
     ],
-    "docs/architecture/graphs/class_graph.mmd": [
-      {
-        "type": "Base64 High Entropy String",
-        "filename": "docs/architecture/graphs/class_graph.mmd",
-        "hashed_secret": "1f4fddb18c4bc3feeb76c3fde85134e2991e0b7e",
-        "is_verified": false,
-        "line_number": 252
-      }
-    ],
     "docs/specs/STORY-slim-20260828897396a935ab.md": [
       {
         "type": "AWS Access Key",
@@ -190,17 +181,10 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
-        "hashed_secret": "9977ec0af474652a0718f59cda74ebd52dabf867",
+        "hashed_secret": "a5994eaed0a6069e4e858cece615943d4d851db5",
         "is_verified": false,
         "line_number": 7
       },
-      {
-        "type": "Hex High Entropy String",
-        "filename": "tests/fixtures/host_artifact_paths.json",
-        "hashed_secret": "0de79e48b3f9c3eee896340dc93579c8967365ed",
-        "is_verified": false,
-        "line_number": 8
-      },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
@@ -750,7 +734,7 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
-        "hashed_secret": "c8db1cd10e7154d247dcccccff9bd5f663ae0850",
+        "hashed_secret": "86bc90e8b5cf7fd911df5eb91a3ea18fef34da3b",
         "is_verified": false,
         "line_number": 380
       },
@@ -894,13 +878,6 @@
         "is_verified": false,
         "line_number": 453
       },
-      {
-        "type": "Hex High Entropy String",
-        "filename": "tests/fixtures/host_artifact_paths.json",
-        "hashed_secret": "26e2cbb16c8c25e58b339cb24cdf45220684093d",
-        "is_verified": false,
-        "line_number": 454
-      },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
@@ -981,7 +958,7 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
-        "hashed_secret": "08c72ddf82a1b305944879f9c85a26156b7d0752",
+        "hashed_secret": "13d57d1a3632c09ba09725607afee063cb16eac6",
         "is_verified": false,
         "line_number": 552
       },
@@ -1097,6 +1074,13 @@
         "is_verified": false,
         "line_number": 583
       },
+      {
+        "type": "Hex High Entropy String",
+        "filename": "tests/fixtures/host_artifact_paths.json",
+        "hashed_secret": "fec022c577e244da45c84829c4aed6697cda7a24",
+        "is_verified": false,
+        "line_number": 635
+      },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
@@ -1263,21 +1247,21 @@
         "filename": "tests/fixtures/host_artifact_paths.json",
         "hashed_secret": "2ddcea7c868c0d35d028d1a70dc96c669f7a70f8",
         "is_verified": false,
-        "line_number": 721
+        "line_number": 722
       }
     ],
     "tests/fixtures/host_prompt_snapshots/classic.json": [
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/classic.json",
-        "hashed_secret": "c510a961f03bd3a362b5778aaac4871f9205ac9e",
+        "hashed_secret": "9eb8e7de843e2cf429d9119be0f9c66a93c38d15",
         "is_verified": false,
         "line_number": 91
       },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/classic.json",
-        "hashed_secret": "abafaa9fc05b3c1f88bbfdb63adce8bf932bd23a",
+        "hashed_secret": "68dc070c5fe5a6c51fd1dd7dcf577fccb523975e",
         "is_verified": false,
         "line_number": 92
       },
@@ -1867,14 +1851,14 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/codex.json",
-        "hashed_secret": "d4f538dca3b066dd8e62810515e213bb0bab48fe",
+        "hashed_secret": "da3a5039feb882c27805f5ab2c98e8748b2031ff",
         "is_verified": false,
         "line_number": 77
       },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/codex.json",
-        "hashed_secret": "1cb2b3d87efc40f51ae2548a6133c26870f724ce",
+        "hashed_secret": "485c59fbcae2d2df77377c54cce51c10fdbd2240",
         "is_verified": false,
         "line_number": 78
       },
@@ -2310,14 +2294,14 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/opencode.json",
-        "hashed_secret": "f0df417a2b434474c55161005ccd65d1ac1f4b56",
+        "hashed_secret": "58a9b55e813b7490985b28f43a3d3a81fac8df6a",
         "is_verified": false,
         "line_number": 89
       },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/opencode.json",
-        "hashed_secret": "a1d77e54caeeac3055373aab307bd02736d97952",
+        "hashed_secret": "c96cd1968d51ffb12bc6976ff3ab4cbbd9a8ef4f",
         "is_verified": false,
         "line_number": 90
       },
@@ -3016,5 +3000,5 @@
       }
     ]
   },
-  "generated_at": "2026-09-26T07:14:50Z"
+  "generated_at": "2026-09-26T13:03:05Z"
 }

{pactkit-3.1.0 → pactkit-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pactkit
-Version: 3.1.0
+Version: 4.0.0
 Summary: Spec-driven agentic DevOps toolkit for AI coding assistants
 Project-URL: Homepage, https://pactkit.dev
 Project-URL: Repository, https://github.com/pactkit/pactkit-public
@@ -25,19 +25,19 @@ Requires-Dist: detect-secrets>=1.5.0
 Requires-Dist: pre-commit>=4.6.1
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: all
-Requires-Dist: pactkit-codex<3.2.0,>=3.1.0; extra == 'all'
-Requires-Dist: pactkit-opencode<3.2.0,>=3.1.0; extra == 'all'
+Requires-Dist: pactkit-codex<4.1.0,>=4.0.0; extra == 'all'
+Requires-Dist: pactkit-opencode<4.1.0,>=4.0.0; extra == 'all'
 Requires-Dist: ruff>=0.4; extra == 'all'
 Requires-Dist: tree-sitter-go>=0.25; extra == 'all'
 Requires-Dist: tree-sitter-java>=0.23; extra == 'all'
 Requires-Dist: tree-sitter-typescript>=0.23; extra == 'all'
 Requires-Dist: tree-sitter>=0.25; extra == 'all'
 Provides-Extra: codex
-Requires-Dist: pactkit-codex<3.2.0,>=3.1.0; extra == 'codex'
+Requires-Dist: pactkit-codex<4.1.0,>=4.0.0; extra == 'codex'
 Provides-Extra: lint
 Requires-Dist: ruff>=0.4; extra == 'lint'
 Provides-Extra: opencode
-Requires-Dist: pactkit-opencode<3.2.0,>=3.1.0; extra == 'opencode'
+Requires-Dist: pactkit-opencode<4.1.0,>=4.0.0; extra == 'opencode'
 Provides-Extra: test
 Requires-Dist: pytest>=7; extra == 'test'
 Requires-Dist: tomli>=1.1.0; (python_version < '3.11') and extra == 'test'

{pactkit-3.1.0 → pactkit-4.0.0}/SECURITY.md

@@ -4,10 +4,10 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 4.0.x   | :white_check_mark: |
 | 3.1.x   | :white_check_mark: |
 | 3.0.x   | :white_check_mark: |
-| 2.27.x  | :white_check_mark: |
-| < 2.27  | :x:                |
+| < 3.0   | :x:                |
 
 We provide security fixes for the current and previous minor release. Users on
 older versions should upgrade — the version is reported by `pactkit version`,

{pactkit-3.1.0 → pactkit-4.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pactkit"
-version = "3.1.0"
+version = "4.0.0"
 description = "Spec-driven agentic DevOps toolkit for AI coding assistants"
 readme = "README.md"
 license = "MIT"
@@ -75,8 +75,8 @@ Issues = "https://github.com/pactkit/pactkit-public/issues"
 pactkit = "pactkit.cli:main"
 
 [project.optional-dependencies]
-opencode = ["pactkit-opencode>=3.1.0,<3.2.0"]
-codex = ["pactkit-codex>=3.1.0,<3.2.0"]
+opencode = ["pactkit-opencode>=4.0.0,<4.1.0"]
+codex = ["pactkit-codex>=4.0.0,<4.1.0"]
 visualize = [
     "tree-sitter>=0.25",
     "tree-sitter-go>=0.25",

{pactkit-3.1.0 → pactkit-4.0.0}/src/pactkit/__init__.py

@@ -1,3 +1,3 @@
 """PactKit - Spec-driven agentic DevOps toolkit."""
 
-__version__ = "3.1.0"
+__version__ = "4.0.0"

{pactkit-3.1.0 → pactkit-4.0.0}/src/pactkit/config.py

@@ -922,10 +922,32 @@ def config_label_for(project_root: Path | str) -> str:
 
 
 def resolve_pactkit_yaml_dir(cwd: Path | None = None, format: str | None = None) -> Path:
-    """Determine where to write pactkit.yaml based on environment (STORY-072 R2, STORY-slim-005 R6).
-
-    When format is explicitly provided, derives path from FormatProfile (no hardcoded branches).
-    When format is None, returns the first existing candidate path, defaulting to classic.
+    """Where a NEW pactkit.yaml is written for `format` (STORY-072 R2, STORY-slim-005 R6).
+
+    **This is a write path.** Reading resolves through
+    :func:`find_pactkit_yaml_layers` — the shared project policy plus the host
+    layer — and never calls this. Both production callers write
+    (`_generate_config_if_missing` and `project_contract.py`).
+
+    **Step 8 R-③-3 / AC-③-2 — the guessing fallback is deleted** (owner
+    2026-09-26). `format=None` used to be answered by guessing: first "which
+    candidate file already exists", then "which candidate's parent directory
+    happens to exist". Both made the write target a fact about the filesystem
+    rather than about the Host being deployed, and they disagreed with the
+    reader's own order — `PACTKIT_YAML_CANDIDATES` puts `opencode` first while
+    `pactkit_yaml_candidates(host)` puts `classic` first. Measured 2026-09-26:
+
+        mkdir .opencode && pactkit init --format classic
+        → .opencode/pactkit.yaml, containing CLASSIC's config
+
+    The rule now: **reading may discover existing layers; writing must know
+    which format it is writing for.** A caller naming no format gets the classic
+    Host's path — a fixed, documented default rather than a guess, and one no
+    directory can change. Every production caller passes `format` explicitly.
+
+    `detect_host_format()` was the other candidate and was rejected on purpose:
+    it swaps a directory guess for an environment guess, and still lets a writer
+    resolve a target without knowing whose config it is producing.
     """
     if cwd is None:
         cwd = Path.cwd()
@@ -934,17 +956,7 @@ def resolve_pactkit_yaml_dir(cwd: Path | None = None, format: str | None = None)
     if format and is_environment_format(format):
         return cwd / get_profile(format).pactkit_yaml_path
 
-    # Auto-detect: first check for existing yaml files, then fall back to dir existence
-    for candidate in PACTKIT_YAML_CANDIDATES:
-        if (cwd / candidate).exists():
-            return cwd / candidate
-    # Dir-existence fallback (when yaml not yet created — e.g. first-time init)
-    for candidate in PACTKIT_YAML_CANDIDATES:
-        parent_dir = (cwd / candidate).parent
-        if parent_dir.is_dir():
-            return cwd / candidate
-
-    # Default fallback: classic
+    # No format: classic's path. Deterministic — NOT "whichever directory exists".
     return cwd / get_profile("classic").pactkit_yaml_path
 
 

{pactkit-3.1.0 → pactkit-4.0.0}/src/pactkit/generators/deployer.py

@@ -631,8 +631,18 @@ def _deploy_classic(
     )
     _deploy_ci(ci_provider, project_root, config)
 
-    # Generate pactkit.yaml at project-level if it doesn't exist (BUG-013)
-    _generate_config_if_missing(project_root=project_root)
+    # Generate pactkit.yaml at project-level if it doesn't exist (BUG-013).
+    #
+    # `format="classic"` is not decoration (SPEC-4.0-22 Step 8 R-③-2). Without
+    # it the path falls to `resolve_pactkit_yaml_dir`'s directory-existence
+    # fallback, which picks the first candidate whose PARENT DIRECTORY happens
+    # to exist — so a project carrying a `.opencode/` directory got CLASSIC's
+    # config written into `.opencode/pactkit.yaml`. Measured 2026-09-26:
+    # `mkdir .opencode && pactkit init --format classic` produced exactly that.
+    # The contract already exists in this repo (`prompts/rules.py`: "writes to
+    # the format-specific directory only. Never cross-write.") — this call site
+    # was the one place not honouring it.
+    _generate_config_if_missing(format="classic", project_root=project_root)
 
     # Generate project-level CLAUDE.md (always regenerate) and CLAUDE.local.md (if missing) (STORY-040)
     # Skip when target is specified (preview mode) to avoid modifying real project

{pactkit-3.1.0 → pactkit-4.0.0}/tests/fixtures/host_artifact_paths.json

@@ -4,8 +4,8 @@
     "all": {
       "digests": {
         "project/.claude/pactkit.yaml": "6ee8aab66c3587f8",
-        "target/.pactkit-version": "b2f44d3b6e29f8b1",
-        "target/CLAUDE.md": "6ba148472d4f04e9",
+        "target/.pactkit-version": "e1d49c569ae09b2e",
+        "target/CLAUDE.md": "8e676a68e64e031e",
         "target/agents/code-explorer.md": "c2e7f592fda4c272",
         "target/agents/product-designer.md": "5b5ae0ff96a094ea",
         "target/agents/qa-engineer.md": "487a69e0a2331209",
@@ -187,8 +187,8 @@
     },
     "classic": {
       "digests": {
-        "home/.claude/.pactkit-version": "b2f44d3b6e29f8b1",
-        "home/.claude/CLAUDE.md": "6ba148472d4f04e9",
+        "home/.claude/.pactkit-version": "e1d49c569ae09b2e",
+        "home/.claude/CLAUDE.md": "8e676a68e64e031e",
         "home/.claude/agents/code-explorer.md": "c2e7f592fda4c272",
         "home/.claude/agents/product-designer.md": "5b5ae0ff96a094ea",
         "home/.claude/agents/qa-engineer.md": "487a69e0a2331209",
@@ -376,8 +376,8 @@
     },
     "codex": {
       "digests": {
-        "home/.codex/.pactkit-version": "b2f44d3b6e29f8b1",
-        "home/.codex/AGENTS.md": "90c3c457f26096d7",
+        "home/.codex/.pactkit-version": "e1d49c569ae09b2e",
+        "home/.codex/AGENTS.md": "c524754b87591eca",
         "home/.codex/rules/pactkit-runtime.md": "fd8a852e8b6d8dc7",
         "home/.codex/skills/.pactkit-command-manifest.json": "ba46031e64fdcf77",
         "home/.codex/skills/pactkit-analyze/SKILL.md": "61e170f41ac10860",
@@ -451,7 +451,7 @@
         "project/.codex/.hooks.json.lock": "e3b0c44298fc1c14",
         "project/.codex/AGENTS.local.md": "60600be9ba3e6fe1",
         "project/.codex/hooks.json": "c3a75d34fc73a31e",
-        "project/.codex/pactkit.yaml": "2a7057e488d00799",
+        "project/.codex/pactkit.yaml": "6ee8aab66c3587f8",
         "project/AGENTS.md": "c0b3df85845575ba"
       },
       "paths": [
@@ -538,7 +538,7 @@
     "copilot": {
       "digests": {
         "project/.github/.pactkit-copilot-ownership.json": "6a79493891ae2910",
-        "project/.github/.pactkit-version": "b2f44d3b6e29f8b1",
+        "project/.github/.pactkit-version": "e1d49c569ae09b2e",
         "project/.github/agents/code-explorer.md": "470c09d6dc253467",
         "project/.github/agents/product-designer.md": "a67877a4f729a5e1",
         "project/.github/agents/qa-engineer.md": "bbefe7981ee1e665",
@@ -549,8 +549,8 @@
         "project/.github/agents/system-medic.md": "5771158127a9163b",
         "project/.github/agents/visual-architect.md": "374dc8ddf8d55af9",
         "project/.github/copilot-instructions.local.md": "d2e16afa69faeb7e",
-        "project/.github/copilot-instructions.md": "571e5a570463a8a7",
-        "project/.github/pactkit.yaml": "2a7057e488d00799",
+        "project/.github/copilot-instructions.md": "6fa905fd85fbe5ea",
+        "project/.github/pactkit.yaml": "6ee8aab66c3587f8",
         "project/.github/prompts/project-act.prompt.md": "34eca00872d85c38",
         "project/.github/prompts/project-check.prompt.md": "afb451a6f4603dae",
         "project/.github/prompts/project-clarify.prompt.md": "d76915550014d45f",
@@ -632,7 +632,7 @@
     },
     "opencode": {
       "digests": {
-        "home/.config/opencode/AGENTS.md": "f1b9ff9e60f5f8f3",
+        "home/.config/opencode/AGENTS.md": "bc9777f2d1da4ee0",
         "home/.config/opencode/agents/code-explorer.md": "37f70e6591298036",
         "home/.config/opencode/agents/product-designer.md": "4787453ddfbe4dd8",
         "home/.config/opencode/agents/qa-engineer.md": "a762da03d68820e9",
@@ -718,6 +718,7 @@
         "home/.config/opencode/skills/pactkit-trace/SKILL.md": "e48f67cade85c08c",
         "home/.config/opencode/skills/pactkit-visualize/SKILL.md": "d7358a1a482c1690",
         "home/.config/opencode/skills/pactkit-visualize/scripts/visualize.py": "edb663b28aceab91",
+        "project/.opencode/pactkit.yaml": "6ee8aab66c3587f8",
         "project/AGENTS.md": "ca1b44d2c69f4309"
       },
       "paths": [
@@ -808,6 +809,7 @@
         "home/.config/opencode/skills/pactkit-trace/SKILL.md",
         "home/.config/opencode/skills/pactkit-visualize/SKILL.md",
         "home/.config/opencode/skills/pactkit-visualize/scripts/visualize.py",
+        "project/.opencode/pactkit.yaml",
         "project/AGENTS.md"
       ]
     }

{pactkit-3.1.0 → pactkit-4.0.0}/tests/fixtures/host_prompt_snapshots/classic.json

@@ -88,8 +88,8 @@
     "project/.claude/settings.json"
   ],
   "body_digests": {
-    "home/.claude/.pactkit-deployed.json": "7fab568a47ad4fe4df1236b295e15f9e174f50efad551a9c17b7aae951a1bd42",
-    "home/.claude/CLAUDE.md": "6ba148472d4f04e9c6e93265be1ad4a87a6612d038c03f867f8f76c08de07ec1",
+    "home/.claude/.pactkit-deployed.json": "9376d4c653de1139744b144589c98751478d22d3948cbfe2a014159f10814f6c",
+    "home/.claude/CLAUDE.md": "8e676a68e64e031e1a34b8a1aae8412a294318b8f491bea451930b261813c9a1",
     "home/.claude/agents/code-explorer.md": "c2e7f592fda4c272a45608c511225e99d6bbde13e6fd0be11a6d03238aecb360",
     "home/.claude/agents/product-designer.md": "5b5ae0ff96a094ea9b6e839f0ced124208da157cdc478c969c4cf7cafa36226b",
     "home/.claude/agents/qa-engineer.md": "487a69e0a2331209bdbe9cc8eb39c83919a2aa189c9f50df898dad3ad6bc5d68",

{pactkit-3.1.0 → pactkit-4.0.0}/tests/fixtures/host_prompt_snapshots/codex.json

@@ -74,8 +74,8 @@
     "project/AGENTS.md"
   ],
   "body_digests": {
-    "home/.codex/.pactkit-deployed.json": "13087e0a047dd05ff2185f21bf58a7abfb8bdb6d67b273c9472ffe110148e670",
-    "home/.codex/AGENTS.md": "90c3c457f26096d7b9b80eb917d8b93ad4f0a40281795e009d639b59dbc677a7",
+    "home/.codex/.pactkit-deployed.json": "f3c23b6f0319f1602679533d4b6c69c3e752ab1bd4306d359ee22cfa5d17adf8",
+    "home/.codex/AGENTS.md": "c524754b87591ecadcad8b252180f97fd0c9eb4246f3ce13d8d536dac34af939",
     "home/.codex/rules/pactkit-runtime.md": "fd8a852e8b6d8dc71ee980fdce731bffbcd189bc2507b0813c26f4114d44f64b",
     "home/.codex/skills/.pactkit-command-manifest.json": "ba46031e64fdcf77ebea7fe352f2cdf2c3792876ab1724d3cb103d315e7770be",
     "home/.codex/skills/pactkit-analyze/SKILL.md": "61e170f41ac108606adc180e15007eaae84db5369a12e49b4ba0bed119b7e059",

{pactkit-3.1.0 → pactkit-4.0.0}/tests/fixtures/host_prompt_snapshots/opencode.json

@@ -86,8 +86,8 @@
     "project/AGENTS.md"
   ],
   "body_digests": {
-    "home/.config/opencode/.pactkit-deployed.json": "7136449928820fa86c0a49a595e6fc6d9cf358acc4621e971ae32ad492d4fd82",
-    "home/.config/opencode/AGENTS.md": "f1b9ff9e60f5f8f367060db37712ca2a592bedef88566a0b43473ef349275e70",
+    "home/.config/opencode/.pactkit-deployed.json": "72d043f55c354164ca863f77be4fa9867d7dec420d39a99eb806f1556912c1bd",
+    "home/.config/opencode/AGENTS.md": "bc9777f2d1da4ee080e72e221b33a31a44b862671460102e753595fbde9a5084",
     "home/.config/opencode/agents/code-explorer.md": "37f70e6591298036f4f9a31e7c32800afc75989929415a545c4219d3e9618a4c",
     "home/.config/opencode/agents/product-designer.md": "4787453ddfbe4dd88b8145a888a00b2925bfa6b4cd9325f033e430d39416b8c0",
     "home/.config/opencode/agents/qa-engineer.md": "a762da03d68820e99607e3b23270a9f831cd5ea65966de983b19842a17bfc1b2",

{pactkit-3.1.0 → pactkit-4.0.0}/tests/scripts/host_artifact_snapshot.py

@@ -313,7 +313,9 @@ def _skip_lines(stdout: str) -> list[str]:
     return [ln.strip() for ln in stdout.splitlines() if ln.strip().startswith(markers)]
 
 
-def measure(hosts: tuple[str, ...] | None = None) -> dict[str, Snapshot]:
+def measure(
+    hosts: tuple[str, ...] | None = None, *, allow_adapter_skew: bool = False
+) -> dict[str, Snapshot]:
     """One deploy per host, in a fresh tree each time.
 
     ``hosts`` defaults to :func:`measurable_hosts` — deploying an adapter host
@@ -321,8 +323,23 @@ def measure(hosts: tuple[str, ...] | None = None) -> dict[str, Snapshot]:
     ``deploy()`` raises), so the measurement covers what this environment can
     deploy and :func:`unmeasured_hosts` reports the rest.  ``all`` is always
     measured: it is Core's own composite path and needs no adapter.
+
+    ``allow_adapter_skew`` is a **4.0 lockstep-bump regeneration escape hatch**,
+    and nothing else. During a lockstep release the core version moves first, so
+    every adapter is momentarily skewed by the (correct) deploy gate — and this
+    snapshot needs all four hosts deployable to record anything at all. Without
+    the hatch the golden could never be regenerated under the release order the
+    project actually uses.
+
+    It relaxes **only the version gate on the deploy**, not the artifacts: the
+    adapter's distribution version reaches no deployed file (measured
+    2026-09-26 — no production code reads it; the manifest records *core's*
+    ``__version__``, which adapters re-export). The adapter bump is therefore
+    expected to leave the golden byte-identical, and the post-bump regeneration
+    without this flag is what proves it.
     """
     hosts = measurable_hosts() if hosts is None else tuple(hosts)
+    skew = ["--allow-adapter-skew"] if allow_adapter_skew else []
     result: dict[str, Snapshot] = {}
     with tempfile.TemporaryDirectory(prefix="pactkit-snapshot-") as tmp:
         base = Path(tmp)
@@ -330,7 +347,7 @@ def measure(hosts: tuple[str, ...] | None = None) -> dict[str, Snapshot]:
             home, project = base / host / "home", base / host / "project"
             home.mkdir(parents=True)
             project.mkdir(parents=True)
-            proc = _run(["init", "--format", host], home, project)
+            proc = _run(["init", "--format", host, *skew], home, project)
             if proc.returncode != 0:
                 raise SystemExit(
                     f"deploy for {host!r} failed (exit {proc.returncode}):\n"
@@ -355,7 +372,7 @@ def measure(hosts: tuple[str, ...] | None = None) -> dict[str, Snapshot]:
         target = base / "all" / "target"
         home.mkdir(parents=True)
         project.mkdir(parents=True)
-        proc = _run(["init", "--format", "all", "-t", str(target)], home, project)
+        proc = _run(["init", "--format", "all", "-t", str(target), *skew], home, project)
         if proc.returncode != 0:
             raise SystemExit(
                 f"deploy for 'all' failed (exit {proc.returncode}):\n"
@@ -502,12 +519,21 @@ def main() -> int:
     ap.add_argument("--write", action="store_true", help="record the measured snapshot as the golden")
     ap.add_argument("--stability", action="store_true", help="measure twice and report what differs")
     ap.add_argument("--verbose", action="store_true", help="list every compared field")
+    ap.add_argument(
+        "--allow-adapter-skew",
+        action="store_true",
+        help=(
+            "4.0 lockstep-bump regeneration escape hatch: pass through to "
+            "`init` so a momentarily-skewed adapter can still deploy. Only "
+            "relaxes the version gate; the artifacts are unchanged by it."
+        ),
+    )
     args = ap.parse_args()
 
     if args.stability:
         return stability()
 
-    measured = measure()
+    measured = measure(allow_adapter_skew=args.allow_adapter_skew)
     if args.write:
         return write_golden(measured)
     return diff_against_golden(measured, args.verbose)

{pactkit-3.1.0 → pactkit-4.0.0}/tests/scripts/refresh_host_prompt_snapshots.py

@@ -29,16 +29,33 @@ class DeployUnavailable(RuntimeError):
     """A host whose adapter is missing or skewed cannot be snapshotted."""
 
 
-def deploy(host: str, base: Path) -> Path:
-    """Deploy `host` into `base`, honouring an isolated HOME."""
+def deploy(host: str, base: Path, *, allow_adapter_skew: bool = False) -> Path:
+    """Deploy `host` into `base`, honouring an isolated HOME.
+
+    ``allow_adapter_skew`` is the **4.0 lockstep-bump regeneration escape
+    hatch**, and nothing else. During a lockstep release the core version moves
+    first, so every adapter is momentarily skewed by the (correct) deploy gate —
+    and this script needs all four hosts deployable or it pins fewer hosts than
+    the golden has and refuses (the PR #13 lesson). Without the hatch the
+    goldens could never be regenerated under the release order this project
+    actually uses.
+
+    It relaxes **only the version gate on the deploy**. The adapter's
+    distribution version reaches no deployed file (measured 2026-09-26: no
+    production code reads it; the manifest records *core's* ``__version__``,
+    which adapters re-export), so the adapter bump is expected to leave the
+    goldens byte-identical — and the post-bump regeneration *without* this flag
+    is what proves it.
+    """
     home = base / host / "home"
     project = base / host / "project"
     home.mkdir(parents=True)
     project.mkdir(parents=True)
     (project / ".git" / "hooks").mkdir(parents=True)
 
+    skew = ["--allow-adapter-skew"] if allow_adapter_skew else []
     proc = subprocess.run(
-        [sys.executable, "-m", "pactkit", "init", "--format", host],
+        [sys.executable, "-m", "pactkit", "init", "--format", host, *skew],
         capture_output=True, text=True, cwd=project, timeout=180,
         env={
             "PATH": "/usr/bin:/bin",
@@ -119,6 +136,8 @@ def main() -> int:
     # is being retired).
     before = pinned_hosts()
     allow_shrink = "--allow-shrink" in sys.argv
+    # 4.0 lockstep-bump regeneration escape hatch — see `deploy()`.
+    allow_skew = "--allow-adapter-skew" in sys.argv
     for host in HOSTS:
         import importlib.metadata
 
@@ -137,7 +156,7 @@ def main() -> int:
         base = Path(tmp)
         for host in HOSTS:
             try:
-                root = deploy(host, base)
+                root = deploy(host, base, allow_adapter_skew=allow_skew)
             except DeployUnavailable as exc:
                 # Reported, not swallowed: a host that stays unpinned is a real
                 # gap in the parity suite.

pactkit-4.0.0/tests/unit/test_adapter_availability_gate.py

@@ -0,0 +1,88 @@
+"""三态可用性门禁**自己的**见证者。
+
+`_adapter_availability` 的存在理由是一次假绿：2026-09-25 共享 runner 的
+toolcache 里躺着三个不同版本的 adapter，套件看上去「装备齐全」，唯一的信号是
+某条无关测试深处的一个 skew 报错。门禁把那种状态变成大声的失败。
+
+**这里补的是它一直没有的东西（2026-09-26）。** 在写这个文件之前，没有任何
+断言针对门禁自身的行为。实测：把 `_fail_if_half_equipped` 的 `partial` 分支短路
+——也就是把这个缺陷重新折叠回沉默——core 全量仍是 `6865 passed, 10 skipped`，
+与基线逐字相同。**一个存在意义就是让假绿不可能发生的机制，自己没有见证者。**
+
+四条用例**模拟**状态而不是依赖环境，所以在 core-only CI 与四宿主齐全的机器上
+运行结果完全一致——这是刻意的：门禁的价值恰恰在「环境本身可能坏掉」的场合，
+而那种场合不能是运行它的前提。
+"""
+
+from __future__ import annotations
+
+import pytest
+
+import _adapter_availability as A
+
+
+@pytest.fixture
+def states(monkeypatch):
+    """把 `require_the_shipped_adapters` 从指定环境驱动起来。"""
+
+    def _set(present: set[str], skewed: dict[str, list[str]] | None = None):
+        monkeypatch.setattr(A, "_all_registered", lambda: {"classic", *present})
+        monkeypatch.setattr(A, "_skewed", lambda: dict(skewed or {}))
+
+    return _set
+
+
+class TestTheGateDistinguishesThreeStates:
+    def test_none_skips_quietly(self, states):
+        """一个 adapter 都没有是**合法配置**——core-only 跑就该安静跳过。"""
+        states(set())
+        with pytest.raises(pytest.skip.Exception) as exc:
+            A.require_the_shipped_adapters()
+        assert "core-only" in str(exc.value)
+
+    def test_partial_fails_loudly(self, states):
+        """**半装备是环境缺陷，不是「判不了」**——2026-09-25 假绿正是这个形态。"""
+        states({"opencode"})
+        with pytest.raises(pytest.fail.Exception) as exc:
+            A.require_the_shipped_adapters()
+        assert "partial adapter install" in str(exc.value), (
+            "半装备被折叠成了别的结论——这正是门禁存在的理由"
+        )
+
+    def test_skew_fails_loudly(self, states):
+        """三个都在但版本对不上，同样是环境缺陷，同样必须大声。"""
+        states({"opencode", "codex", "copilot"}, {"codex": ["incompatible"]})
+        with pytest.raises(pytest.fail.Exception) as exc:
+            A.require_the_shipped_adapters()
+        assert "adapter skew" in str(exc.value)
+
+    def test_complete_runs(self, states):
+        """阳性对照：装备齐全时**不许**抛任何东西。
+
+        少了这条，「门禁永远报错」也能让上面三条各自通过。
+        """
+        states({"opencode", "codex", "copilot"})
+        A.require_the_shipped_adapters()  # 不抛 = 该跑就跑
+
+    def test_the_four_cases_are_not_all_the_same(self, states):
+        """反空转：四种状态必须给出**四种不同**的结论。
+
+        上面每条只断言「抛了某个异常」，所以一个把所有情况都变成 skip 的门禁
+        照样能让它们全绿。这条把它们并排比，逼出区分度本身。
+        """
+        outcomes = []
+        for present, skewed in (
+            (set(), None),
+            ({"opencode"}, None),
+            ({"opencode", "codex", "copilot"}, {"codex": ["x"]}),
+            ({"opencode", "codex", "copilot"}, None),
+        ):
+            states(present, skewed)
+            try:
+                A.require_the_shipped_adapters()
+                outcomes.append("run")
+            except pytest.skip.Exception:
+                outcomes.append("skip")
+            except pytest.fail.Exception:
+                outcomes.append("fail")
+        assert outcomes == ["skip", "fail", "fail", "run"], outcomes