claude-dev-env 1.85.0 → 1.86.0

package/hooks/session/task_list_loop_starter.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""SessionStart hook — start a task-list maintenance loop for the session.
+
+At session start this hook emits an ``additionalContext`` directive asking Claude
+to keep the session's task list current on a 10-minute cadence, starting the
+``/loop`` skill when one is not already running. The hook writes nothing and runs
+no tools itself. Claude reads the directive and invokes the ``/loop`` skill.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.task_list_loop_starter_constants import (  # noqa: E402
+    TASK_LIST_LOOP_DIRECTIVE,
+)
+
+
+def build_session_directive() -> str:
+    """Return the task-list loop directive emitted at session start."""
+    return TASK_LIST_LOOP_DIRECTIVE
+
+
+def main() -> None:
+    """Emit the task-list loop directive as SessionStart additionalContext."""
+    print(json.dumps({"additionalContext": build_session_directive()}))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/test_session_edit_tracker_cleanup.py

@@ -0,0 +1,157 @@
+"""Behavior tests for the session_edit_tracker_cleanup hook.
+
+The cleanup deletes only the running session's own session-edit file, and only
+on a fresh startup (SessionStart with a ``startup`` source) or a session end. A
+SessionStart that continues the same conversation — a compact or a resume —
+keeps the in-flight tracker. A peer session's file is always left alone,
+regardless of its age. These tests redirect ``tempfile.gettempdir`` to a
+temporary directory, seed it with the current session's file and peer-session
+files, run the hook's ``main`` through a lifecycle payload, and confirm which
+files survive.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import io
+import json
+import os
+import pathlib
+import sys
+import tempfile
+import time
+from unittest import mock
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+_HOOKS_TREE = _HOOK_DIR.parent
+for each_path in (str(_HOOK_DIR), str(_HOOKS_TREE)):
+    if each_path not in sys.path:
+        sys.path.insert(0, each_path)
+
+hook_spec = importlib.util.spec_from_file_location(
+    "session_edit_tracker_cleanup",
+    _HOOK_DIR / "session_edit_tracker_cleanup.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
+    ALL_EDITED_FILE_PATHS_KEY,
+    SESSION_EDIT_FILE_PREFIX,
+    SESSION_EDIT_FILE_SUFFIX,
+    STATE_FILE_DEFAULT_SESSION_ID,
+)
+
+AGED_TRACKER_FILE_SECONDS = 1860
+
+
+def _run_main_with_stdin(input_text: str) -> None:
+    with (
+        mock.patch("sys.stdin", io.StringIO(input_text)),
+        mock.patch("sys.stdout", new_callable=io.StringIO),
+        contextlib.suppress(SystemExit),
+    ):
+        hook_module.main()
+
+
+@pytest.fixture()
+def redirected_temp_directory(
+    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> pathlib.Path:
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp_path))
+    return tmp_path
+
+
+def _seed_edit_file(temp_directory: pathlib.Path, session_id: str) -> pathlib.Path:
+    edit_file = temp_directory / f"{SESSION_EDIT_FILE_PREFIX}{session_id}{SESSION_EDIT_FILE_SUFFIX}"
+    edit_file.write_text(json.dumps({ALL_EDITED_FILE_PATHS_KEY: []}), encoding="utf-8")
+    return edit_file
+
+
+def _age_file(target_file: pathlib.Path, age_seconds: float) -> None:
+    old_time = time.time() - age_seconds
+    os.utime(target_file, (old_time, old_time))
+
+
+def _session_start_payload(session_id: str) -> str:
+    return json.dumps({"session_id": session_id, "source": "startup"})
+
+
+def _session_continuation_payload(session_id: str, source: str) -> str:
+    return json.dumps({"session_id": session_id, "source": source})
+
+
+def _session_end_payload(session_id: str) -> str:
+    return json.dumps({"session_id": session_id, "hook_event_name": "SessionEnd"})
+
+
+def test_main_keeps_other_session_stale_tracker(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    other_session_file = _seed_edit_file(redirected_temp_directory, "idle-live-session")
+    _age_file(other_session_file, AGED_TRACKER_FILE_SECONDS)
+    _run_main_with_stdin(_session_start_payload("currentsession"))
+    assert other_session_file.exists()
+
+
+def test_should_keep_fresh_edit_file(redirected_temp_directory: pathlib.Path) -> None:
+    fresh_file = _seed_edit_file(redirected_temp_directory, "other-live-session")
+    _run_main_with_stdin(_session_start_payload("currentsession"))
+    assert fresh_file.exists()
+
+
+def test_should_remove_current_session_edit_file(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    current_file = _seed_edit_file(redirected_temp_directory, "currentsession")
+    _run_main_with_stdin(_session_start_payload("currentsession"))
+    assert not current_file.exists()
+
+
+def test_main_removes_current_session_stale_tracker(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    current_file = _seed_edit_file(redirected_temp_directory, "currentsession")
+    _age_file(current_file, AGED_TRACKER_FILE_SECONDS)
+    _run_main_with_stdin(_session_start_payload("currentsession"))
+    assert not current_file.exists()
+
+
+@pytest.mark.parametrize("continuation_source", ["compact", "resume"])
+def test_should_keep_current_session_tracker_on_continuation(
+    redirected_temp_directory: pathlib.Path, continuation_source: str
+) -> None:
+    current_file = _seed_edit_file(redirected_temp_directory, "currentsession")
+    _run_main_with_stdin(
+        _session_continuation_payload("currentsession", continuation_source)
+    )
+    assert current_file.exists()
+
+
+def test_should_remove_current_session_tracker_on_session_end(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    current_file = _seed_edit_file(redirected_temp_directory, "currentsession")
+    _run_main_with_stdin(_session_end_payload("currentsession"))
+    assert not current_file.exists()
+
+
+def test_should_exit_zero_on_malformed_stdin(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    fresh_file = _seed_edit_file(redirected_temp_directory, "other-live-session")
+    _run_main_with_stdin("not valid json {{{")
+    assert fresh_file.exists()
+
+
+def test_malformed_stdin_keeps_default_session_tracker(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    default_file = _seed_edit_file(redirected_temp_directory, STATE_FILE_DEFAULT_SESSION_ID)
+    _run_main_with_stdin("not valid json {{{")
+    assert default_file.exists()

package/hooks/session/test_task_list_loop_starter.py

@@ -0,0 +1,53 @@
+"""Tests for task_list_loop_starter — SessionStart hook that starts a task-list loop."""
+
+import json
+import sys
+from io import StringIO
+from pathlib import Path
+from unittest.mock import patch
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import task_list_loop_starter as starter
+
+from hooks_constants.task_list_loop_starter_constants import (
+    TASK_LIST_LOOP_DIRECTIVE,
+    TASK_LIST_MAINTENANCE_INSTRUCTION,
+)
+
+
+def _run_main() -> str:
+    """Return stdout produced by running the hook's main()."""
+    captured_stdout = StringIO()
+    with patch("sys.stdout", captured_stdout):
+        starter.main()
+    return captured_stdout.getvalue()
+
+
+class TestSessionDirective:
+    def test_main_emits_additional_context(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "additionalContext" in emitted
+
+    def test_directive_carries_the_one_line_instruction(self) -> None:
+        emitted = json.loads(_run_main())
+        assert TASK_LIST_MAINTENANCE_INSTRUCTION in emitted["additionalContext"]
+
+    def test_directive_names_the_ten_minute_cadence(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "10-minute" in emitted["additionalContext"]
+
+    def test_directive_names_the_loop_command(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "/loop 10m" in emitted["additionalContext"]
+
+    def test_directive_is_idempotent_about_an_existing_loop(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "not already running" in emitted["additionalContext"]
+
+    def test_build_session_directive_returns_the_shared_constant(self) -> None:
+        assert starter.build_session_directive() == TASK_LIST_LOOP_DIRECTIVE

package/package.json

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

package/rules/CLAUDE.md

@@ -36,6 +36,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
 | `plain-language.md` | Everyday words, short active sentences, lead with the answer |
 | `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
+| `re-stage-before-commit.md` | Stage the files edited this session before `git commit`; the session edit stage gate denies a commit that leaves a tracked session edit unstaged, with `-a`, a pathspec, a preceding `git add`, and `# partial-commit` as escapes |
 | `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
 | `right-sized-engineering.md` | Simple over clever; functions over classes; concrete over abstract |
 | `self-contained-docs.md` | Every document is fully self-contained; no references to the conversation that produced it |

package/rules/re-stage-before-commit.md

@@ -0,0 +1,31 @@
+# Re-Stage Session Edits Before Commit
+
+**When this applies:** Any `git commit` run through the Bash tool in a git repository.
+
+## Rule
+
+Stage the files you edited this session right before you commit them. A file this session changed but left unstaged is dropped by a plain `git commit` — the commit records the staged snapshot and the edit stays behind in the working tree.
+
+The `session_edit_stage_gate` hook holds you to this. It reads the per-session tracker that records every file the session edited, checks which of those files are tracked yet still unstaged at commit time, and denies the commit when any are left out. The denial names each file and gives the exact fix: `git add <paths>`, `git commit -a`, or a `# partial-commit` marker.
+
+## What the gate allows
+
+The gate steps aside for a commit that skips staged files on purpose:
+
+- **`-a` / `--all`** — the commit already takes every tracked change, so nothing is dropped.
+- **A pathspec** — `git commit -- <paths>` or `git commit <paths>` commits only the named paths on purpose.
+- **A preceding `git add` / `git stage`** — `git add <paths> && git commit …` stages the files in its own segment before the commit runs, so they are staged by the time the commit records the index.
+- **`# partial-commit`** — add this marker to the command to commit the staged set on purpose and leave the rest.
+
+A `--amend` does not step the gate aside: an amend records the staged snapshot too, so an unstaged session edit is dropped the same way a plain commit drops it.
+
+A missing tracker file or any git failure allows the commit, so the gate never blocks on a tooling problem.
+
+## Companion hooks
+
+- `session_file_edit_tracker` (PostToolUse) records the resolved absolute path of each Write, Edit, and MultiEdit into the per-session tracker file.
+- `session_edit_tracker_cleanup` (SessionStart, SessionEnd) deletes the running session's own tracker file: at a fresh SessionStart so a new session begins with an empty record, and at SessionEnd so a clean exit leaves nothing behind. A tracker is read only by the session that wrote it, so a file a crashed session leaves behind is inert and no peer session touches it.
+
+## Why
+
+A stale git index is a quiet failure: the commit succeeds, the branch looks right, and one file you meant to include never lands. Catching it at commit time keeps the staged set and the session's edits in step.