claude-dev-env 1.85.0 → 1.86.1

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.1",
     "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.

package/skills/autoconverge/SKILL.md

@@ -476,10 +476,10 @@ and `jl-cmd/claude-code-config` for rules and skills both appear):
 2. **Converge the generation.** Launch `workflow/converge_multi.mjs` with one
    entry per checked-out deferred PR, exactly as the
    [multi-PR launch](#launch-the-multi-pr-workflow) describes. Each child run
-   re-checks Copilot and Bugbot availability every round through the workflow's own
-   pre-spawn probe, so a reviewer that is down or out of quota is never spawned in any
-   generation; the `copilotDisabled`/`bugbotDisabled` flags each deferred PR carries
-   seed that check for the first round.
+   checks Copilot and Bugbot availability through the workflow's own preflight-git
+   probe, carried across rounds, so a reviewer that is down or out of quota is never
+   spawned in any generation; the `copilotDisabled`/`bugbotDisabled` flags each
+   deferred PR carries seed that check for the first round.
 3. **Tear down.** Run the [multi-PR teardown](#multi-pr-teardown-on-workflow-completion)
    over the generation's `results`, and revoke project permissions once per
    repository.

package/skills/autoconverge/reference/gotchas.md

@@ -22,8 +22,9 @@ fails in a new way.
   bug-audit lenses both diff against `origin/main`. Concurrent `git fetch` calls
   contend on the worktree `.git` lock and fail intermittently, so the workflow
   runs a single serial `git fetch origin main` inside the merged `preflight-git`
-  step — the one git-utility agent that also resolves the PR HEAD SHA and probes
-  mergeability — and the parallel lenses run no git fetch of their own; they
+  step — the one git-utility agent that also resolves the PR HEAD SHA, probes
+  mergeability, and checks Copilot and Bugbot availability — and the parallel
+  lenses run no git fetch of their own; they
   diff against the already-current ref. The workflow threads the resolved HEAD
   through the rounds and re-runs `preflight-git` only after a push or rebase
   invalidates it, so a round on an unchanged HEAD spawns no git agent at all.

package/skills/autoconverge/reference/stop-conditions.md

@@ -36,8 +36,22 @@ skill still runs teardown (revoke permissions, final report).
   denied, errors, or its agent dies). The convergence gate's bugteam-review
   check can never pass without that CLEAN review, so the run stops rather than
   re-converge to the iteration cap. The `blocker` names the post failure and the
-  HEAD. Unblock by allowing `post_audit_thread.py` with a Bash permission rule,
-  or post the CLEAN review by hand, then re-run.
+  HEAD. Unblock a permission denial by allowing `post_audit_thread.py` with a
+  Bash permission rule. Unblock any other failure by creating a fresh temporary
+  file whose exact content is an empty JSON array (`[]`) and re-running the run's
+  own `post_audit_thread.py --skill bugteam --state CLEAN` command for the
+  lens-verified HEAD with that file as `--findings-json`; then re-run the
+  workflow. A CLEAN post carries an empty findings array by construction, so this
+  re-issues the run's own command for the outcome the lenses already established
+  for that HEAD.
+- **No review lens reviewed HEAD** — a round can end with no lens having reviewed
+  the HEAD three ways: the preflight resolves no SHA, every lens agent dies, or
+  every lens is down or disabled. A single such round retries on the next round.
+  Three consecutive no-lens-reviewed rounds (any mix of the three causes) reach
+  `CONFIG.maxConsecutiveNoLensRounds` and stop the run with a `blocker` that names
+  the consecutive count and only the causes that actually occurred, rather than
+  looping to the iteration cap. Any round in which at least one lens reviews the
+  HEAD resets the consecutive count.
 
 ## Not a blocker (the run continues)
 
@@ -58,10 +72,12 @@ skill still runs teardown (revoke permissions, final report).
   Bugbot lens (null result) counts as down for that HEAD, so the convergence
   check runs with `--bugbot-down` rather than demanding a Bugbot verdict the
   dead agent never produced.
-- **Every lens agent dies** — when all three parallel lenses return null in the
-  same round, the round is a failure, not a clean: the workflow posts no CLEAN
-  bugteam artifact and does not advance to the Copilot gate. It re-resolves HEAD
-  and retries on the next round, still bounded by the iteration cap.
+- **Every lens agent dies (a single round)** — when all three parallel lenses
+  return null in the same round, the round is a failure, not a clean: the
+  workflow posts no CLEAN bugteam artifact and does not advance to the Copilot
+  gate. It re-resolves HEAD and retries on the next round. This is a
+  no-lens-reviewed round, so consecutive occurrences are bounded by the
+  no-review-lens cap in the blockers above, not just the iteration cap.
 
 ## User stop