claude-dev-env 1.65.0 → 1.66.0

package/hooks/blocking/test_code_rules_enforcer_split_test_assertions.py

@@ -6,6 +6,8 @@ import sys
 from pathlib import Path
 from types import SimpleNamespace
 
+import pytest
+
 _BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent)
 _HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
 if _BLOCKING_DIRECTORY not in sys.path:
@@ -15,14 +17,34 @@ if _HOOKS_DIRECTORY not in sys.path:
 
 from code_rules_test_assertions import (  # noqa: E402
     check_constant_equality_tests,
+    check_flag_gated_scenario_test_naming,
 )
 
 code_rules_enforcer = SimpleNamespace(
     check_constant_equality_tests=check_constant_equality_tests,
+    check_flag_gated_scenario_test_naming=check_flag_gated_scenario_test_naming,
 )
 
 
 CONSTANT_EQUALITY_TEST_FILE_PATH = "packages/app/tests/test_constants.py"
+SCENARIO_TEST_FILE_PATH = "packages/app/tests/test_submission_runner_loop.py"
+
+_THREE_SIBLINGS_PATCH_THE_FLAG_ONE_SCENARIO_TEST_DOES_NOT = (
+    "def test_should_submit_when_gate_passes(monkeypatch) -> None:\n"
+    "    assert run() == 'submitted'\n"
+    "\n"
+    "def test_should_fail_when_reader_raises(monkeypatch) -> None:\n"
+    "    monkeypatch.setattr('pkg.pipeline.IS_STAGED_VERIFICATION_ENABLED', True)\n"
+    "    assert run() == 'failed'\n"
+    "\n"
+    "def test_should_soft_skip_when_mismatch(monkeypatch) -> None:\n"
+    "    monkeypatch.setattr('pkg.pipeline.IS_STAGED_VERIFICATION_ENABLED', True)\n"
+    "    assert run() == 'skipped'\n"
+    "\n"
+    "def test_should_hard_stop_when_unhealthy(monkeypatch) -> None:\n"
+    "    monkeypatch.setattr('pkg.pipeline.IS_STAGED_VERIFICATION_ENABLED', True)\n"
+    "    assert run() == 'hard_stop'\n"
+)
 
 
 def test_should_not_flag_two_named_constants_compared_to_each_other() -> None:
@@ -54,3 +76,71 @@ def test_should_flag_named_constant_compared_to_literal() -> None:
     assert any("constant-value test" in issue for issue in issues), (
         f"Expected flag when UPPER_SNAKE compared to literal, got: {issues}"
     )
+
+
+def test_should_advise_when_scenario_test_omits_flag_its_siblings_patch(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    issues = code_rules_enforcer.check_flag_gated_scenario_test_naming(
+        _THREE_SIBLINGS_PATCH_THE_FLAG_ONE_SCENARIO_TEST_DOES_NOT,
+        SCENARIO_TEST_FILE_PATH,
+    )
+    advisory_text = capsys.readouterr().err
+    assert issues == [], "Advisory check must never add a blocking issue"
+    assert "test_should_submit_when_gate_passes" in advisory_text, (
+        f"Expected an advisory naming the un-patched scenario test, got: {advisory_text!r}"
+    )
+    assert "IS_STAGED_VERIFICATION_ENABLED" in advisory_text, (
+        f"Expected the advisory to name the established flag, got: {advisory_text!r}"
+    )
+
+
+def test_should_stay_silent_when_scenario_test_patches_the_flag(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    source = (
+        "def test_should_submit_when_gate_passes(monkeypatch) -> None:\n"
+        "    monkeypatch.setattr('pkg.pipeline.IS_STAGED_VERIFICATION_ENABLED', True)\n"
+        "    assert run() == 'submitted'\n"
+        "\n"
+        "def test_should_fail_when_reader_raises(monkeypatch) -> None:\n"
+        "    monkeypatch.setattr('pkg.pipeline.IS_STAGED_VERIFICATION_ENABLED', True)\n"
+        "    assert run() == 'failed'\n"
+    )
+    issues = code_rules_enforcer.check_flag_gated_scenario_test_naming(
+        source, SCENARIO_TEST_FILE_PATH
+    )
+    advisory_text = capsys.readouterr().err
+    assert issues == []
+    assert advisory_text == "", (
+        f"Expected silence when the scenario test patches the flag, got: {advisory_text!r}"
+    )
+
+
+def test_should_stay_silent_when_only_one_sibling_patches_the_flag(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    source = (
+        "def test_should_submit_when_gate_passes(monkeypatch) -> None:\n"
+        "    assert run() == 'submitted'\n"
+        "\n"
+        "def test_should_fail_when_reader_raises(monkeypatch) -> None:\n"
+        "    monkeypatch.setattr('pkg.pipeline.IS_STAGED_VERIFICATION_ENABLED', True)\n"
+        "    assert run() == 'failed'\n"
+    )
+    issues = code_rules_enforcer.check_flag_gated_scenario_test_naming(
+        source, SCENARIO_TEST_FILE_PATH
+    )
+    advisory_text = capsys.readouterr().err
+    assert issues == []
+    assert advisory_text == "", (
+        f"One sibling patch is not an established flag; expected silence, got: {advisory_text!r}"
+    )
+
+
+def test_should_not_advise_for_production_file() -> None:
+    issues = code_rules_enforcer.check_flag_gated_scenario_test_naming(
+        _THREE_SIBLINGS_PATCH_THE_FLAG_ONE_SCENARIO_TEST_DOES_NOT,
+        "packages/app/services/submission_pipeline.py",
+    )
+    assert issues == []

package/hooks/blocking/test_open_questions_in_plans_blocker.py

@@ -1,5 +1,6 @@
 """Tests for open_questions_in_plans_blocker hook."""
 
+import ast
 import json
 import os
 import subprocess
@@ -10,6 +11,13 @@ HOOK_SCRIPT_PATH = os.path.join(
     os.path.dirname(__file__), "open_questions_in_plans_blocker.py"
 )
 
+
+def _read_hook_module_docstring() -> str:
+    source_text = open(HOOK_SCRIPT_PATH, encoding="utf-8").read()
+    module_docstring = ast.get_docstring(ast.parse(source_text))
+    assert module_docstring is not None
+    return module_docstring
+
 _plan_with_open_questions = (
     "## Context\nA plan.\n\n## Open Questions\n- Which auth provider?\n"
 )
@@ -75,6 +83,41 @@ def test_blocks_project_local_plans_directory():
     assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
 
 
+def test_module_docstring_names_docs_plans_directory_family():
+    """The docstring enumerates every directory family the detector fires on,
+    including the repo-local `docs/plans/` family it now blocks."""
+    module_docstring = _read_hook_module_docstring()
+
+    assert "docs/plans/" in module_docstring
+
+
+def test_blocks_repo_docs_plan_packet_directory():
+    """Repo-local `docs/plans/<slug>/` packet docs are plan files too."""
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": "docs/plans/add-login/spec/scope.md",
+            "content": _plan_with_open_questions,
+        },
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_blocks_windows_style_repo_docs_plan_packet_directory():
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": "docs\\plans\\add-login\\spec\\scope.md",
+            "content": _plan_with_open_questions,
+        },
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
 def test_blocks_case_insensitive_heading():
     result = _run_hook(
         "Write",

package/hooks/hooks_constants/code_rules_path_utils_constants.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 ALL_CONFIG_DIRECTORY_NAMES = frozenset(
     {
+        "anthropic_plan_scripts_constants",
         "config",
         "hooks_constants",
         "git_hooks_constants",

package/hooks/hooks_constants/dead_module_constant_constants.py

@@ -10,6 +10,7 @@ DUNDER_INIT_FILENAME: str = "__init__.py"
 CONSTANTS_MODULE_SUFFIX: str = "_constants.py"
 CONFIG_DIRECTORY_SEGMENT: str = "config"
 DUNDER_ALL_NAME: str = "__all__"
+GIT_DIRECTORY_NAME: str = ".git"
 MINIMUM_UPPER_SNAKE_LENGTH: int = 2
 MAX_DEAD_MODULE_CONSTANT_ISSUES: int = 25
 MAX_SCAN_ROOT_FILE_COUNT: int = 2000

package/hooks/hooks_constants/open_questions_in_plans_blocker_constants.py

@@ -9,6 +9,8 @@ MARKDOWN_EXTENSION: str = ".md"
 
 PLANS_PATH_SEGMENT: str = "/.claude/plans/"
 PLANS_PATH_PREFIX: str = ".claude/plans/"
+DOCS_PLANS_PATH_SEGMENT: str = "/docs/plans/"
+DOCS_PLANS_PATH_PREFIX: str = "docs/plans/"
 
 PLAN_FILE_ENCODING: str = "utf-8"
 
@@ -25,6 +27,8 @@ INLINE_CODE_PATTERN: Pattern[str] = compile(r"``[^`\n]+``|`[^`\n]+`")
 
 __all__ = [
     "CODE_FENCE_PATTERN",
+    "DOCS_PLANS_PATH_PREFIX",
+    "DOCS_PLANS_PATH_SEGMENT",
     "INLINE_CODE_PATTERN",
     "MARKDOWN_EXTENSION",
     "OPEN_QUESTIONS_HEADING_PATTERN",

package/hooks/hooks_constants/test_open_questions_in_plans_blocker_constants.py

@@ -27,6 +27,16 @@ def test_plans_path_prefix_matches_project_local_plans_directory() -> None:
     assert "PLANS_PATH_PREFIX" in constants_module.__all__
 
 
+def test_docs_plans_path_segment_matches_repo_packet_directory() -> None:
+    assert constants_module.DOCS_PLANS_PATH_SEGMENT == "/docs/plans/"
+    assert "DOCS_PLANS_PATH_SEGMENT" in constants_module.__all__
+
+
+def test_docs_plans_path_prefix_matches_repo_packet_directory() -> None:
+    assert constants_module.DOCS_PLANS_PATH_PREFIX == "docs/plans/"
+    assert "DOCS_PLANS_PATH_PREFIX" in constants_module.__all__
+
+
 def test_open_questions_heading_pattern_matches_atx_heading() -> None:
     assert constants_module.OPEN_QUESTIONS_HEADING_PATTERN.search("## Open Questions\n")
 
@@ -111,9 +121,11 @@ def test_unreadable_file_synthetic_content_triggers_heading_pattern() -> None:
     assert "UNREADABLE_FILE_SYNTHETIC_CONTENT" in constants_module.__all__
 
 
-def test_all_exports_enumerates_eight_public_constants_in_sorted_order() -> None:
+def test_all_exports_enumerates_ten_public_constants_in_sorted_order() -> None:
     expected_exports = [
         "CODE_FENCE_PATTERN",
+        "DOCS_PLANS_PATH_PREFIX",
+        "DOCS_PLANS_PATH_SEGMENT",
         "INLINE_CODE_PATTERN",
         "MARKDOWN_EXTENSION",
         "OPEN_QUESTIONS_HEADING_PATTERN",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.65.0",
+    "version": "1.66.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/anthropic-plan/SKILL.md

@@ -1,107 +1,68 @@
 ---
 name: anthropic-plan
-description: Structured implementation planning through readonly codebase exploration before any code changes. Produces a plan file for approval. Use when the user says /anthropic-plan, "plan this first", "think before coding", "explore before implementing", "make a plan", or when approaching non-trivial tasks that benefit from upfront exploration and design. Also triggers on "what would the approach be", "scope this out", or "don't code yet, just plan".
+description: Workflow-backed implementation planning that creates a deep repo-local packet under docs/plans/<slug>/ before any code changes. Use for /anthropic-plan, /plan, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial implementation requests that need source-grounded design, TDD steps, and validator approval before build work.
 ---
 
-# Claude Plan
+# Anthropic Plan
 
-Explore the codebase, design an approach, and write a plan file -- all without touching production code.
+Create a source-grounded plan packet through the Claude Code Workflow runtime. The output is a repo-local `docs/plans/<slug>/` folder with context, spec, implementation, validation, and handoff docs. Stop before implementation.
 
-## Why
+## Launch
 
-Jumping straight to code on non-trivial tasks leads to wasted effort when the approach conflicts with existing patterns, misses reusable code, or misunderstands the user's intent. This skill enforces "look before you leap": explore first, design second, write the plan third, get approval last. No code changes until the user says go.
+Call the workflow with the user request and current working directory:
 
-## Constraints
-
-Treat the codebase as readonly throughout this skill. The only file you may create or edit is the plan file.
-
-**Allowed:** Read files, Grep, Glob, launch Explore agents, launch Plan agents, write/edit the plan file, AskUserQuestion for clarification.
-
-**Not allowed:** Edit source files, Write new source files, run tests, install packages, run non-readonly Bash commands, or make any system changes.
-
-This discipline exists because the user invoked this skill specifically to understand the approach before committing to it. Violating readonly would undermine the whole point.
-
-## Plan File
-
-Write to `~/.claude/plans/<slug>.md`.
-
-Generate the slug from the task -- descriptive, kebab-case, 2-4 words. Examples: `add-user-auth.md`, `fix-payment-retry.md`, `refactor-config-loading.md`. Avoid the random-word convention used by built-in plan mode.
-
-**Announce at start:** "Planning: `<slug>` -- exploring before writing code."
-
-## Workflow
-
-### Phase 1: Explore
-
-Understand the problem space before proposing solutions. Launch Explore agents in parallel -- up to 3, but use the minimum needed. Quality over quantity.
-
-What to look for:
-- Files and modules the task will touch
-- Existing patterns for similar functionality
-- Utilities, helpers, constants, and shared code to reuse
-- Test patterns already in place
-
-Skip this phase only if the task is trivial and full context already exists in the conversation.
-
-### Phase 2: Design
-
-Launch Plan agent(s) to design the implementation -- up to 3 for complex or multi-area tasks, skip entirely for trivial tasks. Feed them comprehensive context from Phase 1; they cannot explore on their own, so everything they need must come from you.
-
-### Phase 3: Review
-
-Before committing to the plan:
-- Read the critical files yourself to verify the agents got it right
-- Check alignment with what the user actually asked for
-- If requirements are ambiguous, use AskUserQuestion now -- not after writing the plan
-
-### Phase 4: Write the Plan
+```js
+Workflow({
+  scriptPath: "$HOME/.claude/skills/anthropic-plan/workflow/plan-packet.mjs",
+  input: {
+    task: "$ARGUMENTS",
+    cwd: "<current working directory>"
+  }
+})
+```
 
-Write incrementally as you learn things in Phases 1-3, then refine here. The plan file has these sections:
+If the Workflow tool is unavailable, say `anthropic-plan requires the Workflow tool; aborting` and stop.
 
-```markdown
-## Context
-Why this change is needed, what problem it solves, what the outcome looks like.
+## Workflow Contract
 
-## Approach
-The recommended implementation. One approach, not a menu of alternatives.
-Concise but detailed enough to execute without re-exploring.
+The workflow handles the full planning loop:
 
-## Files
-Critical file paths that will be created or modified.
+1. Resolve repo root and packet path.
+2. Read project instructions, rules, relevant skills, manifests, docs, tests, hooks, agents, commands, configs, and workflows.
+3. Build a source inventory and extract source facts into `context/source-map.md`.
+4. Write the packet under `docs/plans/<slug>/`.
+5. Run `scripts/validate_packet.py`.
+6. Spawn `plan-packet-validator` in fresh context.
+7. Repair packet findings up to the workflow cap.
+8. Return packet path, validation state, and findings.
+9. Stop before implementation.
 
-## Reuse
-Existing functions, utilities, constants, or patterns to leverage.
-Include file:line references so the implementer can find them instantly.
+## Packet Shape
 
-## Steps
-Ordered implementation steps. Each step is a discrete, testable unit of work.
+Required root: `docs/plans/<slug>/`
 
-## Verification
-How to confirm end-to-end that the implementation works.
-Specific commands, test files, or manual verification steps.
+Required top-level files and folders:
 
-## Bash Permissions
-Semantic descriptions of bash actions the implementation will need:
-- "run tests"
-- "install dependencies"
-- "start dev server"
-These are action descriptions, not specific commands.
-```
+- `README.md`
+- `packet.json`
+- `context/`
+- `spec/`
+- `implementation/`
+- `validation/`
+- `handoff/`
 
-### Phase 5: Present for Approval
+The packet depth rule is strict: `README.md` is a thin hub, first-level folders group purpose, and second-level files carry detail. Add `context/subsystems/<name>.md` only when the planner finds more than twelve source files or more than three subsystems.
 
-Use AskUserQuestion to present the completed plan. Do not ask about approval in regular text -- always use AskUserQuestion so the user gets a clear, structured decision point.
+## Validation
 
-Options:
-- **Approve** -- proceed with implementation
-- **Revise** -- user has feedback to incorporate
-- **Cancel** -- abandon the plan
+The deterministic validator checks required files, placeholders, `Open Questions`, source-map strength, TDD coverage, standalone handoff prompts, and `packet.json` consistency.
 
-## Scaling
+The `plan-packet-validator` agent checks source accuracy, scope, enough implementation detail for a blind build agent, real TDD order, invented APIs or commands, and end-to-end acceptance criteria.
 
-Not every task needs all five phases. Match effort to complexity:
+## Rules
 
-- **Trivial** (rename, typo fix): Ask if a formal plan is even wanted. If yes, skip Phases 1-2, write a minimal plan.
-- **Small** (single-file change, clear scope): One Explore agent, skip Design phase, concise plan.
-- **Medium** (multi-file feature, some ambiguity): Full workflow, 1-2 agents per phase.
-- **Large** (cross-cutting change, architectural): Full workflow, max agents, thorough Review phase.
+- Write docs only.
+- Do not edit production code.
+- Do not run implementation commands.
+- Ask the user only for product choices that cannot be derived from local context.
+- Fold resolved answers into the packet. Never leave an `Open Questions` section.

package/skills/anthropic-plan/scripts/anthropic_plan_scripts_constants/validate_packet_constants.py

@@ -0,0 +1,33 @@
+"""Constants for the plan packet validator."""
+
+from __future__ import annotations
+
+ALL_REQUIRED_RELATIVE_PATHS: tuple[str, ...] = (
+    "README.md",
+    "packet.json",
+    "context/user-request.md",
+    "context/source-map.md",
+    "context/current-state.md",
+    "context/existing-patterns.md",
+    "context/constraints.md",
+    "context/glossary.md",
+    "spec/scope.md",
+    "spec/behavior.md",
+    "spec/interfaces.md",
+    "spec/data-flow.md",
+    "spec/failure-modes.md",
+    "spec/acceptance.md",
+    "implementation/strategy.md",
+    "implementation/steps.md",
+    "implementation/tdd-plan.md",
+    "implementation/file-plan.md",
+    "implementation/refactor-checkpoints.md",
+    "validation/validator-report.md",
+    "validation/deterministic-checks.md",
+    "validation/unresolved-risks.md",
+    "handoff/build-prompt.md",
+    "handoff/review-prompt.md",
+    "handoff/verification-commands.md",
+)
+MARKDOWN_FILE_SUFFIX: str = ".md"
+EXIT_CODE_VALIDATION_FAILED: int = 2