claude-dev-env 2.0.1 → 2.0.2

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

@@ -1,31 +1,14 @@
 # Re-Stage Session Edits Before Commit
 
-**When this applies:** Any `git commit` run through the Bash tool in a git repository.
+Stage the files you edited this session right before you commit them. A plain `git commit` records only the staged snapshot; a tracked file this session changed but left unstaged stays behind in the working tree.
 
-## Rule
+`session_edit_stage_gate` (PreToolUse on Bash `git commit`) denies a commit that would drop tracked session edits and names the fix: `git add <paths>`, `git commit -a`, or a `# partial-commit` marker.
 
-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.
+## Escapes the denial does not restate
 
-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 pathspec** — `git commit -- <paths>` or `git commit <paths>` commits only the named paths on purpose and steps the gate aside.
+- **A preceding `git add` / `git stage`** — `git add <paths> && git commit …` stages the files in its own segment before the commit runs.
 
 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.
+`session_file_edit_tracker` (PostToolUse) records each Write/Edit/MultiEdit path; `session_edit_tracker_cleanup` (SessionStart, SessionEnd) clears the session's tracker.

package/rules/shell-invocation-policy.md

@@ -2,4 +2,4 @@
 
 Every Bash-tool shell command on Windows uses `pwsh`: `pwsh -NoProfile -File '<script>.ps1' <args>` for scripts, `pwsh -NoProfile -Command "..."` (or a literal `@'...'@` here-string) for inline work, or the built-in `PowerShell` tool for pure-PowerShell workflows (it supports `run_in_background`). Never wrap a script path in `-Command "& '...'"` — `-File` keeps `permissions.allow` matching. The `&` call operator is fine for invoking an executable at a path (`& '<venv>\Scripts\python.exe' script.py`).
 
-`powershell`, `powershell.exe`, `cmd /c`, and `bash -c` are blocked by `permissions.deny` and the `pwsh_enforcer.py` PreToolUse hook, which returns the corrective pattern. Audit and migration scripts (`Audit-ShellPolicy.ps1`, `Migrate-ShellPolicy.ps1`) live in `packages/claude-dev-env/scripts/`.
+Keep `powershell`, `powershell.exe`, `cmd /c`, and `bash -c` out of the `settings.json` permission rules. `Audit-ShellPolicy.ps1` reports those forms and `Migrate-ShellPolicy.ps1` rewrites them to `pwsh`, both in `packages/claude-dev-env/scripts/` and run on demand, not as a live gate.

package/rules/vault-context.md

@@ -1,7 +1,7 @@
 # Obsidian Vault Context
 
-An Obsidian vault stores session reports (`sessions/`), decisions (`decisions/`), and research (`Research/`) across projects. Resolve its location via the obsidian MCP tools — `mcp__obsidian__search_notes` (supports `searchFrontmatter: true`), `mcp__obsidian__read_note`, `mcp__obsidian__read_multiple_notes` — never assume an OS path.
+An Obsidian vault holds session reports (`sessions/`), decisions (`decisions/`), and research (`Research/`) across projects, reached through the obsidian MCP tools.
 
-IMPORTANT: Before substantive project work, search the vault for prior sessions and decisions for the current project — by `project` frontmatter first, then keywords ("blocked", "superseded", "decision", "gotcha"). Also search when touching a component with known history or when a task might repeat or reverse a prior decision.
+Before substantive project work, search the vault for prior sessions and decisions on the current project through the `recall` skill — by `project` frontmatter first, then by keyword. Search again when touching a component with known history, or when a task might repeat or reverse a prior decision.
 
-Session logging runs through `/session-log` (same full flow for short and long sessions); offer it at the end of substantive sessions. Reports include `vault_context_retrieved: true|false` and `session_id` (from `CLAUDE_CODE_SESSION_ID`; literal `unknown` when unset) in frontmatter, and every session log ends with a `/rename [Project] - [Primary Outcome]` command — mandatory output, never optional.
+At the end of a substantive session, offer the `session-log` skill; it owns the report format, the `vault_context_retrieved` and `session_id` frontmatter, and the closing `/rename` hand-off.

package/rules/workers-done-before-complete.md

@@ -1,33 +1,5 @@
 # Workers Done Before Complete
 
-**When this applies:** Before marking any task `completed` when the task spawned workers — subagents, workflow agents, or background shells.
+Before marking a task `completed` that spawned workers — subagents, workflow agents, or background shells — confirm both: every worker has finished, and each worker's result is merged into run state (`state.json`, `pr-converge-state.json`, the task list, or whatever record the task keeps). A worker still running, or one whose output never landed in run state, keeps the task `in_progress`: list the live workers, report any dead or hung one as a finding rather than dropping it in silence, and schedule a wakeup so the run picks the workers back up before the task closes.
 
-## Rule
-
-A task reaches `completed` only when two things hold: every worker it spawned has finished, and each worker's result is merged into run state — `state.json`, `pr-converge-state.json`, the task list, or whatever record the task keeps. A worker that still runs, or one that finished but whose output never landed in run state, leaves the task open.
-
-List the live workers before you mark the task complete. When a worker is dead or hung, that is a finding to record and report, not a result to drop in silence. A step that waits on workers ends its turn `in_progress` with a wakeup scheduled, so the run picks the workers back up rather than closing the task without them.
-
-## Checklist before marking complete
-
-| Check | Action |
-|---|---|
-| Are any spawned workers still running? | List them; if yes, stay `in_progress` and schedule a wakeup. |
-| Did every finished worker return a result? | Read each result; a dead or hung worker is a finding to report. |
-| Is each result merged into run state? | Write it to `state.json` / the task list before closing. |
-| Does the task's own goal now hold? | Confirm against the merged state, not a worker's self-report. |
-
-Mark `completed` only when every row passes.
-
-## Examples
-
-**Wrong:** Marking the audit task complete while two bugteam workers still run in the background.
-**Right:** List the workers, see two still running, keep the task `in_progress`, and schedule a wakeup to collect them.
-
-**Wrong:** A worker crashes; the task closes as complete because the other workers finished.
-**Right:** Record the crashed worker as a finding, report it, and hold the task open until its work is covered.
-
-## Relationship to other rules
-
-- **`long-horizon-autonomy`** covers acting on what you have and not ending a turn on a promise. This rule names the specific completion gate: workers finished and their results merged.
-- **`skills/pr-converge/reference/state-schema.md`** defines the run-state records this rule requires a worker's result to land in before the task closes.
+Checklist, examples, and run-state detail: `@~/.claude/docs/worker-completion-gate.md`.

package/scripts/claude_chain_runner.py

@@ -19,6 +19,12 @@ A usage-limited primary falls over to the second binary::
     primary claude     -> exit 1, "usage limit reached"  (falls over)
     fallback claude-ev -> exit 0                          (served)
 
+When stdin is piped (not a TTY), the runner reads it once and forwards the
+same text to every chain attempt so a piped ``-p`` charter body reaches each
+binary in the walk::
+
+    cat charter.md | python claude_chain_runner.py -- -p --strict-mcp-config
+
 Import ``run_claude`` for the outcome object, or run the module as a CLI::
 
     python claude_chain_runner.py [--timeout-seconds N] -- <claude args...>
@@ -27,11 +33,13 @@ Import ``run_claude`` for the outcome object, or run the module as a CLI::
 from __future__ import annotations
 
 import argparse
+import io
 import json
 import subprocess
 import sys
 from dataclasses import dataclass
 from pathlib import Path
+from typing import TextIO
 
 from dev_env_scripts_constants.claude_chain_constants import (
     ALL_USAGE_LIMIT_SIGNATURES,
@@ -48,6 +56,7 @@ from dev_env_scripts_constants.claude_chain_constants import (
     CLAUDE_HOME_SUBDIRECTORY,
     CLI_ARGUMENTS_SEPARATOR,
     CLI_TIMEOUT_FLAG,
+    CODEC_ERROR_STRATEGY,
     CONFIG_CHAIN_EMPTY_REASON,
     CONFIG_CHAIN_KEY,
     CONFIG_CHAIN_NOT_LIST_REASON,
@@ -283,7 +292,10 @@ def _classify_completion(
 
 
 def run_claude(
-    all_claude_arguments: list[str], *, timeout_seconds: int
+    all_claude_arguments: list[str],
+    *,
+    timeout_seconds: int,
+    stdin_text: str | None = None,
 ) -> ChainInvocationOutcome:
     """Run *all_claude_arguments* through the configured fallback chain.
 
@@ -291,12 +303,16 @@ def run_claude(
     exit whose output carries a usage-limit signature) falls over to the next
     binary. A missing fallback binary is skipped and the walk continues. A
     timeout, a missing primary binary, or a non-zero exit without a usage-limit
-    signature stops the walk and returns that outcome unchanged.
+    signature stops the walk and returns that outcome unchanged. When
+    *stdin_text* is set, that same text is supplied as stdin on every chain
+    attempt.
 
     Args:
         all_claude_arguments: Arguments passed after the binary name, such as
             ``["-p", prompt, "--strict-mcp-config"]``.
         timeout_seconds: Timeout applied to each binary invocation.
+        stdin_text: Optional UTF-8 text forwarded as stdin to every binary.
+            ``None`` leaves the subprocess without a piped stdin body.
 
     Returns:
         The outcome of the walk, naming the serving binary and the full
@@ -315,8 +331,11 @@ def run_claude(
                 _build_invocation(each_entry, all_claude_arguments),
                 capture_output=True,
                 text=True,
+                encoding=UTF8_ENCODING,
+                errors=CODEC_ERROR_STRATEGY,
                 timeout=timeout_seconds,
                 check=False,
+                input=stdin_text,
             )
         except subprocess.TimeoutExpired as timeout_error:
             all_attempts.append(
@@ -368,6 +387,12 @@ def _exhausted_message(all_attempts: tuple[ChainAttempt, ...]) -> str:
     return CHAIN_EXHAUSTED_MESSAGE_TEMPLATE.format(attempt_summary=attempt_summary)
 
 
+def _read_piped_stdin_text() -> str | None:
+    if sys.stdin.isatty():
+        return None
+    return sys.stdin.read()
+
+
 def main(all_command_arguments: list[str]) -> int:
     """Walk the chain for CLI arguments and return the process exit code.
 
@@ -381,9 +406,12 @@ def main(all_command_arguments: list[str]) -> int:
     parser = _build_argument_parser()
     parsed_arguments = parser.parse_args(all_command_arguments)
     all_claude_arguments = _strip_leading_separator(parsed_arguments.passthrough)
+    maybe_stdin_text = _read_piped_stdin_text()
     try:
         chain_outcome = run_claude(
-            all_claude_arguments, timeout_seconds=parsed_arguments.timeout_seconds
+            all_claude_arguments,
+            timeout_seconds=parsed_arguments.timeout_seconds,
+            stdin_text=maybe_stdin_text,
         )
     except ChainConfigurationError as configuration_error:
         print(str(configuration_error), file=sys.stderr)
@@ -396,5 +424,13 @@ def main(all_command_arguments: list[str]) -> int:
     return chain_outcome.returncode
 
 
+def _reconfigure_stream_to_utf8(stream: TextIO) -> None:
+    """Reconfigure *stream* to emit UTF-8, replacing any unmappable character."""
+    if isinstance(stream, io.TextIOWrapper):
+        stream.reconfigure(encoding=UTF8_ENCODING, errors=CODEC_ERROR_STRATEGY)
+
+
 if __name__ == "__main__":
+    _reconfigure_stream_to_utf8(sys.stdout)
+    _reconfigure_stream_to_utf8(sys.stderr)
     sys.exit(main(sys.argv[1:]))

package/scripts/dev_env_scripts_constants/claude_chain_constants.py

@@ -9,6 +9,9 @@ from __future__ import annotations
 UTF8_ENCODING: str = "utf-8"
 """Encoding used to read the chain configuration file."""
 
+CODEC_ERROR_STRATEGY: str = "replace"
+"""Codec error handler that maps any unencodable or undecodable value to a marker."""
+
 CLAUDE_HOME_SUBDIRECTORY: str = ".claude"
 """Per-user directory under the home directory that holds the chain config."""
 

package/scripts/test_claude_chain_runner.py

@@ -1,6 +1,7 @@
 """Behavioral tests for the claude fallback-chain runner."""
 
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -78,20 +79,32 @@ class _Recorder:
         self.behavior_by_command = behavior_by_command
         self.invocations = []
         self.timeouts = []
+        self.all_keyword_arguments = []
 
     def __call__(self, invocation, **keyword_arguments):
         self.invocations.append(invocation)
         self.timeouts.append(keyword_arguments.get("timeout"))
+        self.all_keyword_arguments.append(keyword_arguments)
         behavior = self.behavior_by_command[invocation[0]]
         if isinstance(behavior, BaseException):
             raise behavior
         return behavior
 
 
+class _TtyStdin:
+    def isatty(self) -> bool:
+        return True
+
+
+def _install_tty_stdin(monkeypatch):
+    monkeypatch.setattr(runner.sys, "stdin", _TtyStdin())
+
+
 def _install(monkeypatch, config_file, behavior_by_command):
     recorder = _Recorder(behavior_by_command)
     monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
     monkeypatch.setattr(runner, "chain_subprocess_runner", recorder)
+    _install_tty_stdin(monkeypatch)
     return recorder
 
 
@@ -276,6 +289,45 @@ def test_extra_args_are_appended_to_invocation(
     assert recorder.invocations[0] == ["claude", "-p", "hello", "--account", "ev"]
 
 
+def test_run_claude_forwards_stdin_text_to_subprocess(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+    runner.run_claude(
+        _PROMPT_ARGUMENTS, timeout_seconds=5, stdin_text="charter body"
+    )
+    assert recorder.all_keyword_arguments[0]["input"] == "charter body"
+
+
+def test_run_claude_passes_none_input_when_stdin_text_omitted(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+    runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert recorder.all_keyword_arguments[0].get("input") is None
+
+
+def test_cli_forwards_piped_stdin_to_invocation(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+
+    class _PipedStdin:
+        def isatty(self) -> bool:
+            return False
+
+        def read(self) -> str:
+            return "charter body"
+
+    monkeypatch.setattr(runner.sys, "stdin", _PipedStdin())
+    exit_code = runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
+    assert exit_code == 0
+    assert recorder.all_keyword_arguments[0]["input"] == "charter body"
+
+
 def test_signature_matching_is_case_insensitive(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
@@ -362,6 +414,7 @@ def test_cli_missing_config_exits_config_error(
 ) -> None:
     missing_config = tmp_path / CONFIG_FILENAME
     monkeypatch.setattr(runner, "chain_config_path", lambda: missing_config)
+    _install_tty_stdin(monkeypatch)
     exit_code = runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
     captured = capsys.readouterr()
     assert exit_code == CHAIN_CONFIG_ERROR_EXIT_CODE
@@ -470,3 +523,62 @@ def test_chain_config_path_points_at_home_config() -> None:
     config_path = runner.chain_config_path()
     assert config_path.name == CONFIG_FILENAME
     assert CLAUDE_HOME_SUBDIRECTORY in config_path.parts
+
+
+def test_real_subprocess_capture_replaces_undecodable_bytes(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry(sys.executable)])
+    monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
+    child_code = 'import sys; sys.stdout.buffer.write(b"ok \\x90 end")'
+    chain_result = runner.run_claude(["-c", child_code], timeout_seconds=60)
+    assert chain_result.served_command == sys.executable
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "ok � end"
+
+
+def test_real_subprocess_capture_preserves_utf8_text(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry(sys.executable)])
+    monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
+    child_code = 'import sys; sys.stdout.buffer.write("report ✅ done".encode("utf-8"))'
+    chain_result = runner.run_claude(["-c", child_code], timeout_seconds=60)
+    assert chain_result.served_command == sys.executable
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "report ✅ done"
+
+
+def test_cli_emits_utf8_when_console_encoding_is_legacy(tmp_path: Path) -> None:
+    tmp_home = tmp_path / "home"
+    claude_directory = tmp_home / CLAUDE_HOME_SUBDIRECTORY
+    claude_directory.mkdir(parents=True)
+    config_file = claude_directory / CONFIG_FILENAME
+    config_file.write_text(
+        json.dumps({CONFIG_CHAIN_KEY: [_entry(sys.executable)]}),
+        encoding=UTF8_ENCODING,
+    )
+    runner_script = _SCRIPTS_DIR / "claude_chain_runner.py"
+    child_code = 'import sys; sys.stdout.buffer.write("report ✅".encode("utf-8"))'
+    legacy_console_encoding = "cp1252"
+    child_environment = dict(os.environ)
+    child_environment["USERPROFILE"] = str(tmp_home)
+    child_environment["HOME"] = str(tmp_home)
+    child_environment["PYTHONIOENCODING"] = legacy_console_encoding
+    child_environment.pop("PYTHONUTF8", None)
+    runner_command = [
+        sys.executable,
+        str(runner_script),
+        CLI_ARGUMENTS_SEPARATOR,
+        "-c",
+        child_code,
+    ]
+    completed = subprocess.run(
+        runner_command,
+        capture_output=True,
+        env=child_environment,
+        timeout=60,
+    )
+    assert completed.returncode == 0
+    assert b"Traceback" not in completed.stderr
+    assert "report ✅" in completed.stdout.decode(UTF8_ENCODING)

package/scripts/test_grok_headless_runner.py

@@ -418,7 +418,6 @@ def test_tightened_auth_phrases_still_classify_auth_failure(
         assert outcome.classification == CLASSIFICATION_AUTH_FAILURE, each_stderr
 
 
-def test_dual_match_prefers_auth_failure_over_usage_limit(
 def test_missing_binary_returns_dedicated_error(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:

package/skills/auditing-claude-config/SKILL.md

@@ -31,7 +31,7 @@ These come from the official Claude Code documentation; do not re-derive them.
 | Files in `.claude/rules/` without `paths:` frontmatter load **every** session | "Rules without `paths` frontmatter are loaded unconditionally and apply to all files" |
 | Path-scoped rules load **lazily** when matching files are accessed | "Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns" |
 | Skills preload **metadata only** | "At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed" |
-| `@`-imports inside fenced/inline code blocks do not trigger imports | Empirical (verified in this skill's source session) — referenced files alongside backtick-wrapped `@` paths do not appear in session-start context |
+| `@`-imports inside fenced/inline code blocks do not trigger imports | Empirical (`InstructionsLoaded` hook): a bare `@`-import fires an `include` load event; the same path wrapped in backticks fires none, so the referenced file stays out of session-start context |
 
 ## Audit workflow
 

package/skills/everything-search/SKILL.md

@@ -13,7 +13,13 @@ Search files instantly on Windows using the Everything command-line interface (e
 
 ## Hard limits
 
-Scope and fallback policy: `packages/claude-dev-env/rules/es-exe-file-search.md`.
+Every search carries a scope: a project path or registry token, an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern. A bare whole-drive scan or a network-share sweep is out of bounds — narrow the search to what you need.
+
+When `es.exe` fails or returns nothing, self-heal first: fall back to the `Glob` tool (name and path patterns) or `Grep` (file contents), and report the outage so the reader knows the index was unavailable. When self-healing also fails, ask the user through `AskUserQuestion` with a short analysis and next-step options.
+
+## Registry tokens
+
+The `es_exe_path_rewriter` hook resolves scope tokens before the command runs. A `{project-name}` placeholder or a bare registry key from `~/.claude/project-paths.json` becomes its quoted absolute path in the command. The hook allows and rewrites — it never blocks — so a search scoped to a registered project names the project token and lets the hook fill in the path.
 
 ## Instructions