Adopt a benchmarked PyChase code-duplication gate

.github/workflows/ci.yml

@@ -32,6 +32,22 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
 
+      # The Makefile scopes uv to repo-local cache and tool directories,
+      # so caching them preserves the Skylos tool environment, the
+      # duplication gate's PyChase script environment (Python 3.13), and
+      # the pinned pylint/df12 tool environments between runs. The
+      # Makefile and gate script pin those tool versions, so their
+      # hashes key the cache alongside the project lockfile.
+      - name: Cache uv tool and script environments
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            .uv-cache
+            .uv-tools
+          key: uv-envs-${{ runner.os }}-${{ hashFiles('uv.lock', 'Makefile', 'scripts/duplication_gate.py') }}
+          restore-keys: |
+            uv-envs-${{ runner.os }}-
+
       - name: Install CLI tools
         run: |
           for tool in mbake ty ruff; do uv tool install "${tool}"; done
@@ -68,6 +84,9 @@ jobs:
       - name: Run lint
         run: make lint
 
+      - name: Run duplication gate tests
+        run: make duplication-test
+
       - name: Check spelling
         run: make spelling
 

.gitignore

@@ -21,3 +21,4 @@ __pycache__/
 .grepai/
 *.swo
 *~
+.pyscn/

AGENTS.md

@@ -95,8 +95,18 @@
     names the verified runtime caller. Match methods as `type = "method"`,
     rather than `"function"`. Use the named allow-list target only when an
     entry-point rule cannot describe the boundary: run
-    `make skylos-allow NAME=handler REASON="Loaded by plugin registry"`
+
+    ```sh
+    make skylos-allow SYMBOL=episodic.api.handlers.handle_get_entity \
+      REASON="Loaded by plugin registry"
+    ```
+
     with the verified caller in the reason.
+    The lint pipeline ends with the blocking PyChase duplication gate.
+    Prefer extracting shared logic over suppressing a finding; when parallel
+    structure is intentional, record a reasoned exception with
+    `make duplication-allow FIRST='path::qualname' [SECOND='path::qualname']
+    REASON="why this stays"`, and remove entries the gate reports as stale.
   - **Formatting:** Adheres to formatting standards (`make check-fmt`; use
     `make fmt` to apply fixes).
   - **Typechecking:** Passes type checking (`make typecheck`).

Makefile

@@ -36,13 +36,19 @@ DF12_FUTURE_ANNOTATIONS = $(DF12_PYLINT_BASE) --enable=C9112 \
 AMBRLEAKS = $(UV_ENV) $(UV) tool run --python $(DF12_PYTHON) \
 	--from '$(DF12_PYTHON_LINTS)' ambrleaks
 SKYLOS_VERSION = 4.33.2
-SKYLOS = $(UV_ENV) $(UV) tool run --from 'skylos==$(SKYLOS_VERSION)' skylos \
+# Pin the tool interpreter: Skylos parses sources with its own runtime `ast`,
+# so an older default Python misreads the project's 3.14 syntax.
+SKYLOS_CLI = $(UV_ENV) $(UV) tool run --python 3.14 \
+	--from 'skylos==$(SKYLOS_VERSION)' skylos
+SKYLOS = $(SKYLOS_CLI) \
 	--config-file pyproject.toml
 SKYLOS_PRODUCTION_TARGETS ?= alembic episodic openai_test_types.py
+DUPLICATION_GATE = $(UV_ENV) $(UV) run scripts/duplication_gate.py
 
 .PHONY: help all clean build build-release lint fmt check-fmt \
         markdownlint nixie spelling spelling-helper-test test typecheck \
         crosshair check-migrations skylos-allow validate \
+        duplication duplication-test duplication-allow \
         local-k8s-up local-k8s-down local-k8s-status local-k8s-logs \
         $(TOOLS) $(VENV_TOOLS)
 
@@ -110,13 +116,41 @@ lint: check-architecture ## Run linters
 	$(DF12_FUTURE_ANNOTATIONS) $(PYLINT_TARGETS)
 	$(AMBRLEAKS) tests
 	$(SKYLOS) $(SKYLOS_PRODUCTION_TARGETS) --category dead_code --gate --format concise --no-upload --no-provenance --no-grep-verify
+	$(DUPLICATION_GATE) check
 
-skylos-allow: export SKYLOS_NAME = $(value NAME)
-skylos-allow: export SKYLOS_REASON = $(value REASON)
+duplication: ## Run the blocking code-duplication gate
+	$(DUPLICATION_GATE) check
+
+duplication-test: ## Run the duplication-gate helper tests
+	@$(UV_ENV) $(UV) run --no-project --python 3.13 \
+		--with pytest==9.0.2 --with cyclopts --with 'pychase==0.1.0' \
+		--with tomlkit --with 'hypothesis[asyncio]==6.165.6' \
+		python -m pytest -c /dev/null --rootdir=. -p no:cacheprovider \
+		scripts/tests
+
+# Accept FIRST/SECOND/REASON (and skylos SYMBOL) only from the make command
+# line. `NAME` is ambient under WSL, which injects the hostname there, so the
+# Skylos interface deliberately uses the otherwise-unset `SYMBOL` variable.
+cli_value = $(if $(filter command line,$(origin $(1))),$(value $(1)))
+
+duplication-allow: export DUPLICATION_FIRST = $(call cli_value,FIRST)
+duplication-allow: export DUPLICATION_SECOND = $(call cli_value,SECOND)
+duplication-allow: export DUPLICATION_REASON = $(call cli_value,REASON)
+duplication-allow: ## Record one reasoned duplication exception
+	@test -n "$${DUPLICATION_FIRST}" || { printf "Error: FIRST is required (path::qualname)\\n" >&2; exit 2; }
+	@test -n "$${DUPLICATION_REASON}" || { printf "Error: REASON is required for a duplication exception\\n" >&2; exit 2; }
+	$(DUPLICATION_GATE) allow --first "$${DUPLICATION_FIRST}" \
+		$(if $(call cli_value,SECOND),--second "$${DUPLICATION_SECOND}",) \
+		--reason "$${DUPLICATION_REASON}"
+
+skylos-allow: export SKYLOS_SYMBOL = $(call cli_value,SYMBOL)
+skylos-allow: export SKYLOS_REASON = $(call cli_value,REASON)
 skylos-allow: ## Document one named Skylos exception, not an entry point
-	@test -n "$${SKYLOS_NAME}" || { printf "Error: NAME is required for a named whitelist exception\\n" >&2; exit 2; }
+	@test -n "$${SKYLOS_SYMBOL}" || { printf "Error: SYMBOL is required for a named whitelist exception\\n" >&2; exit 2; }
 	@test -n "$${SKYLOS_REASON}" || { printf "Error: REASON is required for a named whitelist exception\\n" >&2; exit 2; }
-	$(SKYLOS) whitelist "$${SKYLOS_NAME}" --reason "$${SKYLOS_REASON}"
+	# The whitelist subcommand must be skylos's first argument; global
+	# options such as --config-file make the main parser treat it as a path.
+	$(SKYLOS_CLI) whitelist "$${SKYLOS_SYMBOL}" --reason "$${SKYLOS_REASON}"
 
 check-architecture: build ## Check hexagonal architecture import boundaries
 	$(UV_ENV) $(UV) run hecate check

benchmarks/dead_code/score.py

@@ -26,11 +26,31 @@
 scoring semantics are stable inputs to the benchmark evidence.
 """
 
+from __future__ import annotations
+
 import dataclasses as dc
 import enum
 import typing as typ
-from collections import abc as cabc
-from pathlib import Path
+
+from benchmarks.score_support import (
+    mapping as _mapping,
+)
+
+if typ.TYPE_CHECKING:
+    from collections import abc as cabc
+    from pathlib import Path
+from benchmarks.score_support import (
+    positive_line as _positive_line,
+)
+from benchmarks.score_support import (
+    relative_source_path,
+)
+from benchmarks.score_support import (
+    sequence as _sequence,
+)
+from benchmarks.score_support import (
+    string as _string,
+)
 
 
 class Lane(enum.StrEnum):
@@ -112,58 +132,6 @@ class LaneScore:
     unmatched_findings: int
 
 
-def _mapping(value: object, *, context: str) -> cabc.Mapping[str, object]:
-    """Validate and return a string-keyed mapping."""
-    if not isinstance(value, cabc.Mapping):
-        msg = f"{context} must be a JSON object"
-        raise TypeError(msg)
-    if not all(isinstance(key, str) for key in value):
-        msg = f"{context} keys must be strings"
-        raise TypeError(msg)
-    return typ.cast("cabc.Mapping[str, object]", value)
-
-
-def _sequence(value: object, *, context: str) -> cabc.Sequence[object]:
-    """Validate and return a non-string sequence."""
-    if not isinstance(value, cabc.Sequence) or isinstance(value, (str, bytes)):
-        msg = f"{context} must be a JSON array"
-        raise TypeError(msg)
-    return value
-
-
-def _string(value: object, *, context: str) -> str:
-    """Validate and return a string value."""
-    if not isinstance(value, str):
-        msg = f"{context} must be a string"
-        raise TypeError(msg)
-    return value
-
-
-def _positive_line(value: object, *, context: str) -> int:
-    """Validate and return a positive, non-boolean line number."""
-    if not isinstance(value, int) or isinstance(value, bool):
-        msg = f"{context} must be a positive integer"
-        raise TypeError(msg)
-    if value < 1:
-        msg = f"{context} must be positive"
-        raise ValueError(msg)
-    return value
-
-
-def _relative_source_path(raw_path: object, corpus_root: Path) -> str:
-    """Normalize a finding path relative to the corpus root."""
-    root = corpus_root.resolve()
-    path = Path(_string(raw_path, context="finding path"))
-    if not path.is_absolute():
-        path = root / path
-    path = path.resolve()
-    try:
-        return path.relative_to(root).as_posix()
-    except ValueError as error:
-        msg = f"finding path {path} is outside corpus root {root}"
-        raise ValueError(msg) from error
-
-
 def parse_pyscn_findings(
     payload: object,
     *,
@@ -238,7 +206,11 @@ def _parse_pyscn_finding(
         context=f"pyscn findings[{finding_index}].location",
     )
     return Finding(
-        path=_relative_source_path(location.get("file_path"), corpus_root),
+        path=relative_source_path(
+            location.get("file_path"),
+            corpus_root,
+            subject="finding",
+        ),
         line=_positive_line(
             location.get("start_line"),
             context="pyscn finding start_line",
@@ -296,7 +268,11 @@ def parse_skylos_findings(
             )
             findings.append(
                 Finding(
-                    path=_relative_source_path(finding.get("file"), corpus_root),
+                    path=relative_source_path(
+                        finding.get("file"),
+                        corpus_root,
+                        subject="finding",
+                    ),
                     line=_positive_line(
                         finding.get("line"),
                         context=f"Skylos {category} line",

benchmarks/duplication/README.md

@@ -0,0 +1,50 @@
+# Code-duplication detector benchmark
+
+This directory contains the reusable, tool-neutral corpus and normalizer for
+the PyChase and pyscn clone-detection comparison. It is development evidence,
+not part of the Episodic application or its test fixtures.
+
+`corpus/` is a deliberately small Python project. Its own `pyproject.toml`
+bounds project-root discovery without configuring either detector. The
+`pricing` module holds original routines; `reporting` clones them as labelled
+Type-1 to Type-4 duplicates; `controls` holds structurally similar but
+semantically distinct false-positive bait.
+
+`expectations.json` is the oracle. Each entry labels one pair of source units
+before detector output is considered, assigns it to either the
+`syntactic-clone` (Types 1-3) or `semantic-clone` (Type 4) lane, and explains
+why merging the pair would or would not be a defensible refactor. Add a new
+label only when its clone status can be decided without trusting a detector. Do
+not change a label merely to make a detector result pass.
+
+The `score.py` module is intentionally specific to the two released JSON
+schemas captured by this comparison. Reuse it for reruns of this corpus; add a
+separate parser when evaluating a different detector rather than disguising
+schema differences inside an existing parser.
+
+`configs/` holds the permissive pyscn capability settings. `results/` retains
+the tool output, normalized scores, generational tuning tables, and the
+production-scan adjudication from 2026-08-22. The large production report is
+compressed with deterministic gzip metadata; its SHA-256 digest is recorded in
+`production-adjudication.json`.
+
+Run the corpus commands from `benchmarks/duplication/corpus/`:
+
+```bash
+uvx pyscn@1.29.1 analyze --select clones --json -c ../configs/pyscn-permissive.toml .
+PYTHONHASHSEED=0 uvx pychase@0.1.0 --json --threshold 0.6 --min-lines 5 --min-nodes 10 .
+```
+
+Run the production comparison from the repository root:
+
+```bash
+PYTHONHASHSEED=0 uvx pychase@0.1.0 --json --threshold 0.9 --min-lines 13 --min-nodes 50 episodic
+```
+
+`PYTHONHASHSEED` must be pinned for repository-scale PyChase runs: above 200
+units it buckets MinHash signatures with the built-in `hash()`, so an unpinned
+seed makes near-threshold findings flicker between runs.
+
+The elapsed times recorded in `results/scores.json` are single wall-clock
+observations, not performance benchmarks. They are retained to expose
+order-of-magnitude differences only.

benchmarks/duplication/__init__.py

@@ -0,0 +1 @@
+"""Duplication detector comparison corpus and scoring support."""

benchmarks/duplication/configs/pyscn-permissive.toml

@@ -0,0 +1,6 @@
+# Permissive capability-measurement settings for the corpus comparison.
+# The floors match the PyChase permissive run; all clone types are enabled.
+[clones]
+min_lines = 5
+min_nodes = 10
+enabled_clone_types = ["type1", "type2", "type3", "type4"]

benchmarks/duplication/corpus/__init__.py

@@ -0,0 +1,5 @@
+"""Public surface for the duplication detector corpus."""
+
+from .pricing import order_total_price
+
+__all__ = ["order_total_price"]