claude-dev-env 8.0.0 → 8.2.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/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:

package/scripts/policy_lint/adapters.py

@@ -427,25 +427,25 @@ def accepts_plans(document: Document) -> bool:
     )
 
 
-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.
 
     Args:
         document: Candidate document.
 
     Returns:
-        True for a Markdown file directly under a ``rules`` directory.
+        True for Markdown on an instruction surface.
     """
-    return adapter_retired_hook_prose.accepts_rules_markdown(document)
+    return adapter_retired_hook_prose.accepts_instruction_markdown(document)
 
 
 def retired_hook_prose_diagnostics(
     document: Document, repository_root: Path
 ) -> tuple[Diagnostic, ...]:
-    """Report rules prose that credits an unregistered hook with a live action.
+    """Report instruction prose that credits an unregistered hook with a live action.
 
     Args:
-        document: Current rules Markdown text and path.
+        document: Current instruction Markdown text and path.
         repository_root: Request repository root for package resolution.
 
     Returns:

package/scripts/policy_lint/config/constants.py

@@ -92,6 +92,14 @@ VIOLATION_SCOPING_MODULE_NAME = "code_rules_gate_parts.violation_scoping"
 
 RETIRED_HOOK_PROSE_RULE_ID = "retired-hook-prose"
 RULES_DIRECTORY_NAME = "rules"
+ALL_HOOK_PROSE_SURFACE_SEGMENTS = (
+    "/.agents/",
+    "/commands/",
+    "/docs/",
+    "/output-styles/",
+    "/rules/",
+    "/system-prompts/",
+)
 HOOKS_DIRECTORY_NAME = "hooks"
 HOOKS_CONFIGURATION_FILE_NAME = "hooks.json"
 HOOK_CONSTANTS_DIRECTORY_NAME = "hooks_constants"

package/scripts/policy_lint/registry.py

@@ -106,7 +106,7 @@ def _text_document_rules() -> tuple[model.Rule, ...]:
         ),
         build_document_rule(
             "retired-hook-prose",
-            adapters.accepts_rules_markdown,
+            adapters.accepts_instruction_markdown,
             adapters.retired_hook_prose_diagnostics,
         ),
     )

package/scripts/sync_to_cursor/rules.py

@@ -73,7 +73,7 @@ _merged_mapping_key_order = (
 _code_standards_section_order = (
     "COMMENT PRESERVATION",
     "CORE PRINCIPLES",
-    "⚡ HOOK-ENFORCED RULES",
+    "⚡ LINT-ENFORCED RULES",
     "3. REUSE CONSTANTS / 4. CONFIG LOCATIONS",
     "5. NO ABBREVIATIONS",
     "6. COMPLETE TYPE HINTS",