claude-dev-env 8.1.0 → 8.3.0

package/scripts/active_capability_references.py

@@ -3,13 +3,15 @@
 
 Builds inventories from committed skill manifests, agent markdown files, and
 commands. Scans active prompt text for slash and backticked capability names.
-Fails when an active (non-inert) reference names a banned capability.
+Fails when an active (non-inert) reference names a capability the tree
+dropped, resolved from the ever-shipped registry against what the tree
+holds today.
 
 ::
 
     unresolved = unresolved_active_capabilities(package_root)
     ok: unresolved == []
-    flag: active text mentions /qbug or `stub-detector`
+    flag: active text mentions a name the tree dropped
 """
 
 from __future__ import annotations
@@ -19,10 +21,12 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from dev_env_scripts_constants.active_capability_constants import (
-    ALL_BANNED_ACTIVE_CAPABILITY_NAMES,
     ALL_INERT_FENCE_LANGUAGES,
-    BACKTICK_CAPABILITY_PATTERN,
-    BANNED_REASON_PREFIX,
+    ALL_QUALIFIED_CAPABILITY_PATTERNS,
+    ALL_UNREGISTERED_RETIRED_CAPABILITY_NAMES,
+    BLANKED_SPAN,
+    EVER_SHIPPED_NAME_PATTERN,
+    EVER_SHIPPED_REGISTRY_RELATIVE_PATH,
     FENCE_CLOSE_PATTERN,
     FENCE_OPEN_PATTERN,
     NEWLINE_JOIN_SEPARATOR,
@@ -31,8 +35,11 @@ from dev_env_scripts_constants.active_capability_constants import (
     PACKAGE_ROOT_AGENTS_DIRECTORY,
     PACKAGE_ROOT_SKILLS_DIRECTORY,
     PACKAGE_SKILLS_DIRECTORY,
+    RETIRED_REASON_PREFIX,
     SKILL_MANIFEST_FILENAME,
+    MULTI_SEGMENT_PATH_PATTERN,
     SLASH_CAPABILITY_PATTERN,
+    URL_PATTERN,
     UTF8_ENCODING,
 )
 
@@ -52,7 +59,7 @@ class CapabilityInventory:
 
 @dataclass(frozen=True)
 class UnresolvedCapabilityReference:
-    """One active reference that names a banned capability."""
+    """One active reference that names a capability outside the shipped tree."""
 
     file_path: str
     line_number: int
@@ -148,6 +155,10 @@ def strip_inert_fenced_blocks(markdown_text: str) -> str:
 def extract_active_capability_names(markdown_text: str) -> list[tuple[int, str]]:
     """Return (1-based line, capability name) for active references.
 
+    A slash reference counts as an invocation, and a qualified reference
+    names a skill directory or manifest. A URL and a multi-segment path
+    carry neither, so both are blanked before the scan.
+
     Args:
         markdown_text: Prompt or skill markdown.
 
@@ -155,31 +166,72 @@ def extract_active_capability_names(markdown_text: str) -> list[tuple[int, str]]
         Ordered list of line number and capability name pairs.
     """
     slash_pattern = re.compile(SLASH_CAPABILITY_PATTERN)
-    backtick_pattern = re.compile(BACKTICK_CAPABILITY_PATTERN)
+    url_pattern = re.compile(URL_PATTERN)
+    path_pattern = re.compile(MULTI_SEGMENT_PATH_PATTERN)
+    all_qualified_patterns = [
+        re.compile(each_pattern) for each_pattern in ALL_QUALIFIED_CAPABILITY_PATTERNS
+    ]
     active_text = strip_inert_fenced_blocks(markdown_text)
     all_hits: list[tuple[int, str]] = []
     for each_line_number, each_line in enumerate(active_text.splitlines(), start=1):
-        for each_match in slash_pattern.finditer(each_line):
-            all_hits.append((each_line_number, each_match.group(1)))
-        for each_match in backtick_pattern.finditer(each_line):
+        for each_pattern in all_qualified_patterns:
+            for each_match in each_pattern.finditer(each_line):
+                all_hits.append((each_line_number, each_match.group(1)))
+        invocation_line = path_pattern.sub(
+            BLANKED_SPAN, url_pattern.sub(BLANKED_SPAN, each_line)
+        )
+        for each_match in slash_pattern.finditer(invocation_line):
             all_hits.append((each_line_number, each_match.group(1)))
     return all_hits
 
 
-def classify_capability_reference(capability_name: str) -> str | None:
-    """Return a failure reason when the capability is banned.
+def retired_capability_names(
+    from_package_root: Path, inventory: CapabilityInventory
+) -> frozenset[str]:
+    """Return the capability names the shipped tree dropped.
 
-    Extractors also match ordinary prose tokens, so unknown names pass.
-    Only the ban list fails a reference.
+    The ever-shipped registry keeps every skill name the package released.
+    Subtracting what the tree holds today leaves the retired set, so no hand
+    kept list decides which name fails.
+
+    Args:
+        from_package_root: ``packages/claude-dev-env`` root.
+        inventory: Names the tree holds today.
+
+    Returns:
+        Retired capability names.
+    """
+    registry_path = from_package_root / EVER_SHIPPED_REGISTRY_RELATIVE_PATH
+    all_ever_shipped_names: set[str] = set(
+        ALL_UNREGISTERED_RETIRED_CAPABILITY_NAMES
+    )
+    if registry_path.is_file():
+        all_ever_shipped_names.update(
+            re.findall(
+                EVER_SHIPPED_NAME_PATTERN,
+                registry_path.read_text(encoding=UTF8_ENCODING),
+            )
+        )
+    return frozenset(all_ever_shipped_names - inventory.all_known_names())
+
+
+def classify_capability_reference(
+    capability_name: str, all_retired_names: frozenset[str]
+) -> str | None:
+    """Return a failure reason when the capability left the tree.
+
+    Extractors also match ordinary prose tokens, so a name the package never
+    shipped passes. A name the registry records and the tree dropped fails.
 
     Args:
         capability_name: Extracted skill/command-like name.
+        all_retired_names: Names resolved by ``retired_capability_names``.
 
     Returns:
         Reason string, or None when the reference is allowed.
     """
-    if capability_name in ALL_BANNED_ACTIVE_CAPABILITY_NAMES:
-        return f"{BANNED_REASON_PREFIX}{capability_name}"
+    if capability_name in all_retired_names:
+        return f"{RETIRED_REASON_PREFIX}{capability_name}"
     return None
 
 
@@ -188,7 +240,7 @@ def unresolved_active_capabilities(
     *,
     all_relative_markdown_paths: list[str] | None = None,
 ) -> list[UnresolvedCapabilityReference]:
-    """Scan package markdown for banned active capability references.
+    """Scan package markdown for references to retired capabilities.
 
     Args:
         from_package_root: ``packages/claude-dev-env`` root.
@@ -196,10 +248,13 @@ def unresolved_active_capabilities(
             defaults to all skills, agents, and commands markdown.
 
     Returns:
-        Banned references with file, line, name, and reason.
+        Retired references with file, line, name, and reason.
     """
     if all_relative_markdown_paths is None:
         all_relative_markdown_paths = _default_markdown_paths(from_package_root)
+    all_retired_names = retired_capability_names(
+        from_package_root, build_capability_inventory(from_package_root)
+    )
     all_unresolved: list[UnresolvedCapabilityReference] = []
     for each_relative_path in all_relative_markdown_paths:
         absolute_path = from_package_root / each_relative_path
@@ -209,7 +264,7 @@ def unresolved_active_capabilities(
         for each_line_number, each_name in extract_active_capability_names(
             markdown_text
         ):
-            reason = classify_capability_reference(each_name)
+            reason = classify_capability_reference(each_name, all_retired_names)
             if reason is None:
                 continue
             all_unresolved.append(

package/scripts/banned_prose_words.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Find banned emphasis words in authored prose.
+
+The package AGENTS.md bans ``real``, ``really``, ``real-world``, ``actual``,
+``actually``, ``genuine``, and ``true`` from every authored surface. This
+module reports each occurrence that survives after code spans, paths, and
+link targets are removed, so a caller can grade a document or a whole tree.
+
+::
+
+    all_hits = find_banned_prose_words("The real cause is a timeout.\n")
+    ok: all_hits == [(1, "real")]
+"""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+
+from dev_env_scripts_constants.banned_prose_word_constants import (
+    ADJECTIVAL_TRUE_PATTERN,
+    ALL_EXEMPT_PATH_SEGMENTS,
+    ALL_GOVERNED_PATH_SEGMENTS,
+    ALL_GOVERNED_SUFFIXES,
+    ALL_PREDICATIVE_TRUE_LEADS,
+    BANNED_PROSE_WORD_PATTERN,
+    BLANKED_SPAN,
+    FENCED_CODE_PATTERN,
+    INDENTED_CODE_PATTERN,
+    INLINE_CODE_PATTERN,
+    MARKDOWN_LINK_TARGET_PATTERN,
+    PATH_PATTERN,
+    URL_PATTERN,
+    UTF8_ENCODING,
+    XML_TAG_PATTERN,
+)
+
+
+def governs_path(relative_posix_path: str) -> bool:
+    """Return whether the ban applies to one repository path.
+
+    Args:
+        relative_posix_path: Repository-relative path with forward slashes.
+
+    Returns:
+        True for an authored instruction surface the ban covers.
+    """
+    normalized_path = f"/{relative_posix_path.lower().lstrip('/')}"
+    if PurePosixPath(normalized_path).suffix not in ALL_GOVERNED_SUFFIXES:
+        return False
+    if any(
+        each_segment in normalized_path for each_segment in ALL_EXEMPT_PATH_SEGMENTS
+    ):
+        return False
+    return any(
+        each_segment in normalized_path for each_segment in ALL_GOVERNED_PATH_SEGMENTS
+    )
+
+
+def prose_lines(document_text: str) -> list[str]:
+    """Return one prose line for each source line, with code spans blanked.
+
+    Args:
+        document_text: Full document source.
+
+    Returns:
+        Lines of the same count as the source, holding prose only.
+    """
+    all_prose_lines: list[str] = []
+    is_inside_fence = False
+    for each_line in document_text.splitlines():
+        if FENCED_CODE_PATTERN.match(each_line):
+            is_inside_fence = not is_inside_fence
+            all_prose_lines.append("")
+            continue
+        if is_inside_fence or INDENTED_CODE_PATTERN.match(each_line):
+            all_prose_lines.append("")
+            continue
+        prose_line = INLINE_CODE_PATTERN.sub(BLANKED_SPAN, each_line)
+        prose_line = XML_TAG_PATTERN.sub(BLANKED_SPAN, prose_line)
+        prose_line = MARKDOWN_LINK_TARGET_PATTERN.sub(BLANKED_SPAN, prose_line)
+        prose_line = URL_PATTERN.sub(BLANKED_SPAN, prose_line)
+        all_prose_lines.append(PATH_PATTERN.sub(BLANKED_SPAN, prose_line))
+    return all_prose_lines
+
+
+def _adjectival_true_columns(prose_line: str) -> list[int]:
+    all_columns: list[int] = []
+    for each_match in ADJECTIVAL_TRUE_PATTERN.finditer(prose_line):
+        leading_words = prose_line[: each_match.start()].lower().split()
+        if leading_words and leading_words[-1].strip(",;:(") in (
+            ALL_PREDICATIVE_TRUE_LEADS
+        ):
+            continue
+        all_columns.append(each_match.start() + 1)
+    return all_columns
+
+
+def find_banned_prose_words(document_text: str) -> list[tuple[int, int, str]]:
+    """Return each banned word occurrence in authored prose.
+
+    Args:
+        document_text: Full document source.
+
+    Returns:
+        Ordered ``(line number, column, word)`` triples, both 1-based.
+    """
+    all_hits: list[tuple[int, int, str]] = []
+    for each_line_number, each_prose_line in enumerate(prose_lines(document_text), 1):
+        for each_match in BANNED_PROSE_WORD_PATTERN.finditer(each_prose_line):
+            all_hits.append(
+                (each_line_number, each_match.start() + 1, each_match.group(1).lower())
+            )
+        for each_column in _adjectival_true_columns(each_prose_line):
+            all_hits.append((each_line_number, each_column, "true"))
+    return sorted(all_hits)
+
+
+def governed_paths(from_package_root: Path) -> list[str]:
+    """Return every governed surface under one package root.
+
+    Args:
+        from_package_root: ``packages/claude-dev-env`` root.
+
+    Returns:
+        Sorted package-relative paths the ban covers.
+    """
+    all_paths: list[str] = []
+    for each_path in from_package_root.rglob("*"):
+        if not each_path.is_file():
+            continue
+        relative_path = each_path.relative_to(from_package_root).as_posix()
+        if governs_path(relative_path):
+            all_paths.append(relative_path)
+    return sorted(all_paths)
+
+
+def banned_prose_words_in_tree(
+    from_package_root: Path,
+) -> list[tuple[str, int, int, str]]:
+    """Return every banned word occurrence across the governed surfaces.
+
+    Args:
+        from_package_root: ``packages/claude-dev-env`` root.
+
+    Returns:
+        Ordered ``(package-relative path, line number, column, word)`` tuples.
+    """
+    all_hits: list[tuple[str, int, int, str]] = []
+    for each_relative_path in governed_paths(from_package_root):
+        document_text = (from_package_root / each_relative_path).read_text(
+            encoding=UTF8_ENCODING, errors="replace"
+        )
+        for each_line_number, each_column, each_word in find_banned_prose_words(
+            document_text
+        ):
+            all_hits.append(
+                (each_relative_path, each_line_number, each_column, each_word)
+            )
+    return all_hits

package/scripts/dev_env_scripts_constants/active_capability_constants.py

@@ -14,18 +14,16 @@ PACKAGE_ROOT_SKILLS_DIRECTORY: str = "skills"
 PACKAGE_ROOT_AGENTS_DIRECTORY: str = "agents"
 SKILL_MANIFEST_FILENAME: str = "SKILL.md"
 
-# Slash-command and skill names that must never appear as active instructions.
-ALL_BANNED_ACTIVE_CAPABILITY_NAMES: frozenset[str] = frozenset(
+ALL_UNREGISTERED_RETIRED_CAPABILITY_NAMES: frozenset[str] = frozenset(
     {
         "stub-detector",
         "superpowers",
-        "qbug",
-        "findbugs",
-        "fixbugs",
-        "monitor-open-prs",
     }
 )
 
+EVER_SHIPPED_REGISTRY_RELATIVE_PATH: str = "bin/ever-shipped-skills.mjs"
+EVER_SHIPPED_NAME_PATTERN: str = r"'([a-z][a-z0-9-]*)'"
+
 # Fence languages treated as inert historical/example content.
 ALL_INERT_FENCE_LANGUAGES: frozenset[str] = frozenset(
     {
@@ -37,13 +35,17 @@ ALL_INERT_FENCE_LANGUAGES: frozenset[str] = frozenset(
     }
 )
 
-SLASH_CAPABILITY_PATTERN: str = r"(?<![`\w])/([a-z][a-z0-9-]{2,})"
-BACKTICK_CAPABILITY_PATTERN: str = (
-    r"`(?:skills/)?([a-z][a-z0-9-]{2,})(?:/SKILL\.md)?`"
+SLASH_CAPABILITY_PATTERN: str = r"(?<![`\w./-])/([a-z][a-z0-9-]{2,})(?![\w/-])"
+ALL_QUALIFIED_CAPABILITY_PATTERNS: tuple[str, ...] = (
+    r"(?<![\w-])([a-z][a-z0-9-]{2,})/SKILL\.md",
+    r"`skills/([a-z][a-z0-9-]{2,})`",
 )
+URL_PATTERN: str = r"\b[a-z][a-z0-9+.-]*://\S+"
+MULTI_SEGMENT_PATH_PATTERN: str = r"(?<![\w-])[\w.{}-]*/[\w.{}/-]*/[\w.{}-]+"
+BLANKED_SPAN: str = " "
 FENCE_OPEN_PATTERN: str = r"^```([A-Za-z0-9_-]*)\s*$"
 FENCE_CLOSE_PATTERN: str = r"^```\s*$"
-BANNED_REASON_PREFIX: str = "banned_active_capability:"
+RETIRED_REASON_PREFIX: str = "retired_capability:"
 
 UTF8_ENCODING: str = "utf-8"
 NEWLINE_JOIN_SEPARATOR: str = "\n"

package/scripts/dev_env_scripts_constants/banned_prose_word_constants.py

@@ -0,0 +1,95 @@
+"""Constants for the banned-prose-word detector.
+
+The package AGENTS.md bans a family of emphasis words from every authored
+surface. These patterns describe where the ban applies and which spans of a
+document are code rather than prose.
+"""
+
+from __future__ import annotations
+
+import re
+
+UTF8_ENCODING: str = "utf-8"
+
+ALL_GOVERNED_PATH_SEGMENTS: tuple[str, ...] = (
+    "/.agents/agents/",
+    "/.agents/skills/",
+    "/audit-rubrics/",
+    "/commands/",
+    "/docs/",
+    "/output-styles/",
+    "/rules/",
+    "/system-prompts/",
+)
+
+ALL_EXEMPT_PATH_SEGMENTS: tuple[str, ...] = (
+    "-archived/",
+    "/fixtures/",
+    "/tests/",
+    "/changelog.md",
+)
+
+ALL_GOVERNED_SUFFIXES: frozenset[str] = frozenset({".md", ".mdx", ".xml"})
+
+ALL_BANNED_PROSE_WORDS: tuple[str, ...] = (
+    "real",
+    "really",
+    "real-world",
+    "actual",
+    "actually",
+    "genuine",
+    "genuinely",
+    "truly",
+)
+
+BANNED_PROSE_WORD_PATTERN: re.Pattern[str] = re.compile(
+    r"(?<![\w-])(" + "|".join(ALL_BANNED_PROSE_WORDS) + r")(?![\w-])",
+    re.IGNORECASE,
+)
+
+ADJECTIVAL_TRUE_PATTERN: re.Pattern[str] = re.compile(
+    r"(?<![\w-])true(?![\w-])\s+[a-z]", re.IGNORECASE
+)
+
+ALL_PREDICATIVE_TRUE_LEADS: frozenset[str] = frozenset(
+    {
+        "is",
+        "are",
+        "was",
+        "were",
+        "be",
+        "been",
+        "being",
+        "always",
+        "still",
+        "holds",
+        "hold",
+        "held",
+        "stays",
+        "stay",
+        "remains",
+        "remain",
+        "returns",
+        "return",
+        "reads",
+        "read",
+        "and",
+        "or",
+        "not",
+        "never",
+    }
+)
+
+FENCED_CODE_PATTERN: re.Pattern[str] = re.compile(r"^\s*```")
+INDENTED_CODE_PATTERN: re.Pattern[str] = re.compile(r"^(?: {4,}|\t)\S")
+INLINE_CODE_PATTERN: re.Pattern[str] = re.compile(r"`[^`]*`")
+URL_PATTERN: re.Pattern[str] = re.compile(r"\b(?:https?|file)://\S+")
+PATH_PATTERN: re.Pattern[str] = re.compile(r"(?<![\w])[\w./-]*/[\w./-]+")
+MARKDOWN_LINK_TARGET_PATTERN: re.Pattern[str] = re.compile(r"\]\([^)]*\)")
+XML_TAG_PATTERN: re.Pattern[str] = re.compile(r"<[^>]+>")
+BLANKED_SPAN: str = " "
+
+BANNED_PROSE_WORD_RULE_ID: str = "banned-prose-word"
+BANNED_PROSE_WORD_MESSAGE: str = (
+    "Banned word: {word}. Delete it and name the evidence instead."
+)

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -85,14 +85,14 @@ ROLE_BUGTEAM: str = "bugteam"
 """Role name whose agent definition set the preflight validates by default."""
 
 ROLE_CLEAN_CODER: str = "clean-coder"
-"""Role name that maps to the clean-coder agent for FIX and standards-fix."""
+"""Compatibility role for FIX and standards-fix using poteto-agent."""
 
 DEFAULT_ROLE: str = ROLE_BUGTEAM
 """Role applied when the caller does not pass ``--role``."""
 
 ALL_AGENT_FILENAMES_BY_ROLE: dict[str, tuple[str, ...]] = {
-    ROLE_BUGTEAM: ("code-quality-agent.md", "clean-coder.md"),
-    ROLE_CLEAN_CODER: ("clean-coder.md",),
+    ROLE_BUGTEAM: ("poteto-agent.md",),
+    ROLE_CLEAN_CODER: ("poteto-agent.md",),
 }
 """Agent definition filenames required under ``agents/`` for each known role."""
 

package/scripts/grok_headless_runner.py

@@ -19,7 +19,7 @@ Import ``run_headless_worker`` for the outcome object::
         working_directory=cwd,
         run_state_directory=run_dir,
         timeout_seconds=5400,
-        agent_name="code-quality-agent",
+        agent_name="poteto-agent",
     )
 """
 
@@ -72,6 +72,7 @@ from dev_env_scripts_constants.grok_worker_constants import (
     WORKER_SPEC_TIMEOUT_KEY,
 )
 from shared_tree_paths import resolve_shared_process_tree_scripts_directory
+from grok_worker_preflight import poteto_mode_skill_path
 
 _shared_process_tree_scripts_directory = resolve_shared_process_tree_scripts_directory(
     __file__,
@@ -420,6 +421,23 @@ def run_headless_worker(
         if leader_socket_path is not None
         else _mint_leader_socket_path(run_state_directory)
     )
+    if agent_name == "poteto-agent":
+        try:
+            skill_path = poteto_mode_skill_path().resolve()
+            skill_text = skill_path.read_text(encoding=UTF8_ENCODING)
+            task_text = prompt_file.read_text(encoding=UTF8_ENCODING)
+            run_state_directory.mkdir(parents=True, exist_ok=True)
+            prompt_file = run_state_directory / f"{resolved_leader_socket_path.stem}-poteto.txt"
+            prompt_file.write_text(
+                f"Poteto skill source: {skill_path}\n"
+                "Resolve companion skill paths against that source directory.\n"
+                "The task below defines your review, build, or translation duty. "
+                "Preserve its scope, write permissions, and report contract.\n\n"
+                f"{skill_text}\n\nTask:\n{task_text}",
+                encoding=UTF8_ENCODING,
+            )
+        except OSError as error:
+            return _launch_failure_outcome(error)
     all_arguments = _build_invocation(
         prompt_file=prompt_file,
         working_directory=working_directory,

package/scripts/grok_worker_preflight.py

@@ -45,6 +45,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import shutil
 import subprocess
 import sys
@@ -61,6 +62,7 @@ from dev_env_scripts_constants.grok_worker_constants import (
     CLAUDE_HOME_SUBDIRECTORY,
     CLI_PING_FLAG,
     CLI_ROLE_FLAG,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
     CLI_RUN_STATE_DIR_FLAG,
     DEFAULT_AUTH_TIMEOUT_SECONDS,
     DEFAULT_PING_TIMEOUT_SECONDS,
@@ -111,7 +113,67 @@ class PreflightOutcome:
 
 def claude_config_home() -> Path:
     """Return the per-user Claude configuration directory."""
-    return Path.home() / CLAUDE_HOME_SUBDIRECTORY
+    configured_root = os.environ.get(CLAUDE_CONFIG_DIR_ENV_VAR)
+    return Path(configured_root) if configured_root else Path.home() / CLAUDE_HOME_SUBDIRECTORY
+
+
+def _read_pstack_registry(registry_path: Path) -> dict[str, object]:
+    try:
+        registry = json.loads(registry_path.read_text(encoding=UTF8_ENCODING))
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise OSError(f"Invalid pstack installation registry {registry_path}: {error}") from error
+    if not isinstance(registry, dict):
+        raise OSError(f"Invalid pstack installation registry {registry_path}: root must be an object")
+    return registry
+
+
+def _user_pstack_entries(all_registry: dict[str, object], registry_path: Path) -> list[dict[str, object]]:
+    plugins = all_registry.get("plugins")
+    if not isinstance(plugins, dict):
+        raise OSError(f"Invalid pstack installation registry {registry_path}: plugins must be an object")
+    entries = plugins.get("pstack@pstack-claude", [])
+    if not isinstance(entries, list) or any(not isinstance(entry, dict) for entry in entries):
+        raise OSError(f"Invalid pstack installation registry {registry_path}: pstack entries must be objects")
+    user_entries = [entry for entry in entries if entry.get("scope") == "user"]
+    if len(user_entries) > 1:
+        raise OSError(f"Invalid pstack installation registry {registry_path}: multiple user pstack installations")
+    return user_entries
+
+
+def _native_pstack_skill_path(registry_path: Path, fallback_path: Path) -> Path:
+    if not registry_path.exists():
+        return fallback_path
+    user_entries = _user_pstack_entries(_read_pstack_registry(registry_path), registry_path)
+    if not user_entries:
+        return fallback_path
+    install_path = user_entries[0].get("installPath")
+    if not isinstance(install_path, str) or not Path(install_path).is_absolute():
+        raise OSError(f"Invalid pstack installation registry {registry_path}: pstack installPath must be absolute")
+    return Path(install_path) / "skills" / "poteto-mode" / "SKILL.md"
+
+
+def poteto_mode_skill_path() -> Path:
+    """Return the selected installed pstack poteto-mode skill path.
+
+    Returns:
+        The validated poteto-mode skill path.
+
+    Raises:
+        OSError: If the registry or selected skill is invalid.
+    """
+    config_root = claude_config_home()
+    fallback_path = config_root / "skills" / "poteto-mode" / "SKILL.md"
+    skill_path = _native_pstack_skill_path(
+        config_root / "plugins" / "installed_plugins.json",
+        fallback_path,
+    )
+    try:
+        skill_text = skill_path.read_text(encoding=UTF8_ENCODING)
+    except UnicodeError as error:
+        raise OSError(f"Invalid UTF-8 poteto skill {skill_path}") from error
+    if not skill_text.strip():
+        raise OSError(f"Empty poteto skill {skill_path}")
+    return skill_path
 
 
 def _install_manifest_path() -> Path:
@@ -218,6 +280,10 @@ def _is_grok_binary_resolvable() -> bool:
 def _is_claude_dev_env_config_present(role: str) -> bool:
     if not _install_manifest_path().is_file():
         return False
+    try:
+        poteto_mode_skill_path()
+    except OSError:
+        return False
     all_agent_filenames = ALL_AGENT_FILENAMES_BY_ROLE.get(role)
     if all_agent_filenames is None:
         return False

package/scripts/policy_lint/adapter_retired_hook_prose.py

@@ -15,23 +15,33 @@ from .config import constants
 from .model import Diagnostic, Document, Location, Severity
 
 
-def accepts_rules_markdown(document: Document) -> bool:
-    """Return whether the document is Markdown in a rules directory.
+def accepts_instruction_markdown(document: Document) -> bool:
+    """Return whether the document is authored instruction Markdown.
+
+    Rules, skills, agents, commands, documentation and stored system prompts
+    all describe hooks to a reader, so each one carries the same claim.
 
     Args:
         document: Candidate document.
 
     Returns:
-        True for a Markdown file directly under a ``rules`` directory.
+        True for Markdown on an instruction surface.
     """
-    return (
-        document.path.suffix.lower() in constants.ALL_MARKDOWN_SUFFIXES
-        and document.path.parent.name == constants.RULES_DIRECTORY_NAME
+    if document.path.suffix.lower() not in constants.ALL_MARKDOWN_SUFFIXES:
+        return False
+    normalized_path = f"/{document.path.as_posix().lower()}"
+    return any(
+        each_segment in normalized_path
+        for each_segment in constants.ALL_HOOK_PROSE_SURFACE_SEGMENTS
     )
 
 
 def _package_root(repository_root: Path, document: Document) -> Path:
-    return repository_root / document.path.parent.parent.as_posix()
+    for each_ancestor in document.path.parents:
+        candidate_root = repository_root / each_ancestor.as_posix()
+        if (candidate_root / constants.HOOKS_DIRECTORY_NAME).is_dir():
+            return candidate_root
+    return repository_root / document.path.parent.as_posix()
 
 
 def _read_text(path: Path) -> str: