claude-dev-env 8.85.0 → 8.85.2

package/scripts/deepstack_inventory.py

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+"""Diff the DeepStack retirement manifest against the active tree.
+
+Each row names a retired path, the behavior it required, the trigger that
+covers it, and the requirement that stays. The eval row keeps a
+reproducible check. An instruction or a manifest cell that marks evals
+optional, or that drops that check, is a finding.
+
+This script reads the manifest and the active files. It does not rewrite them.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from active_capability_references import unresolved_active_capabilities
+from dev_env_scripts_constants.deepstack_inventory_constants import (
+    ALL_EVAL_OPTIONAL_MARKERS,
+    ALL_TRUST_CARD_LINES,
+    DEEPSTACK_SECTION_HEADING,
+    DEEPSTACK_SKILL_RELATIVE_PATH,
+    EVAL_GUIDE_PATH_SUFFIX,
+    FINDING_BEHAVIOR_STILL_ACTIVE,
+    FINDING_DROPS_FIRST_ACTION_NOTE,
+    FINDING_DROPS_REPRODUCIBLE_CHECK,
+    FINDING_DROPS_TRUST_LINE,
+    FINDING_MARKS_EVALS_OPTIONAL,
+    FINDING_TRIGGER_MISSING,
+    FIRST_ACTION_BEHAVIOR_PREFIX,
+    FIRST_ACTION_RETIRED_SENTENCE,
+    MANIFEST_RELATIVE_PATH,
+    PATH_NONE,
+    REPRODUCIBLE_CHECK_SENTENCE,
+    RETIRED_PATH_HEADER,
+    SHORTEST_BACKTICKED_CELL,
+    TABLE_COLUMN_COUNT,
+    UTF8_ENCODING,
+)
+
+
+@dataclass(frozen=True)
+class ReplacementRow:
+    """One retired behavior and the trigger that covers it."""
+
+    retired_path: str
+    behavior: str
+    trigger: str
+    requirement_that_stays: str
+
+
+@dataclass(frozen=True)
+class InventoryFinding:
+    """One place the active tree still carries a retired behavior."""
+
+    retired_path: str
+    code: str
+    detail: str
+
+
+def _unquote(cell: str) -> str:
+    text = cell.strip()
+    if len(text) >= SHORTEST_BACKTICKED_CELL and text.startswith("`") and text.endswith("`"):
+        return text[1:-1]
+    return text
+
+
+def _table_cells(line: str) -> tuple[str, ...] | None:
+    stripped = line.strip()
+    if not stripped.startswith("|"):
+        return None
+    cells = [_unquote(each_cell) for each_cell in stripped.strip("|").split("|")]
+    if len(cells) != TABLE_COLUMN_COUNT:
+        return None
+    if cells[0].startswith("-") or cells[0].lower() == RETIRED_PATH_HEADER:
+        return None
+    return tuple(cells)
+
+
+def _row_from_line(each_line: str) -> ReplacementRow | None:
+    cells = _table_cells(each_line)
+    if cells is None:
+        return None
+    return ReplacementRow(
+        retired_path=cells[0],
+        behavior=cells[1],
+        trigger=cells[2],
+        requirement_that_stays=cells[3],
+    )
+
+
+def replacement_rows(manifest_text: str) -> tuple[ReplacementRow, ...]:
+    """Return the rows under the DeepStack heading, or none when it is absent.
+
+    Args:
+        manifest_text: The archive manifest text.
+
+    Returns:
+        One row per table line under the heading.
+    """
+    all_lines = manifest_text.splitlines()
+    is_in_section = False
+    all_rows: list[ReplacementRow] = []
+    for each_line in all_lines:
+        if each_line.startswith(DEEPSTACK_SECTION_HEADING):
+            is_in_section = True
+            continue
+        if is_in_section and each_line.startswith("## "):
+            break
+        if not is_in_section:
+            continue
+        each_row = _row_from_line(each_line)
+        if each_row is None:
+            continue
+        all_rows.append(each_row)
+    return tuple(all_rows)
+
+
+def _is_eval_retirement(row: ReplacementRow) -> bool:
+    return row.retired_path.endswith(EVAL_GUIDE_PATH_SUFFIX) or row.behavior.startswith(
+        FIRST_ACTION_BEHAVIOR_PREFIX
+    )
+
+
+def _optional_eval_finding(
+    each_text: str, each_surface: str, retired_path: str
+) -> InventoryFinding | None:
+    """Return a finding when the text marks evals optional."""
+    lowered = each_text.lower()
+    if any(each_marker in lowered for each_marker in ALL_EVAL_OPTIONAL_MARKERS):
+        return InventoryFinding(
+            retired_path=retired_path,
+            code=FINDING_MARKS_EVALS_OPTIONAL,
+            detail=each_surface,
+        )
+    return None
+
+
+def _dropped_check_finding(
+    each_text: str, each_surface: str, retired_path: str
+) -> InventoryFinding | None:
+    """Return a finding when the reproducible-check sentence is absent."""
+    if REPRODUCIBLE_CHECK_SENTENCE in each_text:
+        return None
+    return InventoryFinding(
+        retired_path=retired_path,
+        code=FINDING_DROPS_REPRODUCIBLE_CHECK,
+        detail=each_surface,
+    )
+
+
+def _trust_line_findings(
+    each_text: str, each_surface: str, retired_path: str
+) -> tuple[InventoryFinding, ...]:
+    """Return one finding per trust-card line the text omits."""
+    all_findings: list[InventoryFinding] = []
+    for each_trust_line in ALL_TRUST_CARD_LINES:
+        if each_trust_line not in each_text:
+            all_findings.append(
+                InventoryFinding(
+                    retired_path=retired_path,
+                    code=FINDING_DROPS_TRUST_LINE,
+                    detail=f"{each_surface}:{each_trust_line}",
+                )
+            )
+    return tuple(all_findings)
+
+
+def _surface_findings(
+    each_text: str, each_surface: str, retired_path: str
+) -> tuple[InventoryFinding, ...]:
+    """Return the optional-eval, dropped-check, and trust-line findings for one surface."""
+    all_findings: list[InventoryFinding] = []
+    optional_eval = _optional_eval_finding(each_text, each_surface, retired_path)
+    if optional_eval is not None:
+        all_findings.append(optional_eval)
+    dropped_check = _dropped_check_finding(each_text, each_surface, retired_path)
+    if dropped_check is not None:
+        all_findings.append(dropped_check)
+    all_findings.extend(_trust_line_findings(each_text, each_surface, retired_path))
+    return tuple(all_findings)
+
+
+def eval_retirement_findings(
+    instruction_text: str, requirement_text: str, retired_path: str
+) -> tuple[InventoryFinding, ...]:
+    """Reject an eval retirement that makes the reproducible check optional.
+
+    Args:
+        instruction_text: The active instruction the row points at.
+        requirement_text: The manifest cell for the requirement that stays.
+        retired_path: Path named by the row, used on each finding.
+
+    Returns:
+        Findings for an optional eval or a dropped reproducible check.
+    """
+    all_findings: list[InventoryFinding] = []
+    for each_text, each_surface in (
+        (instruction_text, "instruction"),
+        (requirement_text, "manifest"),
+    ):
+        all_findings.extend(_surface_findings(each_text, each_surface, retired_path))
+    if FIRST_ACTION_RETIRED_SENTENCE not in requirement_text:
+        all_findings.append(
+            InventoryFinding(
+                retired_path=retired_path,
+                code=FINDING_DROPS_FIRST_ACTION_NOTE,
+                detail="manifest",
+            )
+        )
+    return tuple(all_findings)
+
+
+def _read_text(path: Path) -> str:
+    if not path.is_file():
+        return ""
+    return path.read_text(encoding=UTF8_ENCODING)
+
+
+def _instruction_text(package_root: Path, retired_path: str) -> str:
+    """Return the active file for a retired path, or empty text for the none row."""
+    if retired_path == PATH_NONE:
+        return ""
+    return _read_text(package_root / retired_path)
+
+
+def _missing_trigger_finding(
+    each_row: ReplacementRow, skill_text: str
+) -> InventoryFinding | None:
+    if each_row.trigger in skill_text:
+        return None
+    return InventoryFinding(
+        retired_path=each_row.retired_path,
+        code=FINDING_TRIGGER_MISSING,
+        detail=each_row.trigger,
+    )
+
+
+def _live_behavior_finding(
+    each_row: ReplacementRow, instruction_text: str
+) -> InventoryFinding | None:
+    if not each_row.behavior or each_row.behavior not in instruction_text:
+        return None
+    return InventoryFinding(
+        retired_path=each_row.retired_path,
+        code=FINDING_BEHAVIOR_STILL_ACTIVE,
+        detail=each_row.behavior,
+    )
+
+
+def _row_findings(
+    package_root: Path, each_row: ReplacementRow, skill_text: str
+) -> tuple[InventoryFinding, ...]:
+    """Return the trigger, behavior, and eval findings for one manifest row."""
+    instruction_text = _instruction_text(package_root, each_row.retired_path)
+    all_findings: list[InventoryFinding] = []
+    missing_trigger = _missing_trigger_finding(each_row, skill_text)
+    if missing_trigger is not None:
+        all_findings.append(missing_trigger)
+    live_behavior = _live_behavior_finding(each_row, instruction_text)
+    if live_behavior is not None:
+        all_findings.append(live_behavior)
+    if _is_eval_retirement(each_row):
+        all_findings.extend(
+            eval_retirement_findings(
+                instruction_text,
+                each_row.requirement_that_stays,
+                each_row.retired_path,
+            )
+        )
+    return tuple(all_findings)
+
+
+def findings_for_rows(
+    package_root: Path,
+    all_rows: tuple[ReplacementRow, ...],
+    skill_text: str,
+) -> tuple[InventoryFinding, ...]:
+    """Return findings for retired behaviors that the active tree still requires.
+
+    Args:
+        package_root: Package directory that holds the active files.
+        all_rows: Manifest rows under the DeepStack heading.
+        skill_text: Install note that must name each trigger.
+
+    Returns:
+        Findings for missing triggers, live behaviors, and eval rows.
+    """
+    all_findings: list[InventoryFinding] = []
+    for each_row in all_rows:
+        all_findings.extend(_row_findings(package_root, each_row, skill_text))
+    return tuple(all_findings)
+
+
+def inventory_findings(package_root: Path) -> tuple[InventoryFinding, ...]:
+    """Return DeepStack findings plus leftover retired capability names.
+
+    Args:
+        package_root: Package directory that holds the manifest and the active files.
+
+    Returns:
+        Findings from the manifest rows and from leftover retired capability names.
+    """
+    manifest_text = _read_text(package_root / MANIFEST_RELATIVE_PATH)
+    all_rows = replacement_rows(manifest_text)
+    skill_text = _read_text(package_root / DEEPSTACK_SKILL_RELATIVE_PATH)
+    all_findings = list(findings_for_rows(package_root, all_rows, skill_text))
+    for each_reference in unresolved_active_capabilities(package_root):
+        all_findings.append(
+            InventoryFinding(
+                retired_path=each_reference.file_path,
+                code="retired-capability",
+                detail=each_reference.capability_name,
+            )
+        )
+    return tuple(all_findings)
+
+
+def _format_finding(finding: InventoryFinding) -> str:
+    return f"{finding.retired_path}: {finding.code}: {finding.detail}"
+
+
+def main(all_arguments: list[str]) -> int:
+    """Print each finding and return 1 when the active tree fails the manifest.
+
+    Args:
+        all_arguments: Command-line arguments, without the program name.
+
+    Returns:
+        0 when the tree has no findings, and 1 when it has any.
+    """
+    parser = argparse.ArgumentParser(description=__doc__, allow_abbrev=False)
+    parser.add_argument(
+        "--package-root",
+        type=Path,
+        default=Path(__file__).resolve().parent.parent,
+    )
+    arguments = parser.parse_args(all_arguments)
+    all_findings = inventory_findings(arguments.package_root)
+    for each_finding in all_findings:
+        sys.stdout.write(_format_finding(each_finding) + "\n")
+    return 1 if all_findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/scripts/dev_env_scripts_constants/deepstack_inventory_constants.py

@@ -0,0 +1,42 @@
+"""Constants for the DeepStack retirement inventory."""
+
+from __future__ import annotations
+
+UTF8_ENCODING: str = "utf-8"
+SHORTEST_BACKTICKED_CELL: int = 2
+TABLE_COLUMN_COUNT: int = 4
+MANIFEST_RELATIVE_PATH: str = "rules-archived/ARCHIVE-MANIFEST.md"
+DEEPSTACK_SECTION_HEADING: str = "## DeepStack replacements"
+DEEPSTACK_SKILL_RELATIVE_PATH: str = "docs/decisions/deepstack-install.md"
+EVAL_GUIDE_PATH_SUFFIX: str = "features-start-with-an-eval.md"
+FIRST_ACTION_BEHAVIOR_PREFIX: str = "Your first action is the Skill tool"
+RETIRED_PATH_HEADER: str = "retired path"
+PATH_NONE: str = "none"
+REQUIREMENT_NONE: str = "none"
+REPRODUCIBLE_CHECK_SENTENCE: str = (
+    "A reproducible, re-runnable check is still required before any done claim."
+)
+FIRST_ACTION_RETIRED_SENTENCE: str = (
+    "Only the forced position as the very first action is retired."
+)
+ALL_TRUST_CARD_LINES: tuple[str, ...] = (
+    "Red before the fix",
+    "wrong twin fails",
+    "undo fails again",
+)
+ALL_EVAL_OPTIONAL_MARKERS: tuple[str, ...] = (
+    "evals are optional",
+    "eval is optional",
+    "evals optional",
+    "optional eval",
+    "reproducible check is removed",
+    "reproducible check is retired",
+    "no reproducible check",
+    "without a reproducible check",
+)
+FINDING_BEHAVIOR_STILL_ACTIVE: str = "behavior-still-active"
+FINDING_TRIGGER_MISSING: str = "trigger-missing"
+FINDING_MARKS_EVALS_OPTIONAL: str = "marks-evals-optional"
+FINDING_DROPS_REPRODUCIBLE_CHECK: str = "drops-reproducible-check"
+FINDING_DROPS_TRUST_LINE: str = "drops-trust-line"
+FINDING_DROPS_FIRST_ACTION_NOTE: str = "drops-first-action-retired-note"

package/scripts/test_deepstack_inventory.py

@@ -0,0 +1,137 @@
+"""The inventory rejects an eval retirement that drops the reproducible check."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+from deepstack_inventory import (
+    findings_for_rows,
+    inventory_findings,
+    replacement_rows,
+    eval_retirement_findings,
+)
+from dev_env_scripts_constants.deepstack_inventory_constants import (
+    FINDING_BEHAVIOR_STILL_ACTIVE,
+    FINDING_DROPS_REPRODUCIBLE_CHECK,
+    FINDING_MARKS_EVALS_OPTIONAL,
+    REPRODUCIBLE_CHECK_SENTENCE,
+)
+
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent
+_KEPT_REQUIREMENT = (
+    f"{REPRODUCIBLE_CHECK_SENTENCE} "
+    "Red before the fix, the wrong twin fails, and undo fails again. "
+    "Only the forced position as the very first action is retired."
+)
+_KEPT_INSTRUCTION = (
+    "The DeepStack reproducible-check leaf calls this guide after intake. "
+    f"{_KEPT_REQUIREMENT}"
+)
+_FIRST_ACTION = (
+    "Your first action is the Skill tool with skill `claude-api` and args `build-eval`"
+)
+
+
+def _row_block(requirement: str, instruction_phrase: str) -> str:
+    return textwrap.dedent(
+        f"""\
+        ## DeepStack replacements
+
+        | Retired path | Behavior it required | Trigger that replaces it | Requirement that stays |
+        |---|---|---|---|
+        | docs/rule-guides/features-start-with-an-eval.md | {instruction_phrase} | DeepStack reproducible-check leaf | {requirement} |
+        """
+    )
+
+
+def test_should_reject_an_instruction_that_marks_evals_optional() -> None:
+    findings = eval_retirement_findings(
+        "Evals are optional before a done claim.",
+        "Evals are optional. The reproducible check is removed.",
+        "docs/rule-guides/features-start-with-an-eval.md",
+    )
+    assert any(each.code == FINDING_MARKS_EVALS_OPTIONAL for each in findings)
+    assert any(each.code == FINDING_DROPS_REPRODUCIBLE_CHECK for each in findings)
+
+
+def test_should_reject_a_manifest_that_removes_the_reproducible_check() -> None:
+    findings = eval_retirement_findings(
+        _KEPT_INSTRUCTION,
+        "Only the forced position as the very first action is retired.",
+        "docs/rule-guides/features-start-with-an-eval.md",
+    )
+    manifest_drops = [
+        each
+        for each in findings
+        if each.code == FINDING_DROPS_REPRODUCIBLE_CHECK and each.detail == "manifest"
+    ]
+    assert manifest_drops
+
+
+def test_should_accept_a_retirement_that_keeps_the_reproducible_check() -> None:
+    assert eval_retirement_findings(
+        _KEPT_INSTRUCTION,
+        _KEPT_REQUIREMENT,
+        "docs/rule-guides/features-start-with-an-eval.md",
+    ) == ()
+
+
+def test_should_reject_a_tree_whose_guide_still_orders_the_first_action(tmp_path: Path) -> None:
+    package_root = tmp_path
+    guide = package_root / "docs" / "rule-guides" / "features-start-with-an-eval.md"
+    guide.parent.mkdir(parents=True)
+    guide.write_text(f"{_FIRST_ACTION}. Build the feature.\n", encoding="utf-8")
+    skill = package_root / "docs" / "decisions" / "deepstack-install.md"
+    skill.parent.mkdir(parents=True)
+    skill.write_text("DeepStack reproducible-check leaf\n", encoding="utf-8")
+    manifest = package_root / "rules-archived" / "ARCHIVE-MANIFEST.md"
+    manifest.parent.mkdir(parents=True)
+    manifest.write_text(_row_block(_KEPT_REQUIREMENT, _FIRST_ACTION), encoding="utf-8")
+    all_rows = replacement_rows(manifest.read_text(encoding="utf-8"))
+    findings = findings_for_rows(package_root, all_rows, skill.read_text(encoding="utf-8"))
+    assert any(each.code == FINDING_BEHAVIOR_STILL_ACTIVE for each in findings)
+    assert any(each.code == FINDING_DROPS_REPRODUCIBLE_CHECK for each in findings)
+
+
+def test_should_accept_a_tree_that_retires_only_the_first_action(tmp_path: Path) -> None:
+    package_root = tmp_path
+    guide = package_root / "docs" / "rule-guides" / "features-start-with-an-eval.md"
+    guide.parent.mkdir(parents=True)
+    guide.write_text(_KEPT_INSTRUCTION + "\n", encoding="utf-8")
+    skill = package_root / "docs" / "decisions" / "deepstack-install.md"
+    skill.parent.mkdir(parents=True)
+    skill.write_text("DeepStack reproducible-check leaf\n", encoding="utf-8")
+    manifest = package_root / "rules-archived" / "ARCHIVE-MANIFEST.md"
+    manifest.parent.mkdir(parents=True)
+    manifest.write_text(_row_block(_KEPT_REQUIREMENT, _FIRST_ACTION), encoding="utf-8")
+    (package_root / ".agents" / "skills" / "kept").mkdir(parents=True)
+    (package_root / ".agents" / "skills" / "kept" / "SKILL.md").write_text(
+        "---\nname: kept\n---\n", encoding="utf-8"
+    )
+    (package_root / "bin").mkdir()
+    (package_root / "bin" / "ever-shipped-skills.mjs").write_text("'kept'\n", encoding="utf-8")
+    assert inventory_findings(package_root) == ()
+
+
+def test_install_citation_names_the_plugin_repository_and_the_triggers() -> None:
+    text = (_PACKAGE_ROOT / "docs" / "decisions" / "deepstack-install.md").read_text(encoding="utf-8")
+    assert "jl-cmd-projects/DeepStack" in text
+    assert "deepstack@DeepStack" in text
+    assert "DeepStack intake" in text
+    assert "DeepStack search leaf" in text
+    assert "DeepStack reproducible-check leaf" in text
+
+
+def test_live_package_inventory_exits_clean() -> None:
+    completed = subprocess.run(
+        [sys.executable, str(_PACKAGE_ROOT / "scripts" / "deepstack_inventory.py")],
+        capture_output=True,
+        text=True,
+        check=False,
+        cwd=str(_PACKAGE_ROOT),
+    )
+    assert completed.returncode == 0
+    assert completed.stdout == ""

package/scripts/test_deepstack_wording_rule.py

@@ -0,0 +1,20 @@
+"""The wording rule cites the first-task gate."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent
+
+
+def test_wording_rule_cites_the_gate() -> None:
+    rule_text = (_PACKAGE_ROOT / "rules" / "deepstack-wording.md").read_text(encoding="utf-8")
+    guide_text = (_PACKAGE_ROOT / "docs" / "rule-guides" / "deepstack-wording.md").read_text(
+        encoding="utf-8"
+    )
+    assert "hooks/session/deepen_first_prompt.py" in rule_text
+    assert "hooks/session/deepen_first_prompt.py" in guide_text
+    assert "SCOPE (role):" in guide_text
+    assert "EXAMPLES (illustration only):" in guide_text
+    assert "ZOOM-IN BLOCKER:" in guide_text
+    assert "DeepStack" in rule_text