claude-dev-env 1.65.0 → 1.66.0

package/skills/anthropic-plan/scripts/validate_packet.py

@@ -0,0 +1,397 @@
+"""Validate workflow-generated plan packets."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+from anthropic_plan_scripts_constants.validate_packet_constants import (
+    ALL_REQUIRED_RELATIVE_PATHS,
+    EXIT_CODE_VALIDATION_FAILED,
+    MARKDOWN_FILE_SUFFIX,
+)
+
+
+def required_relative_paths() -> tuple[str, ...]:
+    """Return every required packet file path relative to the packet root.
+
+    Returns:
+        Every required packet file path, relative to the packet root.
+    """
+    return ALL_REQUIRED_RELATIVE_PATHS
+
+
+def markdown_relative_paths() -> list[str]:
+    """Return required markdown packet files.
+
+    Returns:
+        Each required packet file path that names a markdown file.
+    """
+    return [
+        each_relative_path
+        for each_relative_path in required_relative_paths()
+        if each_relative_path.endswith(MARKDOWN_FILE_SUFFIX)
+    ]
+
+
+def validate_packet(packet_directory: Path) -> list[str]:
+    """Return validation errors for a packet directory.
+
+    Args:
+        packet_directory: Directory that should contain a complete packet.
+
+    Returns:
+        Every validation error found, or an empty list when the packet is valid.
+    """
+    all_errors: list[str] = []
+    all_errors.extend(missing_file_errors(packet_directory))
+    all_errors.extend(markdown_content_errors(packet_directory))
+    all_errors.extend(packet_json_errors(packet_directory))
+    all_errors.extend(source_map_errors(packet_directory))
+    all_errors.extend(tdd_plan_errors(packet_directory))
+    all_errors.extend(implementation_step_errors(packet_directory))
+    all_errors.extend(build_prompt_errors(packet_directory))
+    return all_errors
+
+
+def missing_file_errors(packet_directory: Path) -> list[str]:
+    """Return one error for each missing required packet file.
+
+    Args:
+        packet_directory: Directory that should contain a complete packet.
+
+    Returns:
+        One error string for each required file absent from the directory.
+    """
+    return [
+        f"missing required file: {each_relative_path}"
+        for each_relative_path in required_relative_paths()
+        if not (packet_directory / each_relative_path).is_file()
+    ]
+
+
+def markdown_content_errors(packet_directory: Path) -> list[str]:
+    """Return errors for invalid markdown packet content.
+
+    Args:
+        packet_directory: Directory that should contain markdown packet files.
+
+    Returns:
+        One error string for each markdown file with placeholder or open-question text.
+    """
+    all_errors: list[str] = []
+    for each_relative_path in markdown_relative_paths():
+        packet_file = packet_directory / each_relative_path
+        if not packet_file.is_file():
+            continue
+        markdown_text = packet_file.read_text(encoding="utf-8")
+        if has_placeholder_text(markdown_text):
+            all_errors.append(f"{each_relative_path} contains placeholder text")
+        if has_open_questions_heading(markdown_text):
+            all_errors.append(f"{each_relative_path} contains an Open Questions heading")
+    return all_errors
+
+
+def packet_json_errors(packet_directory: Path) -> list[str]:
+    """Return errors for the machine-readable packet manifest.
+
+    Args:
+        packet_directory: Directory that should contain packet.json.
+
+    Returns:
+        One error string for each packet.json field that is missing or inconsistent.
+    """
+    packet_file = packet_directory / "packet.json"
+    if not packet_file.is_file():
+        return []
+    try:
+        payload_object: object = json.loads(packet_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as packet_error:
+        return [f"packet.json is invalid JSON: {packet_error.msg}"]
+    if not isinstance(payload_object, dict):
+        return ["packet.json must contain an object"]
+
+    all_errors: list[str] = []
+    if payload_object.get("schemaVersion") != 1:
+        all_errors.append("packet.json schemaVersion must be 1")
+    if not isinstance(payload_object.get("slug"), str) or not payload_object.get("slug"):
+        all_errors.append("packet.json slug must be a non-empty string")
+    all_source_files = payload_object.get("sourceFiles")
+    if not isinstance(all_source_files, list) or not all_source_files:
+        all_errors.append("packet.json sourceFiles must be a non-empty list")
+    stored_packet_path = payload_object.get("packetPath", "")
+    if not is_same_packet_path(packet_directory, stored_packet_path):
+        all_errors.append("packet.json packetPath must match the validated packet directory")
+    if not isinstance(payload_object.get("validator"), dict):
+        all_errors.append("packet.json validator must be an object")
+    return all_errors
+
+
+def is_same_packet_path(packet_directory: Path, stored_packet_path: object) -> bool:
+    """Return whether a stored packetPath names the validated packet directory.
+
+    Args:
+        packet_directory: Directory passed to the validator on the command line.
+        stored_packet_path: The packetPath value read from packet.json.
+
+    Returns:
+        True when both paths resolve to the same directory regardless of
+        separator style, trailing separators, or relative-versus-absolute form,
+        otherwise False.
+    """
+    if not isinstance(stored_packet_path, str) or not stored_packet_path:
+        return False
+    return packet_directory.resolve() == Path(stored_packet_path).resolve()
+
+
+def source_map_errors(packet_directory: Path) -> list[str]:
+    """Return errors for weak source-map grounding.
+
+    Args:
+        packet_directory: Directory that should contain context/source-map.md.
+
+    Returns:
+        An error string when the source map lacks source-grounded rows, else an empty list.
+    """
+    source_map_file = packet_directory / "context" / "source-map.md"
+    if not source_map_file.is_file():
+        return []
+    source_map_text = source_map_file.read_text(encoding="utf-8")
+    if not has_source_table_row(source_map_text):
+        return ["source-map.md must include source-grounded rows"]
+    return []
+
+
+def tdd_plan_errors(packet_directory: Path) -> list[str]:
+    """Return errors for a weak TDD plan.
+
+    Args:
+        packet_directory: Directory that should contain implementation/tdd-plan.md.
+
+    Returns:
+        One error string for each TDD-plan requirement the file fails to state.
+    """
+    tdd_file = packet_directory / "implementation" / "tdd-plan.md"
+    if not tdd_file.is_file():
+        return []
+    tdd_text = tdd_file.read_text(encoding="utf-8").lower()
+    if "failing test" not in tdd_text and not re.search(r"\bred\b", tdd_text):
+        return ["tdd-plan.md must name failing tests"]
+    if "production" not in tdd_text and "green" not in tdd_text:
+        return ["tdd-plan.md must state the production-code step after red"]
+    return []
+
+
+def implementation_step_errors(packet_directory: Path) -> list[str]:
+    """Return errors for implementation steps without test coverage.
+
+    Args:
+        packet_directory: Directory that should contain implementation/steps.md.
+
+    Returns:
+        An error string when a numbered or bulleted step names no test or
+        non-code reason, else an empty list.
+    """
+    steps_file = packet_directory / "implementation" / "steps.md"
+    if not steps_file.is_file():
+        return []
+    step_lines = [
+        each_line.strip()
+        for each_line in steps_file.read_text(encoding="utf-8").splitlines()
+        if is_step_line(each_line.strip())
+    ]
+    missing_test_lines = [
+        each_line
+        for each_line in step_lines
+        if not step_line_has_test_contract(each_line)
+    ]
+    if missing_test_lines:
+        return ["implementation/steps.md has steps without a test or non-code reason"]
+    return []
+
+
+def build_prompt_errors(packet_directory: Path) -> list[str]:
+    """Return errors for a handoff prompt that depends on chat history.
+
+    Args:
+        packet_directory: Directory that should contain handoff/build-prompt.md.
+
+    Returns:
+        One error string for each standalone-handoff requirement the prompt fails.
+    """
+    build_prompt_file = packet_directory / "handoff" / "build-prompt.md"
+    if not build_prompt_file.is_file():
+        return []
+    build_prompt_text = build_prompt_file.read_text(encoding="utf-8").lower()
+    if any(each_phrase in build_prompt_text for each_phrase in forbidden_chat_phrases()):
+        return ["build-prompt.md must stand alone without chat history"]
+    if "use only this packet" not in build_prompt_text:
+        return ["build-prompt.md must tell the build agent to use only this packet"]
+    return []
+
+
+def has_placeholder_text(markdown_text: str) -> bool:
+    """Return whether markdown contains unresolved placeholder text.
+
+    Args:
+        markdown_text: Markdown content to inspect.
+
+    Returns:
+        True when the markdown prose contains keyword placeholders (todo, tbd,
+        fixme, replace_me, placeholder, fill this in), curly-brace template
+        tokens, or angle-bracket template tokens such as `<path>` or
+        `<Plan Title>` that are not known inline HTML tags. An angle bracket
+        directly preceded by an identifier character is a generic type in prose
+        (List<Item>, Optional<User>) rather than a placeholder, so it does not
+        count. Otherwise False.
+    """
+    keyword_pattern = re.compile(
+        r"\b(?:todo|tbd|fixme|replace_me|placeholder|fill this in)\b|{{|}}",
+        re.IGNORECASE,
+    )
+    angle_bracket_pattern = re.compile(
+        r"(?<![A-Za-z0-9_])"
+        r"<(?!/?(?:details|summary|br|hr|div|span|img|a|p|kbd|code|pre|sub|sup"
+        r"|table|thead|tbody|tr|td|th)[ />])[A-Za-z][\w \-]*>",
+    )
+    prose_text = strip_markdown_code(markdown_text)
+    if keyword_pattern.search(prose_text):
+        return True
+    return bool(angle_bracket_pattern.search(prose_text))
+
+
+def has_open_questions_heading(markdown_text: str) -> bool:
+    """Return whether markdown contains an Open Questions heading.
+
+    Args:
+        markdown_text: Markdown content to inspect.
+
+    Returns:
+        True when the markdown contains an Open Questions heading, otherwise False.
+    """
+    heading_pattern = re.compile(
+        r"^\s*(?:#{1,6}\s+|\*\*\s*|__\s*)open[\s_-]+questions(?:[^A-Za-z0-9]|$)",
+        re.IGNORECASE | re.MULTILINE,
+    )
+    return bool(heading_pattern.search(strip_markdown_code(markdown_text)))
+
+
+def strip_markdown_code(markdown_text: str) -> str:
+    """Return markdown with code spans and fenced blocks removed.
+
+    Args:
+        markdown_text: Markdown content to strip.
+
+    Returns:
+        The markdown content with fenced blocks and inline code spans removed.
+    """
+    without_fences = re.sub(r"```[\s\S]*?```", "", markdown_text)
+    return re.sub(r"``[^`\n]+``|`[^`\n]+`", "", without_fences)
+
+
+def has_source_table_row(source_map_text: str) -> bool:
+    """Return whether source-map.md has at least one concrete source row.
+
+    Args:
+        source_map_text: The source map markdown content.
+
+    Returns:
+        True when at least one table row names a concrete source path, otherwise False.
+    """
+    source_file_token_pattern = re.compile(
+        r"[\w-]+\.(?:py|pyi|js|mjs|cjs|jsx|ts|tsx|mts|cts|json|jsonc|ya?ml|toml|ini|cfg"
+        r"|mdx?|rst|txt|sh|bash|ps[dm]?1|sql|html?|s?css|sass|less|go|rs|java|kts?|rb|php"
+        r"|cc?|cpp|h|hpp|cs|swift|scala|lua|vue|svelte|xml|env|lock|dockerfile|mk|gradle"
+        r"|proto|gr?aphql|gql)\b",
+        re.IGNORECASE,
+    )
+    for each_line in source_map_text.splitlines():
+        normalized_line = each_line.strip()
+        if not normalized_line.startswith("|"):
+            continue
+        if set(normalized_line.replace("|", "").strip()) <= {"-", ":"}:
+            continue
+        if "/" in normalized_line or "\\" in normalized_line:
+            return True
+        if source_file_token_pattern.search(normalized_line):
+            return True
+    return False
+
+
+def is_step_line(stripped_line: str) -> bool:
+    """Return whether a stripped line is a numbered or bulleted implementation step.
+
+    Args:
+        stripped_line: A whitespace-stripped line from steps.md.
+
+    Returns:
+        True when the line begins with a numbered marker such as a digit run
+        followed by a dot, or a bullet marker (`-`, `*`, `+`), otherwise False.
+    """
+    return bool(re.match(r"^(?:\d+\.|[-*+])\s+", stripped_line))
+
+
+def step_line_has_test_contract(step_line: str) -> bool:
+    """Return whether a step names test coverage or a non-code reason.
+
+    Args:
+        step_line: Numbered implementation step line.
+
+    Returns:
+        True when the step names a test or a non-code reason, otherwise False.
+    """
+    normalized_line = step_line.lower()
+    return (
+        "test" in normalized_line
+        or "non-code" in normalized_line
+        or "covered by" in normalized_line
+    )
+
+
+def forbidden_chat_phrases() -> tuple[str, ...]:
+    """Return phrases that make a handoff prompt depend on chat history.
+
+    Returns:
+        Each phrase that signals a handoff prompt depends on chat history.
+    """
+    return (
+        "as discussed above",
+        "from our chat",
+        "previous conversation",
+        "earlier in this thread",
+    )
+
+
+def parse_arguments() -> argparse.Namespace:
+    """Parse CLI arguments.
+
+    Returns:
+        The parsed command-line arguments namespace.
+    """
+    parser = argparse.ArgumentParser(description="Validate a plan packet directory.")
+    parser.add_argument("packet_directory", type=Path)
+    return parser.parse_args()
+
+
+def main() -> int:
+    """Run the packet validator CLI.
+
+    Returns:
+        Zero when the packet is valid, or a non-zero exit code when validation errors are found.
+    """
+    parsed_arguments = parse_arguments()
+    packet_directory = parsed_arguments.packet_directory
+    all_errors = validate_packet(packet_directory)
+    if all_errors:
+        for each_error in all_errors:
+            print(each_error, file=sys.stderr)
+        return EXIT_CODE_VALIDATION_FAILED
+    print("packet validation passed")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/anthropic-plan/templates/README.md

@@ -0,0 +1,20 @@
+# <Plan Title>
+
+## Goal
+
+State the requested outcome in one short paragraph.
+
+## Status
+
+- Approval: pending
+- Deterministic validation: pending
+- Semantic validation: pending
+- Implementation: not started
+
+## Packet Map
+
+Link every first-level packet file.
+
+## Build Path
+
+Tell the build agent which files to read first.

package/skills/anthropic-plan/templates/build-prompt.md

@@ -0,0 +1,9 @@
+# Build Prompt
+
+Use only this packet. Do not rely on prior chat history.
+
+1. Read `README.md`.
+2. Read `context/source-map.md`.
+3. Read `implementation/tdd-plan.md`.
+4. Follow `implementation/steps.md`.
+5. Verify with `handoff/verification-commands.md`.

package/skills/anthropic-plan/templates/source-map.md

@@ -0,0 +1,5 @@
+# Source Map
+
+| Source | Why it matters | Facts extracted | Plan implication |
+|---|---|---|---|
+| <path> | <reason> | <verified fact> | <implementation implication> |

package/skills/anthropic-plan/test_skill_contract.py

@@ -0,0 +1,53 @@
+"""Contract tests for the anthropic-plan skill packet workflow."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+SKILL_DIRECTORY = Path(__file__).resolve().parent
+CLAUDE_DIRECTORY = SKILL_DIRECTORY.parent.parent
+SKILL_PATH = SKILL_DIRECTORY / "SKILL.md"
+PLAN_COMMAND_PATH = CLAUDE_DIRECTORY / "commands" / "plan.md"
+VALIDATOR_AGENT_PATH = CLAUDE_DIRECTORY / "agents" / "plan-packet-validator.md"
+
+
+def test_skill_invokes_plan_packet_workflow() -> None:
+    skill_text = SKILL_PATH.read_text(encoding="utf-8")
+
+    assert "Workflow({" in skill_text
+    assert "workflow/plan-packet.mjs" in skill_text
+    assert "docs/plans/<slug>/" in skill_text
+
+
+def test_skill_no_longer_mentions_single_home_plan_file() -> None:
+    skill_text = SKILL_PATH.read_text(encoding="utf-8")
+
+    assert "~/.claude/plans/<slug>.md" not in skill_text
+    assert "single-file" not in skill_text.lower()
+
+
+def test_skill_names_validator_and_stop_before_code_rules() -> None:
+    skill_text = SKILL_PATH.read_text(encoding="utf-8")
+
+    assert "plan-packet-validator" in skill_text
+    assert "validate_packet.py" in skill_text
+    assert "stop before implementation" in skill_text.lower()
+
+
+def test_plan_command_routes_to_anthropic_plan_without_stale_skills() -> None:
+    command_text = PLAN_COMMAND_PATH.read_text(encoding="utf-8")
+
+    assert "anthropic-plan" in command_text
+    assert "write-plan" not in command_text
+    assert "review-plan" not in command_text
+    assert "plan-executor" not in command_text
+
+
+def test_validator_agent_exists_and_is_read_only() -> None:
+    agent_text = VALIDATOR_AGENT_PATH.read_text(encoding="utf-8")
+
+    assert "name: plan-packet-validator" in agent_text
+    assert "tools: Read, Grep, Glob, Bash" in agent_text
+    assert "Never edit" in agent_text
+    assert "source-backed" in agent_text

package/skills/anthropic-plan/workflow/plan-packet.contract.test.mjs

@@ -0,0 +1,79 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const workflowDirectory = dirname(fileURLToPath(import.meta.url));
+const workflowPath = join(workflowDirectory, 'plan-packet.mjs');
+const workflowSource = existsSync(workflowPath) ? readFileSync(workflowPath, 'utf8') : '';
+
+function functionBody(functionName) {
+  const functionStart = workflowSource.indexOf(`function ${functionName}(`);
+  assert.notEqual(functionStart, -1, `expected ${functionName} to exist`);
+  const nextFunctionMatch = /\n(?:async )?function /.exec(workflowSource.slice(functionStart + 1));
+  const functionEnd =
+    nextFunctionMatch === null ? workflowSource.length : functionStart + 1 + nextFunctionMatch.index;
+  return workflowSource.slice(functionStart, functionEnd);
+}
+
+test('workflow file exists and starts with meta export', () => {
+  assert.ok(existsSync(workflowPath), 'expected workflow/plan-packet.mjs to exist');
+  assert.match(workflowSource.trimStart(), /^export const meta = /);
+  assert.doesNotMatch(workflowSource, /^import\s/m);
+});
+
+test('workflow declares packet creation, validation, and approval phases', () => {
+  assert.match(workflowSource, /name:\s*'plan-packet'/);
+  assert.match(workflowSource, /Discover/);
+  assert.match(workflowSource, /Write packet/);
+  assert.match(workflowSource, /Validate/);
+  assert.match(workflowSource, /Approval/);
+});
+
+test('workflow requires the docs plans packet root', () => {
+  const pathBuilder = functionBody('buildPacketPath');
+  assert.match(pathBuilder, /docs/);
+  assert.match(pathBuilder, /plans/);
+  assert.doesNotMatch(pathBuilder, /\.claude\/plans/);
+});
+
+test('workflow writes the packet before spawning the validator', () => {
+  const runBody = functionBody('runPlanPacketWorkflow');
+  const writeIndex = runBody.indexOf('writePacket');
+  const deterministicIndex = runBody.indexOf('runDeterministicValidation');
+  const semanticIndex = runBody.indexOf('runSemanticValidator');
+  assert.ok(writeIndex !== -1 && deterministicIndex !== -1 && semanticIndex !== -1);
+  assert.ok(writeIndex < deterministicIndex);
+  assert.ok(deterministicIndex < semanticIndex);
+});
+
+test('workflow repairs semantic findings and caps repair loops at three', () => {
+  const runBody = functionBody('runPlanPacketWorkflow');
+  assert.match(runBody, /maxRepairLoops:\s*3/);
+  assert.match(runBody, /repairPacket/);
+  assert.match(runBody, /semanticValidation\.allPassed/);
+});
+
+test('semantic validator uses a dedicated validator agent with structured schema', () => {
+  const validatorBody = functionBody('runSemanticValidator');
+  assert.match(validatorBody, /agentType:\s*'plan-packet-validator'/);
+  assert.match(validatorBody, /schema:\s*validationSchema\(\)/);
+  assert.match(validatorBody, /source-backed/);
+  assert.match(validatorBody, /blind build agent/);
+});
+
+test('workflow stops before implementation work', () => {
+  const runBody = functionBody('runPlanPacketWorkflow');
+  assert.match(runBody, /implementationStarted:\s*false/);
+  assert.doesNotMatch(runBody, /clean-coder/);
+  assert.doesNotMatch(runBody, /git commit/);
+});
+
+test('workflow fails closed when a phase errors', () => {
+  const runBody = functionBody('runPlanPacketWorkflow');
+  assert.match(runBody, /try\s*{/);
+  assert.match(runBody, /catch\s*\(/);
+  assert.match(runBody, /validationPassed:\s*false/);
+  assert.match(runBody, /approvalRequired:\s*true/);
+});