claude-dev-env 1.41.0 → 1.43.0

package/skills/bugteam/scripts/test_agent_config_carveout.py

@@ -0,0 +1,356 @@
+"""Behavior tests for the agent-config carve-out and stale-trust-entry purge.
+
+Covers two Bugbot findings on PR #467:
+  - Deny rules must be written to permissions.deny so agent-config edits
+    require explicit per-edit user approval.
+  - Trust entries in autoMode.environment must be purged on grant
+    (preventing accumulation across template revisions) and removed on
+    revoke regardless of the exact template wording.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+_script_directory = str(Path(__file__).resolve().parent)
+if _script_directory not in sys.path:
+    sys.path.insert(0, _script_directory)
+
+import _bugteam_permissions_common as common_module
+import grant_project_claude_permissions as grant_module
+import revoke_project_claude_permissions as revoke_module
+from bugteam_scripts_constants.claude_permissions_common_constants import (
+    ALL_AGENT_CONFIG_DENY_TOOLS,
+    ALL_AGENT_CONFIG_PATH_PATTERNS,
+    ALL_PERMISSION_ALLOW_TOOLS,
+    AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE,
+)
+
+
+def _make_fake_project(tmp_path: Path) -> Path:
+    fake_project_root = tmp_path / "fake_project"
+    (fake_project_root / ".claude").mkdir(parents=True)
+    return fake_project_root
+
+
+def _project_path_as_posix(fake_project_root: Path) -> str:
+    return str(fake_project_root).replace("\\", "/")
+
+
+def _redirect_settings_to_fake_path(
+    fake_settings_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    fake_home_directory = fake_settings_path.parent.parent
+    monkeypatch.setattr(Path, "home", classmethod(lambda _cls: fake_home_directory))
+
+
+def _prepare_fake_home(tmp_path: Path) -> Path:
+    fake_home_directory = tmp_path / "fake_home"
+    claude_settings_directory = fake_home_directory / ".claude"
+    claude_settings_directory.mkdir(parents=True)
+    return claude_settings_directory / "settings.json"
+
+
+def _seed_grant_then_run(
+    fake_settings_path: Path,
+    fake_project_root: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    pre_existing_settings: dict[str, Any],
+) -> None:
+    fake_settings_path.write_text(json.dumps(pre_existing_settings), encoding="utf-8")
+    _redirect_settings_to_fake_path(fake_settings_path, monkeypatch)
+    monkeypatch.chdir(fake_project_root)
+    grant_module.grant_permissions_for_current_directory()
+
+
+def _seed_revoke_then_run(
+    fake_settings_path: Path,
+    fake_project_root: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    pre_existing_settings: dict[str, Any],
+) -> None:
+    fake_settings_path.write_text(json.dumps(pre_existing_settings), encoding="utf-8")
+    _redirect_settings_to_fake_path(fake_settings_path, monkeypatch)
+    monkeypatch.chdir(fake_project_root)
+    revoke_module.revoke_permissions_for_current_directory()
+
+
+def test_grant_writes_deny_rules_for_every_tool_and_pattern(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    fake_project_root = _make_fake_project(tmp_path)
+    fake_settings_path = _prepare_fake_home(tmp_path)
+    _seed_grant_then_run(
+        fake_settings_path, fake_project_root, monkeypatch, pre_existing_settings={}
+    )
+    capsys.readouterr()
+    written_settings = json.loads(fake_settings_path.read_text(encoding="utf-8"))
+    deny_list = written_settings["permissions"]["deny"]
+    project_path_posix = _project_path_as_posix(fake_project_root)
+    for each_tool in ALL_AGENT_CONFIG_DENY_TOOLS:
+        for each_pattern in ALL_AGENT_CONFIG_PATH_PATTERNS:
+            expected_rule = f"{each_tool}({project_path_posix}/.claude/{each_pattern})"
+            assert expected_rule in deny_list, (
+                f"deny list missing expected rule {expected_rule!r}"
+            )
+
+
+def test_grant_writes_glob_deny_rules_for_every_agent_config_pattern(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """Glob must be in the deny tuple so agent-config paths require approval.
+
+    The AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE promises Edit/Write/Read/Glob
+    trust EXCEPT for agent-config files. Glob deny rules are how the EXCEPT
+    clause is honored for the Glob tool.
+    """
+    fake_project_root = _make_fake_project(tmp_path)
+    fake_settings_path = _prepare_fake_home(tmp_path)
+    _seed_grant_then_run(
+        fake_settings_path, fake_project_root, monkeypatch, pre_existing_settings={}
+    )
+    capsys.readouterr()
+    written_settings = json.loads(fake_settings_path.read_text(encoding="utf-8"))
+    deny_list = written_settings["permissions"]["deny"]
+    project_path_posix = _project_path_as_posix(fake_project_root)
+    assert "Glob" in ALL_AGENT_CONFIG_DENY_TOOLS
+    assert "Glob" not in ALL_PERMISSION_ALLOW_TOOLS
+    for each_pattern in ALL_AGENT_CONFIG_PATH_PATTERNS:
+        expected_glob_rule = f"Glob({project_path_posix}/.claude/{each_pattern})"
+        assert expected_glob_rule in deny_list, (
+            f"deny list missing expected Glob rule {expected_glob_rule!r}"
+        )
+
+
+def test_grant_purges_stale_trust_entries_then_writes_current_template(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    fake_project_root = _make_fake_project(tmp_path)
+    fake_settings_path = _prepare_fake_home(tmp_path)
+    project_path_posix = _project_path_as_posix(fake_project_root)
+    stale_entry_a = (
+        f"Trusted local workspace: {project_path_posix}/.claude/** old wording form A"
+    )
+    stale_entry_b = (
+        f"Trusted local workspace: {project_path_posix}/.claude/** "
+        f"different earlier wording"
+    )
+    unrelated_entry = "Some unrelated environment hint"
+    pre_existing_settings: dict[str, Any] = {
+        "autoMode": {
+            "environment": [stale_entry_a, stale_entry_b, unrelated_entry],
+        },
+    }
+    _seed_grant_then_run(
+        fake_settings_path,
+        fake_project_root,
+        monkeypatch,
+        pre_existing_settings=pre_existing_settings,
+    )
+    captured = capsys.readouterr()
+    written_settings = json.loads(fake_settings_path.read_text(encoding="utf-8"))
+    environment_list = written_settings["autoMode"]["environment"]
+    assert stale_entry_a not in environment_list
+    assert stale_entry_b not in environment_list
+    assert unrelated_entry in environment_list
+    matching_trust_entries = [
+        each_entry
+        for each_entry in environment_list
+        if isinstance(each_entry, str)
+        and each_entry.startswith("Trusted local workspace:")
+        and f"{project_path_posix}/.claude/**" in each_entry
+    ]
+    assert len(matching_trust_entries) == 1
+    assert "Stale auto-mode environment entries purged" in captured.out
+
+
+def test_revoke_removes_deny_rules(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    fake_project_root = _make_fake_project(tmp_path)
+    fake_settings_path = _prepare_fake_home(tmp_path)
+    project_path_posix = _project_path_as_posix(fake_project_root)
+    all_deny_rules = common_module.build_agent_config_deny_rules(
+        project_path_posix,
+        ALL_AGENT_CONFIG_DENY_TOOLS,
+        ALL_AGENT_CONFIG_PATH_PATTERNS,
+    )
+    pre_existing_settings: dict[str, Any] = {
+        "permissions": {
+            "deny": list(all_deny_rules),
+        },
+    }
+    _seed_revoke_then_run(
+        fake_settings_path,
+        fake_project_root,
+        monkeypatch,
+        pre_existing_settings=pre_existing_settings,
+    )
+    capsys.readouterr()
+    written_settings = json.loads(fake_settings_path.read_text(encoding="utf-8"))
+    permissions_section = written_settings.get("permissions", {})
+    remaining_deny_list = permissions_section.get("deny", [])
+    for each_rule in all_deny_rules:
+        assert each_rule not in remaining_deny_list
+
+
+def test_revoke_removes_every_legacy_trust_entry_for_project(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    fake_project_root = _make_fake_project(tmp_path)
+    fake_settings_path = _prepare_fake_home(tmp_path)
+    project_path_posix = _project_path_as_posix(fake_project_root)
+    legacy_entry_a = (
+        f"Trusted local workspace: {project_path_posix}/.claude/** template revision A"
+    )
+    legacy_entry_b = (
+        f"Trusted local workspace: {project_path_posix}/.claude/** template revision B"
+    )
+    unrelated_other_project_entry = (
+        "Trusted local workspace: /some/other/project/.claude/** still valid"
+    )
+    pre_existing_settings: dict[str, Any] = {
+        "autoMode": {
+            "environment": [
+                legacy_entry_a,
+                legacy_entry_b,
+                unrelated_other_project_entry,
+            ],
+        },
+    }
+    _seed_revoke_then_run(
+        fake_settings_path,
+        fake_project_root,
+        monkeypatch,
+        pre_existing_settings=pre_existing_settings,
+    )
+    written_settings = json.loads(fake_settings_path.read_text(encoding="utf-8"))
+    environment_list = written_settings.get("autoMode", {}).get("environment", [])
+    assert legacy_entry_a not in environment_list
+    assert legacy_entry_b not in environment_list
+    assert unrelated_other_project_entry in environment_list
+
+
+def test_template_constant_documents_agent_config_carveout() -> None:
+    assert "agent-config files always require explicit per-edit user approval" in (
+        AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE
+    )
+
+
+def test_is_trust_entry_for_project_predicate_filters_by_prefix_and_project_path() -> (
+    None
+):
+    project_path_posix = "/fake/proj"
+    trust_prefix = "Trusted local workspace:"
+    non_string_value: object = 42
+    assert (
+        common_module.is_trust_entry_for_project(
+            non_string_value, project_path_posix, trust_prefix
+        )
+        is False
+    )
+    wrong_prefix_entry = (
+        f"Something else: {project_path_posix}/.claude/** with marker token"
+    )
+    assert (
+        common_module.is_trust_entry_for_project(
+            wrong_prefix_entry, project_path_posix, trust_prefix
+        )
+        is False
+    )
+    different_project_entry = (
+        "Trusted local workspace: /other/project/.claude/** unrelated"
+    )
+    assert (
+        common_module.is_trust_entry_for_project(
+            different_project_entry, project_path_posix, trust_prefix
+        )
+        is False
+    )
+    matching_entry = (
+        f"Trusted local workspace: {project_path_posix}/.claude/** any wording form"
+    )
+    assert (
+        common_module.is_trust_entry_for_project(
+            matching_entry, project_path_posix, trust_prefix
+        )
+        is True
+    )
+
+
+def test_is_trust_entry_rejects_cross_project_path_suffix_collision() -> None:
+    """When the project_path is a path suffix of an unrelated entry's path,
+    the predicate must reject the unrelated entry (the boundary anchor case)."""
+    short_project_path = "/projects/foo"
+    trust_prefix = "Trusted local workspace:"
+    longer_unrelated_path_entry = (
+        "Trusted local workspace: /Users/jon/projects/foo/.claude/** unrelated path"
+    )
+    assert (
+        common_module.is_trust_entry_for_project(
+            longer_unrelated_path_entry, short_project_path, trust_prefix
+        )
+        is False
+    )
+    quoted_matching_entry = (
+        f'Trusted local workspace: "{short_project_path}/.claude/**" quoted form'
+    )
+    assert (
+        common_module.is_trust_entry_for_project(
+            quoted_matching_entry, short_project_path, trust_prefix
+        )
+        is True
+    )
+
+
+def test_second_grant_is_idempotent_when_no_other_settings_changed(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """Running grant twice in a row must perform zero changes the second time.
+
+    On the second call the existing trust entry is byte-identical to the
+    freshly-formatted current entry, so purge_stale_trust_entries treats it as
+    protected and does not remove it; add_auto_mode_environment_entry then
+    no-ops because the entry is already present.
+    """
+    fake_project_root = _make_fake_project(tmp_path)
+    fake_settings_path = _prepare_fake_home(tmp_path)
+    _seed_grant_then_run(
+        fake_settings_path, fake_project_root, monkeypatch, pre_existing_settings={}
+    )
+    first_run_output = capsys.readouterr()
+    assert "No changes needed" not in first_run_output.out
+    _redirect_settings_to_fake_path(fake_settings_path, monkeypatch)
+    monkeypatch.chdir(fake_project_root)
+    grant_module.grant_permissions_for_current_directory()
+    second_run_output = capsys.readouterr()
+    assert "No changes needed; settings file left untouched." in second_run_output.out
+    assert "Stale auto-mode environment entries purged" not in second_run_output.out
+
+
+def test_template_derives_human_readable_pattern_list_from_pattern_tuple() -> None:
+    """Every pattern in ALL_AGENT_CONFIG_PATH_PATTERNS must surface in the
+    rendered template through its derived human-readable form, and the
+    template must still expose the {project_path} placeholder for .format()
+    substitution at runtime."""
+    template_text: str = AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE
+    assert "{project_path}" in template_text
+    for each_pattern in ALL_AGENT_CONFIG_PATH_PATTERNS:
+        if each_pattern.endswith("/**"):
+            directory_name = each_pattern[: -len("/**")]
+            expected_phrase = f"anything under {directory_name}/"
+        elif each_pattern == "mcp.json":
+            expected_phrase = "the mcp.json file"
+        else:
+            expected_phrase = each_pattern
+        assert expected_phrase in template_text, (
+            f"template missing derived phrase for pattern {each_pattern!r}: "
+            f"expected {expected_phrase!r}"
+        )
+    rendered_template_text = template_text.format(project_path="/tmp/x")
+    assert "/tmp/x" in rendered_template_text

package/skills/bugteam/scripts/test_bugteam_fix_hookspath.py

@@ -356,29 +356,3 @@ def test_read_global_core_hooks_path_returns_empty_when_key_unset() -> None:
     with patch.object(subprocess, "run", fake_run):
         result = bugteam_fix_hookspath.read_global_core_hooks_path(None)
     assert result == ""
-
-
-def test_module_import_evicts_cached_config_submodules() -> None:
-    """Importing bugteam_fix_hookspath must evict cached `config.*` submodules.
-
-    Regression for loop1-1: without a defensive cache pop above sys.path.insert,
-    a previously-cached `config` package shadows scripts/config/ and the
-    from-import raises ModuleNotFoundError.
-    """
-    fake_submodule_name = "config.bugteam_fix_hookspath_constants"
-    fake_parent_name = "config"
-    sentinel_module_a = ModuleType(fake_parent_name)
-    sentinel_module_b = ModuleType(fake_submodule_name)
-    sys.modules[fake_parent_name] = sentinel_module_a
-    sys.modules[fake_submodule_name] = sentinel_module_b
-    try:
-        _load_fix_module()
-    finally:
-        sys.modules.pop(fake_parent_name, None)
-        sys.modules.pop(fake_submodule_name, None)
-    assert sys.modules.get(fake_parent_name) is not sentinel_module_a, (
-        "parent `config` cache entry must be evicted on module import"
-    )
-    assert sys.modules.get(fake_submodule_name) is not sentinel_module_b, (
-        "cached `config.<submodule>` entries must be evicted on module import"
-    )

package/skills/bugteam/scripts/{test_claude_permissions_common.py → test_bugteam_permissions_common.py}

@@ -1,7 +1,5 @@
-import importlib
 import sys
 from pathlib import Path
-from types import ModuleType
 from unittest.mock import patch
 
 import pytest
@@ -10,14 +8,14 @@ _script_directory = str(Path(__file__).resolve().parent)
 if _script_directory not in sys.path:
     sys.path.insert(0, _script_directory)
 
-import _claude_permissions_common as common_module
-from _claude_permissions_common import (
+import _bugteam_permissions_common as common_module
+from _bugteam_permissions_common import (
     build_permission_rule,
     get_current_project_path,
     path_contains_glob_metacharacters,
     save_settings,
 )
-from config.claude_permissions_common_constants import DEFAULT_SETTINGS_FILE_MODE
+from bugteam_scripts_constants.claude_permissions_common_constants import DEFAULT_SETTINGS_FILE_MODE
 import grant_project_claude_permissions as grant_module
 import revoke_project_claude_permissions as revoke_module
 
@@ -140,64 +138,3 @@ def test_is_valid_project_root_exported_from_consumer_modules(
     assert revoke_module.is_valid_project_root(bare_directory) is False
 
 
-def _reload_with_stale_config_cache(module_name: str) -> ModuleType:
-    fake_submodule_name = "config.claude_permissions_common_constants"
-    fake_parent_name = "config"
-    sentinel_module_a = ModuleType(fake_parent_name)
-    sentinel_module_b = ModuleType(fake_submodule_name)
-    sys.modules[fake_parent_name] = sentinel_module_a
-    sys.modules[fake_submodule_name] = sentinel_module_b
-    try:
-        target_module = sys.modules.get(module_name)
-        if target_module is None:
-            target_module = importlib.import_module(module_name)
-        else:
-            target_module = importlib.reload(target_module)
-    finally:
-        sys.modules.pop(fake_parent_name, None)
-        sys.modules.pop(fake_submodule_name, None)
-    return target_module
-
-
-def test_grant_module_import_evicts_cached_config_submodules(
-    tmp_path: Path,
-) -> None:
-    """grant_project_claude_permissions must evict cached `config.*` on import.
-
-    Regression for loop1-2: without a defensive cache pop above sys.path.insert,
-    a cached `config` package shadows scripts/config/ and the from-import raises.
-    Calls the rebound `is_valid_project_root` to confirm the real implementation
-    survived the cache eviction (a stale shadow would either raise on import or
-    bind a placeholder that returns the wrong value).
-    """
-    reloaded_module = _reload_with_stale_config_cache(
-        "grant_project_claude_permissions"
-    )
-    real_project_root = tmp_path / "project_root"
-    (real_project_root / ".claude").mkdir(parents=True)
-    bare_directory = tmp_path / "no_claude_marker"
-    bare_directory.mkdir()
-    assert reloaded_module.is_valid_project_root(real_project_root) is True
-    assert reloaded_module.is_valid_project_root(bare_directory) is False
-
-
-def test_revoke_module_import_evicts_cached_config_submodules(
-    tmp_path: Path,
-) -> None:
-    """revoke_project_claude_permissions must evict cached `config.*` on import.
-
-    Regression for loop1-3: without a defensive cache pop above sys.path.insert,
-    a cached `config` package shadows scripts/config/ and the from-import raises.
-    Calls the rebound `is_valid_project_root` to confirm the real implementation
-    survived the cache eviction (a stale shadow would either raise on import or
-    bind a placeholder that returns the wrong value).
-    """
-    reloaded_module = _reload_with_stale_config_cache(
-        "revoke_project_claude_permissions"
-    )
-    real_project_root = tmp_path / "project_root"
-    (real_project_root / ".claude").mkdir(parents=True)
-    bare_directory = tmp_path / "no_claude_marker"
-    bare_directory.mkdir()
-    assert reloaded_module.is_valid_project_root(real_project_root) is True
-    assert reloaded_module.is_valid_project_root(bare_directory) is False

package/skills/bugteam/scripts/test_bugteam_preflight.py

@@ -210,38 +210,13 @@ def test_should_exit_nonzero_when_subprocess_run_raises_os_error(
     )
 
 
-def test_module_import_evicts_cached_config_submodules() -> None:
-    """Importing bugteam_preflight must evict cached `config.*` submodules.
-
-    Regression for loop1-4: a single `sys.modules.pop("config", None)` only
-    removes the parent key, leaving stale `config.<submodule>` entries that
-    satisfy the next from-import with the wrong bindings.
-    """
-    fake_submodule_name = "config.bugteam_preflight_constants"
-    fake_parent_name = "config"
-    sentinel_module_a = ModuleType(fake_parent_name)
-    sentinel_module_b = ModuleType(fake_submodule_name)
-    sys.modules[fake_parent_name] = sentinel_module_a
-    sys.modules[fake_submodule_name] = sentinel_module_b
-    try:
-        _load_preflight_module()
-    finally:
-        sys.modules.pop(fake_parent_name, None)
-        sys.modules.pop(fake_submodule_name, None)
-    assert sys.modules.get(fake_parent_name) is not sentinel_module_a, (
-        "parent `config` cache entry must be evicted on module import"
-    )
-    assert sys.modules.get(fake_submodule_name) is not sentinel_module_b, (
-        "cached `config.<submodule>` entries must be evicted on module import"
-    )
-
-
 def test_has_pytest_configuration_finds_pytest_ini(tmp_path: Path) -> None:
     """has_pytest_configuration must detect pytest.ini at the repo root.
 
     Regression for loop1-17/loop1-18: the literals "pytest.ini",
     "pyproject.toml", and "[tool.pytest" were inlined in production function
-    bodies; centralizing them in config and importing here pins the contract.
+    bodies; centralizing them in bugteam_scripts_constants and importing here
+    pins the contract.
     """
     repository_root = tmp_path / "repo"
     repository_root.mkdir()

package/skills/bugteam/scripts/windows_safe_rmtree.py

@@ -16,7 +16,7 @@ import stat
 import sys
 from collections.abc import Callable
 
-from config.windows_safe_rmtree_constants import (
+from bugteam_scripts_constants.windows_safe_rmtree_constants import (
     EXIT_CODE_REMOVE_TREE_FAILURE,
     EXIT_CODE_USAGE_ERROR,
     EXPECTED_ARGUMENT_COUNT,

package/skills/doc-gist/SKILL.md

@@ -94,6 +94,6 @@ Read the matching example for the artifact you're designing. Crib palette, typog
 
 - `SKILL.md` — this file.
 - `skills/doc-gist/scripts/gist_upload.py` — transport: HTML in, gist + preview URLs out.
-- `skills/doc-gist/scripts/config/gist_upload_constants.py` — the URL prefixes and template strings.
+- `skills/doc-gist/scripts/doc_gist_scripts_constants/gist_upload_constants.py` — the URL prefixes and template strings.
 - `references/examples/` — Thariq's 20 html-effectiveness prototypes.
 - (PostToolUse hook lives in `packages/claude-dev-env/hooks/workflow/doc_gist_auto_publish.py` — wired into the plugin's `hooks.json`.)

package/skills/doc-gist/scripts/gist_upload.py

@@ -30,7 +30,7 @@ _script_directory = str(Path(__file__).resolve().parent)
 if _script_directory not in sys.path:
     sys.path.insert(0, _script_directory)
 
-from config.gist_upload_constants import (  # noqa: E402
+from doc_gist_scripts_constants.gist_upload_constants import (  # noqa: E402
     GIST_DEFAULT_FILENAME,
     GIST_HOST_PREFIX,
     MINIMUM_GIST_URL_PARTS,

package/skills/implement/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: implement
+description: "Implement a spec while maintaining a running implementation-notes.html file that captures design decisions, deviations, tradeoffs, and open questions. Triggers: /implement, implement this spec, build out this plan and keep notes."
+argument-hint: "[path to spec file, or omit to use a spec already in context]"
+---
+
+# implement
+
+Execute a spec end-to-end while keeping a sidecar `implementation-notes.html` that the user can read to see how the build diverged from or interpreted the written plan.
+
+## Instructions
+
+Carry out the following prompt against the spec resolved below.
+
+### Resolve `<SPEC>`
+
+- If `$ARGUMENTS` is non-empty, treat it as the path to the spec file and read it.
+- Otherwise, use the most recent plan / spec / design doc already present in the conversation context.
+- If neither is available, ask the user for the spec path via `AskUserQuestion` before proceeding.
+
+### Prompt to execute
+
+> Implement `<SPEC>`. As you work maintain a running `implementation-notes.html` file that captures anything I should know about how the implementation diverges from or interprets the spec, including:
+>
+> - **Design decisions:** choices you made where the spec was ambiguous
+> - **Deviations:** places where you intentionally departed from the spec, and why
+> - **Tradeoffs:** alternatives you considered and why you picked what you did
+> - **Open questions:** anything you'd want me to confirm or revise
+
+### How to write notes
+
+Run `${CLAUDE_SKILL_DIR}/scripts/append_note.py` to append each entry. The script creates `implementation-notes.html` with the four sections on first run, then inserts a new `<li>` under the requested section. HTML-escapes `--about` and `--note` automatically. `${CLAUDE_SKILL_DIR}` is host-substituted by Claude Code at runtime so the bundled CLI is found regardless of the current working directory.
+
+```
+python "${CLAUDE_SKILL_DIR}/scripts/append_note.py" \
+  --section decisions \
+  --about "Storage location" \
+  --note "Wrote notes next to the spec because the spec path was provided." \
+  --file /path/to/spec-dir/implementation-notes.html
+```
+
+`--section` choices (slug → heading):
+
+| Slug | Heading |
+|---|---|
+| `decisions` | Design decisions |
+| `deviations` | Deviations |
+| `tradeoffs` | Tradeoffs |
+| `questions` | Open questions |
+
+`--file` is optional. When omitted, the script writes to `./implementation-notes.html` in the current working directory. When a spec path is known, pass `--file` so notes land next to the spec rather than in CWD.
+
+Append entries as decisions are made — do not batch them until the end.
+
+## Gotchas
+
+- **Do not hand-edit `implementation-notes.html`.** The append script locates each section by its `<section id="...">` marker and the first `</ul>` after it. Editing the structure breaks subsequent appends; the script raises a `RuntimeError` naming the missing marker.
+- **`--about` and `--note` are HTML-escaped automatically** — pass raw text, not pre-escaped HTML.
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | This hub |
+| `packages/claude-dev-env/skills/implement/scripts/append_note.py` | CLI to append one entry to a section |
+| `packages/claude-dev-env/skills/implement/scripts/implement_scripts_constants/notes_constants.py` | Section slugs → headings and default filename |