scitex-dev 0.26.0__tar.gz → 0.27.0__tar.gz

{scitex_dev-0.26.0 → scitex_dev-0.27.0}/.envrc

@@ -1,3 +1,5 @@
+source_up
+
 # scitex-dev → its own Telegram bot @ProjSciTeXDevBot (CCT_BOT_TOKEN_DEV).
 # sac folds at deploy; direnv applies live. Unique per project — no 409 combat.
 export CCT_AGENT_ID="scitex-dev"

{scitex_dev-0.26.0 → scitex_dev-0.27.0}/.scitex/dev/cli-audit-dict.yaml

@@ -29,6 +29,17 @@ transitive_verbs:
   # `scitex-dev ci runner use <target>` — flip CI_RUNS_ON for the
   # current repo's GitHub Actions workflow.
   - use
+  # `scitex-dev registry-normalize <pkg>` — the operator-and-sac-agreed
+  # public command name for the PS-181 registry-layout drift fixer (chosen to
+  # sit next to `trace-env-vars`). The compound leaf reads `<noun>-<verb>`
+  # (registry / normalize), so §1's leaf-head heuristic classifies the head
+  # "registry" as a noun and flags it — but the command IS a transitive
+  # action: it normalizes the registry for its required `<pkg>` object.
+  # Declare the whole leaf a transitive verb so §1 doesn't misfire, exactly
+  # like the `gate` / `unset` / `use` escape hatches above. Renaming a
+  # shipped public command to satisfy the heuristic would be worse than this
+  # one-line declaration.
+  - registry-normalize
 intransitive_verbs:
   # `scitex-dev ecosystem run` — run the collective ecosystem supervisor in
   # the foreground (the systemd ExecStart). "run" is an intransitive verb in

{scitex_dev-0.26.0/src/scitex_dev.egg-info → scitex_dev-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitex-dev
-Version: 0.26.0
+Version: 0.27.0
 Summary: Shared developer utilities for the SciTeX ecosystem
 Author-email: Yusuke Watanabe <ywatanabe@scitex.ai>
 License-Expression: AGPL-3.0-only

{scitex_dev-0.26.0 → scitex_dev-0.27.0}/docs/submission-gate.md

@@ -18,7 +18,8 @@ provenance and tells the solver exactly what to fix.
   package-agnostic: it never imports scitex-clew / scitex-dataset. The
   pre-submission hook depends on **only** scitex-dev.
 - Each **leaf** owns its *rule* and reads its *own* state from the capsule
-  workdir (clew → `.scitex/clew/*.db`; dataset → the bound submission file).
+  workdir (clew → `.scitex/clew/**/*.sqlite`, e.g. `db.sqlite` — the leaf
+  decides its own file/extension; dataset → the bound submission file).
 - **paper** owns the hooks and the submit command.
 
 This mirrors scitex-dev's existing federations (`scitex_dev.jobs`,

{scitex_dev-0.26.0 → scitex_dev-0.27.0}/src/scitex_dev/__init__.py

@@ -136,6 +136,12 @@ _LAZY_ATTRS: dict[str, str] = {
     "bulk_rename": "rename",
     "execute_rename": "rename",
     "preview_rename": "rename",
+    # trace_env
+    "TraceEnvResult": "trace_env",
+    "format_quiet": "trace_env",
+    "format_report": "trace_env",
+    "scan_env_vars": "trace_env",
+    "trace_env_vars": "trace_env",
     # ssh
     "check_all_hosts": "ssh",
     "get_remote_version": "ssh",

scitex_dev-0.27.0/src/scitex_dev/_cli/__init__.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""SciTeX-dev CLI package — entry point + reusable subcommand mixins.
+
+Module map:
+- `_root`        — top-level Click group `main` (the `scitex-dev` console script entry point)
+- `_utils`       — `handle_result`, `run_as_cli`, `wrap_as_cli`, json/dry-run option helpers
+- `_completion`  — shell tab-completion installer
+- `_doctor`      — `scitex-dev doctor`
+- `_stats`       — `scitex-dev ecosystem stats`
+- `audit/`       — `_summary` (was _cli_audit), `_api`, `_project`, `_skills`
+- `ecosystem/`   — `_registry` (was _cli_ecosystem)
+- `quality/`     — `_check` (was _cli_quality), `_frontmatter`
+- `skills/`      — `_manage` (was _cli_skills), `_tags`
+
+The `main` callable is the `[project.scripts]` target — `scitex_dev._cli:main`
+must remain importable.
+"""
+
+from __future__ import annotations
+
+import sys as _sys
+
+
+def _is_bare_version_invocation(argv: list[str]) -> bool:
+    """True iff ``argv`` is exactly a single ``--version``/``-V`` token.
+
+    A pure predicate (no ``sys.argv`` access) so it is unit-testable
+    without spawning a subprocess. Deliberately narrow — any other
+    combination (extra flags, a subcommand, ``--version --json``)
+    returns False and falls through to the real Click group unchanged.
+    """
+    return argv in (["--version"], ["-V"])
+
+
+# Fast-path a bare `--version`/`-V` invocation BEFORE importing `._root`.
+# `_root`'s module-level code eagerly registers the ENTIRE subcommand
+# tree (ecosystem, linter, gate, ci-runner, docs, skills, …) as a side
+# effect of import — several hundred ms even though a version check
+# needs none of it. `CliRunner.invoke` in tests bypasses `sys.argv`
+# entirely, so this never affects test behavior — only the real
+# console-script invocation (`scitex-dev --version`) sees it.
+if _is_bare_version_invocation(_sys.argv[1:]):
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _version
+
+    try:
+        _v = _version("scitex-dev")
+    except PackageNotFoundError:
+        _v = "0.0.0-unknown"
+    print(f"scitex-dev {_v}")
+    raise SystemExit(0)
+
+from ._root import main
+from ._utils import (
+    add_dry_run_argument,
+    add_json_argument,
+    dry_run_option,
+    handle_result,
+    json_option,
+    run_as_cli,
+    wrap_as_cli,
+)
+
+__all__ = [
+    "add_dry_run_argument",
+    "add_json_argument",
+    "dry_run_option",
+    "handle_result",
+    "json_option",
+    "main",
+    "run_as_cli",
+    "wrap_as_cli",
+]

scitex_dev-0.27.0/src/scitex_dev/_cli/_registry_normalize.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""``scitex-dev registry-normalize`` — mechanical fix for PS-181 drift.
+
+Mirrors ``_cli/_trace_env.py`` / ``_cli/_rename.py``: a thin
+``register(main)`` entry point that wires the command to the top-level
+click group; all real logic lives in the ``scitex_dev.registry_normalize``
+engine package (shared with the PS-181 audit rule, so detection can never
+drift between the two surfaces).
+
+Safety, non-negotiable:
+
+- Dry-run by default — pass ``--yes``/``-y`` to actually move files.
+- Archive, never delete.
+- A ``*.pid`` file naming a currently-alive process is SKIPPED, not moved.
+- A ``*.sock`` file is ALWAYS skipped — liveness is not cheaply
+  determinable for sockets; remove manually if you've confirmed it's
+  stale.
+- Exactly one ``<pkg>`` positional argument — no bulk "normalize
+  everything" mode.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+
+def register(main: click.Group) -> None:
+    """Attach the ``registry-normalize`` command to the top-level click group."""
+
+    @main.command(
+        "registry-normalize",
+        epilog=(
+            "Fixes PS-181 registry-layout drift for a SINGLE "
+            "~/.scitex/<pkg>/ state directory.\n"
+            "\n"
+            "CAVEATS:\n"
+            "  * dry-run by default — nothing is moved without --yes/-y.\n"
+            "  * archive, never delete — every move has a destination.\n"
+            "  * a *.pid file naming a LIVE process is skipped, not moved.\n"
+            "  * *.sock files are ALWAYS skipped (liveness of a socket is "
+            "not cheaply\n"
+            "    determinable) — remove manually once you've confirmed "
+            "it's stale.\n"
+            "  * config-naming drift, __pycache__/, and venv-naming "
+            "drift are reported\n"
+            "    by `scitex-dev ecosystem audit-registry-layout` but NOT "
+            "auto-moved here\n"
+            "    (renaming a config file or a venv is not a safe "
+            "mechanical move).\n"
+            "\n"
+            "Examples:\n"
+            "  $ scitex-dev registry-normalize scitex-todo\n"
+            "  $ scitex-dev registry-normalize scitex-todo --json\n"
+            "  $ scitex-dev registry-normalize scitex-todo --yes"
+        ),
+    )
+    @click.argument("pkg")
+    @click.option(
+        "--yes",
+        "-y",
+        "confirm",
+        is_flag=True,
+        help="Actually move files on disk. Without this flag, dry-run only.",
+    )
+    @click.option(
+        "--scitex-dir",
+        "scitex_dir_opt",
+        type=click.Path(file_okay=False, dir_okay=True),
+        default=None,
+        help="Override $SCITEX_DIR (defaults to the resolved user root, ~/.scitex).",
+    )
+    @click.option("--json", "as_json", is_flag=True, help="Emit JSON output.")
+    def _registry_normalize(pkg, confirm, scitex_dir_opt, as_json):
+        """Fix ~/.scitex/<pkg>/ registry-layout drift (dry-run by default).
+
+        \b
+        Example:
+            $ scitex-dev registry-normalize scitex-todo
+            $ scitex-dev registry-normalize scitex-todo --yes
+            $ scitex-dev registry-normalize scitex-todo --json
+        """
+        from pathlib import Path
+
+        from ..registry_normalize import run_registry_normalize
+
+        if scitex_dir_opt:
+            scitex_dir = Path(scitex_dir_opt).expanduser()
+        else:
+            from scitex_config._ecosystem import local_state
+
+            scitex_dir = local_state.user_root()
+
+        report = run_registry_normalize(pkg, confirm=confirm, scitex_dir=scitex_dir)
+
+        if as_json:
+            click.echo(json.dumps(report.to_dict(), indent=2, default=str))
+        elif report.error:
+            click.echo(f"registry-normalize: {report.error}", err=True)
+        else:
+            mode = "APPLIED" if confirm else "DRY-RUN"
+            click.echo(f"registry-normalize [{mode}] {report.pkg_dir}")
+            if not report.moves:
+                click.echo("  (no drift found — already conformant)")
+            for m in report.moves:
+                click.echo(f"  {m.detail}")
+
+        sys.exit(2 if report.error else 0)
+
+
+# EOF

{scitex_dev-0.26.0 → scitex_dev-0.27.0}/src/scitex_dev/_cli/_root.py

@@ -15,7 +15,7 @@ CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
 # not listed here falls through to the "Other" section in --help.
 COMMAND_CATEGORIES = [
     ("CI", ["ci"]),
-    ("Development", ["show-config", "rename-symbols"]),
+    ("Development", ["show-config", "rename-symbols", "trace-env-vars"]),
     ("Documentation", ["docs", "search-docs", "skills"]),
     (
         "Ecosystem",
@@ -351,6 +351,22 @@ from ._rename import register as _register_rename
 
 _register_rename(main)
 
+# trace-env-vars — env-var provenance diagnostic. Thin CLI in
+# _cli/_trace_env.py; engine in scitex_dev/trace_env/ (mirrors the
+# rename-symbols CLI/engine split).
+from ._trace_env import register as _register_trace_env
+
+_register_trace_env(main)
+
+# registry-normalize — mechanical fix for PS-181 (~/.scitex/<pkg>/
+# registry-layout drift). Thin CLI in _cli/_registry_normalize.py;
+# engine in scitex_dev/registry_normalize/ (mirrors the rename-symbols /
+# trace-env-vars CLI/engine split; shares detection logic with the
+# PS-181 audit rule via registry_normalize/scan.py).
+from ._registry_normalize import register as _register_registry_normalize
+
+_register_registry_normalize(main)
+
 # -------------------------------------------------------------------
 # Documentation commands
 # -------------------------------------------------------------------

scitex_dev-0.27.0/src/scitex_dev/_cli/_trace_env.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""``scitex-dev trace-env-vars`` — env-var provenance CLI surface.
+
+Mirrors ``_cli/_rename.py``: a thin ``register(main)`` entry-point that
+wires the command to the top-level click group; all real logic lives in
+the ``scitex_dev.trace_env`` engine package.
+
+Two modes:
+
+- static scan (default) — every assignment site for the named var(s)
+  across shell init files, direnv, tmux global env, and the current
+  process environment, with WORD-BOUNDARY matching so ``FOO`` never
+  matches ``FOO_BAR``.
+- dynamic trace (``--trace -- CMD ...``) — run CMD under strace and
+  report the first exec stage whose child env carries the var.
+
+Secret-shaped values (``*_KEY`` / ``*_TOKEN`` / ...) are redacted in all
+output. ``--json`` emits the structured envelope; ``--quiet``/``-q``
+emits a one-line summary (mirrors rename-symbols).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+
+class _PassthroughCommand(click.Command):
+    """Command that records the raw sub-args (incl. ``--``) at parse time.
+
+    Click strips the first ``--`` before the callback sees it, so a
+    ``NAMES... --trace -- CMD ARGS`` invocation loses the boundary
+    between the traced var names and the passthrough command. Capturing
+    the raw args here lets the callback split them deterministically —
+    and works identically under a real CLI and under ``CliRunner``
+    (which never populates ``sys.argv``).
+    """
+
+    def parse_args(self, ctx, args):  # noqa: D102 (inherited contract)
+        ctx.meta["trace_env_raw_args"] = list(args)
+        return super().parse_args(ctx, args)
+
+
+def _split_names_command(
+    tokens: tuple[str, ...], raw_args: list[str]
+) -> tuple[list[str], list[str]]:
+    """Split combined positionals into (names, command) on the ``--`` marker."""
+    if "--" not in raw_args:
+        return list(tokens), []
+    command = raw_args[raw_args.index("--") + 1 :]
+    names = list(tokens[: len(tokens) - len(command)]) if command else list(tokens)
+    return names, command
+
+
+def register(main: click.Group) -> None:
+    """Attach the ``trace-env-vars`` command to the top-level click group."""
+
+    @main.command(
+        "trace-env-vars",
+        cls=_PassthroughCommand,
+        context_settings={
+            "ignore_unknown_options": True,
+            "allow_extra_args": True,
+        },
+    )
+    @click.argument("names", nargs=-1, type=click.UNPROCESSED, required=True)
+    @click.option(
+        "--trace",
+        "trace_cmd",
+        is_flag=True,
+        help="Dynamic mode: run a command (after `--`) under strace and "
+        "report the first exec stage that injects the var(s).",
+    )
+    @click.option(
+        "--no-etc",
+        is_flag=True,
+        help="Skip /etc/* system surfaces (scan mode).",
+    )
+    @click.option(
+        "--no-tmux",
+        is_flag=True,
+        help="Skip the `tmux show-environment -g` probe (scan mode).",
+    )
+    @click.option("--json", "as_json", is_flag=True, help="Output as structured JSON.")
+    @click.option(
+        "--quiet",
+        "-q",
+        is_flag=True,
+        help="Emit a one-line summary instead of the full report.",
+    )
+    @click.pass_context
+    def _trace_env_vars(ctx, names, trace_cmd, no_etc, no_tmux, as_json, quiet):
+        """Trace WHERE env var(s) are defined or injected.
+
+        \b
+        Example:
+            $ scitex-dev trace-env-vars SCITEX_TODO_AGENT
+            $ scitex-dev trace-env-vars FOO BAR --json
+            $ scitex-dev trace-env-vars FOO -q
+            $ scitex-dev trace-env-vars SCITEX_TODO_AGENT --trace -- \\
+                  sac agents start scitex-todo --yes
+        """
+        from ..trace_env import (
+            format_quiet,
+            format_report,
+            scan_env_vars,
+            trace_env_vars,
+        )
+
+        raw_args = ctx.meta.get("trace_env_raw_args", [])
+        var_names, command = _split_names_command(names, raw_args)
+
+        if trace_cmd:
+            result = trace_env_vars(
+                var_names, command=command, announce=not as_json
+            )
+        else:
+            result = scan_env_vars(
+                var_names,
+                include_etc=not no_etc,
+                include_tmux=not no_tmux,
+            )
+
+        if as_json:
+            click.echo(json.dumps(result.to_dict(), indent=2, default=str))
+        elif quiet:
+            click.echo(format_quiet(result))
+        else:
+            click.echo(format_report(result))
+
+        sys.exit(1 if result.error else 0)
+
+
+# EOF

{scitex_dev-0.26.0 → scitex_dev-0.27.0}/src/scitex_dev/_cli/audit/_project/_audit.py

@@ -245,6 +245,11 @@ def audit_project(
     check_ps145_cross_package_read(repo_root, distribution, Violation, violations)
     check_ps146_pip_install_side_effect(repo_root, Violation, violations)
     check_ps147_eval_form_completion(repo_root, Violation, violations)
+    # PS-182: rolled-own local-state path resolver (git-root/project-scope
+    # precedence re-implemented instead of using scitex_config...local_state).
+    from ._check_path_resolver import check_ps182_rolled_own_path_resolver
+
+    check_ps182_rolled_own_path_resolver(repo_root, Violation, violations)
     # PS-PATH / PS-CLEW / PS-AGENT — paper-scitex-clew MVP lint set.
     # Artifact-gated (only fire when PATH.yaml / clew.add_claim /
     # scripts/agent/ are present); safe to run on every project type.

{scitex_dev-0.26.0 → scitex_dev-0.27.0}/src/scitex_dev/_cli/audit/_project/_check_local_state.py

@@ -1,7 +1,7 @@
 """PS-145 / PS-146 / PS-147 — local-state convention checks.
 
 Implements the rules from
-`_skills/general/01_ecosystem/06_local-state-directories.md`:
+`_skills/general/01_ecosystem/06_dot_scitex_directory.md`:
 
   PS-145 — cross-package state read (§9.5 plugin-port pattern).
            Source must not contain `~/.scitex/<other-pkg>/` literals
@@ -34,7 +34,7 @@ except ImportError:  # pragma: no cover
 
 # Known short-names for every scitex-* package and external partner.
 # Mirrors the §2 prefix-stripping rule in
-# 01_ecosystem/06_local-state-directories.md. Kept in sync manually with
+# 01_ecosystem/06_dot_scitex_directory.md. Kept in sync manually with
 # `_ecosystem._core.ECOSYSTEM`. Adding a new package here is a one-liner.
 _KNOWN_SHORTS = frozenset(
     {
@@ -252,7 +252,7 @@ def check_ps145_cross_package_read(
                     f"var: {sample}{more}. Use the plugin-port pattern: "
                     f"expose `SCITEX_<THIS>_*_DIRS` and let the consumer "
                     f"populate it from their own startup. See "
-                    f"_skills/general/01_ecosystem/06_local-state-directories.md "
+                    f"_skills/general/01_ecosystem/06_dot_scitex_directory.md "
                     f"§9.5."
                 ),
             )
@@ -338,7 +338,7 @@ def check_ps146_pip_install_side_effect(
         ". `pip install <pkg>` must not create `~/.scitex/<pkg-short>/` — "
         "use lazy `mkdir(parents=True, exist_ok=True)` from PathManager on "
         "first write. See _skills/general/"
-        "01_ecosystem/06_local-state-directories.md §3.5."
+        "01_ecosystem/06_dot_scitex_directory.md §3.5."
     )
     out.append(violation_cls("PS-146", str(pp), detail))
 
@@ -395,7 +395,7 @@ def check_ps147_eval_form_completion(
                     f"create an XDG symlink, and write a `[ -f cache ] && "
                     f"source cache` line into rc. See _skills/general/"
                     f"03_interface/02_cli/03_required-introspection-commands.md "
-                    f"and 01_ecosystem/06_local-state-directories.md §11."
+                    f"and 01_ecosystem/06_dot_scitex_directory.md §11."
                 ),
             )
         )

scitex_dev-0.27.0/src/scitex_dev/_cli/audit/_project/_check_path_resolver.py

@@ -0,0 +1,145 @@
+"""PS-182 — rolled-own local-state path resolver.
+
+Implements the resolution-by-data-nature standard from
+`_skills/general/01_ecosystem/12_local-state-resolution.md`:
+
+  PS-182 — a package ships its own `src/<pkg>/**/_paths.py` (or
+           `paths.py`) that RE-IMPLEMENTS the project-scope / git-root
+           precedence walk — a `.git` sentinel walk plus a
+           `.scitex/<pkg-short>` project-scope literal — WITHOUT
+           importing the canonical
+           `scitex_config._ecosystem.local_state` helper.
+
+           Rolling your own precedence is the CONFIG-vs-DATA footgun:
+           `local_state.path()` legitimately lets a project scope shadow
+           the user scope for *config*, but a hand-rolled resolver
+           applies the same "project wins" rule to *data / state stores*
+           too. That is exactly how a week-stale
+           `<repo>/.scitex/todo/tasks.yaml` silently shadowed the
+           canonical `~/.scitex/todo/tasks.yaml` task store when a
+           process ran with its cwd inside the repo (2026-07 incident).
+
+           Fix: adopt `scitex_config._ecosystem.local_state` and pick the
+           resolver by DATA NATURE — `path()` for config,
+           `user_path()` for DATA/STATE stores (user-canonical, never
+           project-shadowed), `runtime_path()` for ephemera. See the
+           standard doc + PS-182 detail string.
+
+Deterministic + low-false-positive by design: the finding needs BOTH a
+git-root walk signal AND a `.scitex` project-scope literal in a file
+named `_paths.py` / `paths.py`, and is suppressed when the file already
+imports the canonical helper. A resolver that keys off a plain
+`$SCITEX_<PKG>_DIR` / `$SCITEX_BASE_DIR` env var without a `.git` walk
+(e.g. `scitex-app/paths.py`) is NOT flagged.
+
+b2 (a resolver whose chain orders project-scope ABOVE user-scope for a
+`.yaml`/`.db`/`.json` DATA store specifically) is intentionally DEFERRED:
+detecting store-nature + chain-order cleanly enough to stay
+low-false-positive is a separate refinement. PS-182 (b1) already flags
+the root cause — the rolled-own resolver — so b2 buys little today. See
+the standard doc §"Future refinement (b2)".
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+__all__ = ["check_ps182_rolled_own_path_resolver"]
+
+
+# A git-root walk: a named helper (`find_project_scope` / `_find_git_root`
+# / `_project_root`) OR a bare `.git` sentinel probe `(... / ".git").exists()`
+# / `.is_dir()`. Any one is enough — combined with the `.scitex` literal below
+# it is an unambiguous "I re-implemented project-scope resolution" signal.
+_GIT_WALK_RE = re.compile(
+    r"""(?:
+        find_project_scope
+      | _find_git_root
+      | _project_root
+      | ["']\.git["']\s*\)\s*\.\s*(?:exists|is_dir)
+    )""",
+    re.VERBOSE,
+)
+
+# A `.scitex` project-scope path literal (the `<repo>/.scitex/<pkg>` join).
+_SCITEX_LITERAL_RE = re.compile(r"""["']\.scitex["']""")
+
+# The canonical helper — its presence means the file delegates precedence
+# to `local_state` rather than rolling its own. Match the import/attribute
+# form so a stray mention in a comment is unlikely to exempt a real offender
+# (we require BOTH tokens).
+_CANONICAL_HELPER_RE = re.compile(r"\blocal_state\b")
+_CANONICAL_PKG_RE = re.compile(r"\bscitex_config\b")
+
+
+def _candidate_resolver_files(repo: Path) -> list[Path]:
+    """`src/**/_paths.py` and `src/**/paths.py` (gitignore-naive, cache-skip)."""
+    src = repo / "src"
+    if not src.is_dir():
+        return []
+    out: list[Path] = []
+    for p in src.rglob("*.py"):
+        if "__pycache__" in p.parts:
+            continue
+        if p.name in ("_paths.py", "paths.py"):
+            out.append(p)
+    return sorted(out)
+
+
+def _uses_canonical_helper(text: str) -> bool:
+    """True iff the file references `scitex_config` AND `local_state`.
+
+    Both tokens are required so a package that merely mentions one word in
+    an unrelated string does not get a free pass.
+    """
+    return bool(_CANONICAL_HELPER_RE.search(text) and _CANONICAL_PKG_RE.search(text))
+
+
+def check_ps182_rolled_own_path_resolver(
+    repo: Path,
+    violation_cls: type,
+    out: list,
+) -> None:
+    """Append one PS-182 violation per rolled-own local-state resolver file.
+
+    Fires when a `_paths.py` / `paths.py` under `src/`:
+      * shows a git-root walk signal (`_GIT_WALK_RE`), AND
+      * builds a `.scitex` project-scope path (`_SCITEX_LITERAL_RE`), AND
+      * does NOT import the canonical `scitex_config._ecosystem.local_state`
+        helper (`_uses_canonical_helper`).
+    """
+    for py in _candidate_resolver_files(repo):
+        try:
+            text = py.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if _uses_canonical_helper(text):
+            continue
+        if not _GIT_WALK_RE.search(text):
+            continue
+        if not _SCITEX_LITERAL_RE.search(text):
+            continue
+        out.append(
+            violation_cls(
+                "PS-182",
+                str(py),
+                (
+                    "rolls its own local-state precedence (a `.git`-root walk "
+                    "+ `.scitex/<pkg>` project-scope literal) instead of the "
+                    "canonical `scitex_config._ecosystem.local_state` helper. "
+                    "Project-scope shadowing is legitimate for CONFIG but a "
+                    "footgun for DATA/STATE stores: it silently shadowed the "
+                    "canonical `~/.scitex/todo/tasks.yaml` with a week-stale "
+                    "`<repo>/.scitex/todo/tasks.yaml` (2026-07). Adopt "
+                    "`local_state` and resolve by DATA NATURE — `path()` for "
+                    "config, `user_path()` for DATA/STATE stores "
+                    "(user-canonical, never project-shadowed), "
+                    "`runtime_path()` for ephemera. See _skills/general/"
+                    "01_ecosystem/12_local-state-resolution.md."
+                ),
+            )
+        )
+
+
+# EOF