Adopt Skylos dead-code detection

.github/workflows/ci.yml

@@ -48,7 +48,7 @@ jobs:
       - name: Check spelling
         run: make spelling
 
-      - name: Run ruff
+      - name: Run linters, including Skylos dead-code detection
         run: make lint
 
       - name: Run typechecker

.gitignore

@@ -186,6 +186,7 @@ cython_debug/
 
 # Ruff stuff:
 .ruff_cache/
+.skylos/
 
 # PyPI configuration file
 .pypirc

AGENTS.md

@@ -86,7 +86,14 @@
   - Formatting is correct and validated.
 - **For Python files:**
   - **Testing:** Passes all relevant unit and behavioural tests (`make test`).
-  - **Linting:** Passes lint checks (`make lint`).
+  - **Linting:** Passes the complete `make lint` pipeline: Ruff, Interrogate,
+    Pylint, and the blocking Skylos dead-code scan. Investigate every Skylos
+    finding and remove genuine dead code. After verifying a false positive,
+    prefer a precise, typed entry-point rule in `[tool.skylos.dead_code]` with
+    its fully qualified symbol and a reason that names the verified caller.
+    Use `type = "method"` for methods. Use
+    `make skylos-allow NAME=handler REASON="Loaded by plugin registry"` only
+    when an entry-point rule cannot describe the boundary.
   - **Formatting:** Adheres to formatting standards (`make check-fmt`; use
     `make fmt` to apply fixes).
   - **Typechecking:** Passes type checking (`make typecheck`).

Makefile

@@ -25,10 +25,14 @@ PYLINT_TARGETS ?= lading scripts tests
 PYLINT_PYPY_SHIM_REF ?= 726d09f968b4d729ee4b29c71fc732e744854f3b
 PYLINT_PYPY_SHIM = git+https://github.com/leynos/pylint-pypy-shim.git@$(PYLINT_PYPY_SHIM_REF)
 PYLINT = $(UV) tool run --python $(PYLINT_PYTHON) --from '$(PYLINT_PYPY_SHIM)' pylint-pypy
+SKYLOS_VERSION ?= 4.33.2
+SKYLOS ?= $(UV_ENV) $(UV) tool run --from 'skylos==$(SKYLOS_VERSION)' skylos \
+	--config-file pyproject.toml
+SKYLOS_PRODUCTION_TARGETS ?= lading
 
 .PHONY: help all clean build build-release lint fmt check-fmt \
 	markdownlint nixie spelling spelling-helper-test test typecheck crosshair \
-	$(TOOLS) $(VENV_TOOLS)
+	skylos-allow $(TOOLS) $(VENV_TOOLS)
 
 .DEFAULT_GOAL := all
 
@@ -88,12 +92,22 @@ lint: build $(UV) interrogate ## Run linters
 	$(RUFF) check
 	$(UV) run interrogate --fail-under 100 lading
 	$(PYLINT) $(PYLINT_TARGETS)
+	$(SKYLOS) $(SKYLOS_PRODUCTION_TARGETS) --category dead_code --gate \
+		--format concise --no-upload --no-provenance --no-grep-verify
+
+skylos-allow: export SKYLOS_NAME = $(value NAME)
+skylos-allow: export SKYLOS_REASON = $(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_REASON}" || { printf "Error: REASON is required for a named whitelist exception\\n" >&2; exit 2; }
+	$(SKYLOS) whitelist "$${SKYLOS_NAME}" --reason "$${SKYLOS_REASON}"
 
 typecheck: build $(UV) ## Run typechecking
 	$(UV_ENV) $(TY) check --python-version 3.13 $(PY_SOURCES)
 
 markdownlint: spelling $(MDLINT) ## Lint Markdown files and enforce spelling
 	find . -type f -name '*.md' \
+	  -not -path './.uv-cache/*' -not -path './.uv-tools/*' \
 	  -not -path './.venv/*' -print0 | xargs -0 $(MDLINT)
 
 spelling: spelling-helper-test ## Enforce en-GB-oxendict spelling in Markdown prose

docs/adr/003-three-tier-python-linting.md

@@ -1,4 +1,4 @@
-# ADR-003: Use three-tier Python linting
+# ADR-003: Use layered Python linting
 
 ## Status
 
@@ -14,17 +14,22 @@ package code so internal APIs stay discoverable as modules are refactored.
 That documentation requirement needs to be part of the normal lint gate rather
 than an optional local check. It also needs to run after the virtual
 environment has been created and synchronized, because Interrogate is installed
-as a development dependency.
+as a development dependency. Cross-module dead-code detection also needs a
+blocking, deterministic production scan, without treating test-only references
+as application liveness.
 
 ## Decision
 
-`make lint` is the canonical Python lint gate and runs three tiers in order:
+`make lint` is the canonical Python lint gate and runs four tiers in order:
 
 1. Ruff checks formatting-adjacent style and broad correctness rules.
 2. Interrogate runs with `--fail-under 100` against `lading` and requires 100%
    docstring coverage.
 3. Pylint runs through the pinned `pylint-pypy-shim` command and applies the
    selected complementary checks.
+4. Skylos runs separately through a pinned `uv tool run` environment against
+   `lading`, with dead-code analysis only, no uploads or provenance collection,
+   and no repository-wide grep verification.
 
 The Makefile keeps lint tooling wired as prerequisites as well as recipe
 commands. `lint` depends on `build` before checking `interrogate`, so
@@ -35,7 +40,9 @@ the virtual-environment tool.
 
 New package modules, helper functions, and refactors must include docstrings at
 the time they are introduced. Missing documentation fails `make lint` before
-the Pylint tier runs.
+the Pylint tier runs. Genuine dead code must be removed. A verified static
+analysis false positive requires a precise, reasoned Skylos entry point or
+named allow-list exception in `pyproject.toml`.
 
 Contributors can still use Ruff and targeted tests during inner-loop work, but
 changes are not ready until the full `make lint` target succeeds.

docs/contents.md

@@ -30,8 +30,8 @@ branch, recording the plan, progress, decisions, and retrospective for a change.
 
 ## Decision records
 
-- [ADR-003: Use three-tier Python linting][adr-003] - accepted linting policy
-  for Ruff, Interrogate, and Pylint.
+- [ADR-003: Use layered Python linting][adr-003] - accepted linting policy for
+  Ruff, Interrogate, Pylint, and Skylos.
 - [ADR-004: In-process metrics accumulator flushed at exit][adr-004] - accepted
   design for the `lading.utils.metrics` backend and metric contracts.
 

docs/developers-guide.md

@@ -46,16 +46,17 @@ Run the Python lint gate with:
 make lint
 ```
 
-The target is deliberately three-tiered. Ruff runs first because it is fast,
+The target is deliberately four-tiered. Ruff runs first because it is fast,
 handles broad style and correctness checks, and imports the stricter lint
 policy used by `leynos/episodic`. If Ruff passes, the target runs `interrogate`
 with `--fail-under 100` across `lading` to enforce **100% docstring coverage**.
-If `interrogate` passes, the final tier runs Pylint through the pinned
+If `interrogate` passes, the third tier runs Pylint through the pinned
 `pylint-pypy-shim` tool under PyPy. The final tier is focused on rule families
 that complement Ruff, especially logging format safety, pattern matching
 checks, selected simplification checks, deprecated standard-library usage, file
-hygiene, and design-size limits.
-[ADR-003](adr/003-three-tier-python-linting.md) records the policy decision.
+hygiene, and design-size limits. Skylos then runs a blocking production-only
+dead-code scan across `lading`. [ADR-003](adr/003-three-tier-python-linting.md)
+records the policy decision.
 
 The relevant Makefile variables are:
 
@@ -79,20 +80,48 @@ The relevant Makefile variables are:
 - `PYLINT_PYPY_SHIM` — Git URL assembled from the pinned shim revision.
 - `PYLINT` — full `uv tool run --python $(PYLINT_PYTHON)` invocation for the
   shimmed Pylint command.
+- `SKYLOS_VERSION` — pinned Skylos release; defaults to `4.33.2`.
+- `SKYLOS` — separately provisioned Skylos command, configured from
+  `pyproject.toml` so local and Continuous Integration (CI) runs share the
+  reviewed allow-list policy.
+- `SKYLOS_PRODUCTION_TARGETS` — source directories checked for dead code;
+  defaults to `lading` so test-only references do not keep application symbols
+  live.
 
 The `lint` target depends on `ruff`, `build`, `uv`, and `interrogate`, so it
 creates and syncs the virtual environment before checking virtual-environment
-tools. Keep any future lint additions wired through Makefile prerequisites as
-well as command invocations, so local failures remain early and clear.
-
-Ruff and Pylint policy live in `pyproject.toml`. The Ruff configuration enables
-preview rules, targets Python 3.13, imports the selected `episodic` rule set,
-and bans deprecated `typing` aliases in favour of built-in collection types,
-`collections.abc`, `collections`, `contextlib`, or `re` as appropriate. The
-Pylint configuration keeps the pass opt-in by disabling all messages first and
-then enabling only the chosen third-tier checks. Local ignores and thresholds
-document existing codebase constraints that should be addressed as focused
-cleanup work rather than incidental lint-gate churn.
+tools. Skylos is separately provisioned by `uv tool run`. Keep any future lint
+additions wired through Makefile prerequisites and command invocations, so
+local failures remain early and clear.
+
+Ruff, Pylint, and Skylos policy live in `pyproject.toml`. The Ruff
+configuration enables preview rules, targets Python 3.13, imports the selected
+`episodic` rule set, and bans deprecated `typing` aliases in favour of built-in
+collection types, `collections.abc`, `collections`, `contextlib`, or `re` as
+appropriate. The Pylint configuration keeps the pass opt-in by disabling all
+messages first and then enabling only the chosen third-tier checks. Local
+ignores and thresholds document existing codebase constraints that should be
+addressed as focused cleanup work rather than incidental lint-gate churn.
+
+Skylos runs with concise, non-interactive output, dead-code analysis only, no
+uploads or provenance collection, and no repository-wide grep verification. The
+latter two constraints keep the local and CI gate deterministic and prevent
+test references from distorting production liveness. It never modifies source
+files.
+
+Treat every Skylos finding as dead code until its caller is verified. Remove
+genuine dead code. When a protocol-dispatched method, framework callback, or
+other runtime boundary cannot be inferred statically, add a precise, typed
+entry-point rule under `[tool.skylos.dead_code]`, using the fully qualified
+symbol and a reason that identifies the verified caller. Use `type = "method"`
+for methods. The configured entry points and the named whitelist are the
+version-controlled Skylos allow-list; do not add unexplained broad exceptions.
+
+Use `make skylos-allow NAME=... REASON=...` only when no typed entry-point rule
+can model the boundary. The target rejects blank values and records named
+exceptions under `[tool.skylos.whitelist.documented]`; each reason must explain
+who calls the symbol and how that was verified. Remove allow-list entries when
+the runtime boundary disappears.
 
 ## Testing hooks
 

docs/execplans/regenerate-lockfiles.md

@@ -121,7 +121,7 @@ fixture lockfile and seeing that lockfile listed in the bump output with a
 - [x] (2026-07-07 12:20Z) Stage A: prototype proved
   `cargo update --workspace --manifest-path <nested>` restores freshness for a
   nested fixture package with a path dependency on a bumped workspace crate. See
-  `Artifacts and notes`. No fallback command needed.
+  `Artefacts and notes`. No fallback command needed.
 - [x] (2026-07-07 13:10Z) Stage B: red tests landed and observed failing for
   the expected reasons — three new unit tests plus the two extended wiring
   tests failed with

lading/commands/bump_manifests.py

@@ -139,12 +139,3 @@ def _dependency_sections_for_crate(
         # corresponding table entry can be located and updated.
         sections.setdefault(section, set()).add(dependency.manifest_name)
     return sections
-
-
-# Re-export internal functions used by tests to maintain backward compatibility
-_parse_manifest = bump_toml.parse_manifest
-_select_table = bump_toml.select_table
-_assign_version = bump_toml.assign_version
-_value_matches = bump_toml.value_matches
-_update_dependency_sections = bump_toml.update_dependency_sections
-_update_dependency_table = bump_toml.update_dependency_table

lading/commands/publish.py

@@ -216,7 +216,6 @@ def _copy_workspace_tree(
 
 def prepare_workspace(
     plan: PublishPlan,
-    workspace: WorkspaceGraph,
     *,
     options: PublishOptions | None = None,
 ) -> PublishPreparation:
@@ -227,8 +226,6 @@ def prepare_workspace(
     plan : PublishPlan
         The publication plan describing the workspace root and the publishable
         crates to be staged.
-    workspace : WorkspaceGraph
-        The resolved workspace graph being staged for publication.
     options : PublishOptions | None, optional
         Staging options controlling the build directory, symlink handling, and
         automatic cleanup. When :data:`None`, default :class:`PublishOptions`
@@ -248,7 +245,7 @@ def prepare_workspace(
 
     Examples
     --------
-    >>> preparation = prepare_workspace(plan, workspace)  # doctest: +SKIP
+    >>> preparation = prepare_workspace(plan)  # doctest: +SKIP
     >>> preparation.staging_root  # doctest: +SKIP
     PosixPath('/tmp/lading-publish-abcd1234/my-workspace')
     """
@@ -731,7 +728,7 @@ def run(
     plan = plan_publication(
         active_workspace, active_configuration, workspace_root=root_path
     )
-    preparation = prepare_workspace(plan, active_workspace, options=options)
+    preparation = prepare_workspace(plan, options=options)
     _apply_strip_patch_strategy(
         preparation.staging_root,
         plan,

lading/config.py

@@ -57,10 +57,6 @@ class ConfigurationNotLoadedError(ConfigurationError):
     """Raised when code accesses the configuration before it is loaded."""
 
 
-class MissingConfigurationError(ConfigurationError):
-    """Raised when the configuration file cannot be located."""
-
-
 @dc.dataclass(frozen=True, slots=True)
 class DocumentationConfig:
     """Configuration for documentation updates triggered by ``bump``."""

lading/workspace/graph_build.py

@@ -173,7 +173,6 @@ def _build_crate(
     readme_is_workspace = _manifest_uses_workspace_readme(manifest_path)
     root_path = manifest_path.parent
     return WorkspaceCrate(
-        id=package_id,
         name=name,
         version=version,
         manifest_path=manifest_path,

lading/workspace/models.py

@@ -60,7 +60,6 @@ class WorkspaceDependency(msgspec.Struct, frozen=True, kw_only=True):
 class WorkspaceCrate(msgspec.Struct, frozen=True, kw_only=True):
     """Represents a single crate discovered in the workspace."""
 
-    id: str
     name: str
     version: str
     manifest_path: Path

pyproject.toml

@@ -454,6 +454,37 @@ do_not_mutate = ["lading/testing/*"]
 [tool.uv]
 package = true
 
+[tool.skylos.gate]
+strict = true
+
+[[tool.skylos.dead_code.entrypoints]]
+type = "function"
+full_name = [
+    "lading.commands.lockfile.validate_lockfile_freshness",
+    "lading.commands.lockfile._is_lockfile_stale_detail",
+]
+reason = "The cargo inspection adapter delegates to these lockfile freshness classifiers."
+
+[[tool.skylos.dead_code.entrypoints]]
+type = "method"
+full_name = [
+    "lading.commands.bump_lockfiles.CargoLockfileRepository.resolve_lockfile_paths",
+    "lading.commands.bump_lockfiles.CargoLockfileRepository.regenerate_lockfiles",
+]
+reason = "BumpOptions dispatches these adapter methods through the LockfileRepository port."
+
+[[tool.skylos.dead_code.entrypoints]]
+type = "method"
+full_name = [
+    "lading.commands.lockfile.CargoLockfileInspectionRepository.validate_lockfile_freshness",
+]
+reason = "Publish pre-flight dispatches this adapter method through the LockfileInspectionRepository port."
+
+[tool.skylos.whitelist]
+names = []
+
+[tool.skylos.whitelist.documented]
+
 [tool.setuptools.packages.find]
 include = [
     "lading",

tests/helpers/workspace_builders.py

@@ -83,7 +83,6 @@ def _build_workspace_with_internal_deps(
         manifests[spec.name] = manifest_path
         crates.append(
             WorkspaceCrate(
-                id=f"{spec.name}-id",
                 name=spec.name,
                 version=spec.version,
                 manifest_path=manifest_path,
@@ -145,7 +144,6 @@ def _create_alpha_crate(workspace_root: Path) -> WorkspaceCrate:
         encoding="utf-8",
     )
     return WorkspaceCrate(
-        id="alpha-id",
         name="alpha",
         version="0.1.0",
         manifest_path=alpha_manifest,
@@ -184,7 +182,6 @@ def _create_beta_crate_with_dependencies(
         encoding="utf-8",
     )
     return WorkspaceCrate(
-        id="beta-id",
         name="beta",
         version="0.1.0",
         manifest_path=beta_manifest,

tests/unit/conftest.py

@@ -192,7 +192,6 @@ def _make_crate(
         manifest.write_text(tomlkit.dumps(document), encoding="utf-8")
 
         return WorkspaceCrate(
-            id=f"{name}-id",
             name=name,
             version="0.1.0",
             manifest_path=manifest,