claude-dev-env 2.9.0 → 2.11.0

package/hooks/session/test_issue_tracker_session_starter.py

@@ -0,0 +1,104 @@
+"""Tests for the repository-gated issue-tracker SessionStart starter."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from hooks_constants.issue_tracker_session_starter_constants import (
+    ISSUE_TRACKER_SESSION_START_DIRECTIVE,
+    ISSUE_TRACKER_SESSION_STARTER_ENABLED_ENV_VAR,
+    ISSUE_TRACKER_STARTER_TIMEOUT_MILLISECONDS,
+)
+from session.issue_tracker_session_starter import (
+    issue_tracker_session_starter_enabled_in_environment,
+    repository_is_registered,
+    run_issue_tracker_session_starter,
+)
+
+STARTER_SCRIPT = Path(__file__).resolve().parent / "issue_tracker_session_starter.py"
+DEFAULT_TIMEOUT = ISSUE_TRACKER_STARTER_TIMEOUT_MILLISECONDS
+
+
+def test_default_environment_is_disabled(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv(ISSUE_TRACKER_SESSION_STARTER_ENABLED_ENV_VAR, raising=False)
+    assert issue_tracker_session_starter_enabled_in_environment() is False
+
+
+def test_enabled_env_values(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(ISSUE_TRACKER_SESSION_STARTER_ENABLED_ENV_VAR, "1")
+    assert issue_tracker_session_starter_enabled_in_environment() is True
+    monkeypatch.setenv(ISSUE_TRACKER_SESSION_STARTER_ENABLED_ENV_VAR, "true")
+    assert issue_tracker_session_starter_enabled_in_environment() is True
+
+
+def test_disabled_or_ineligible_emits_nothing() -> None:
+    assert (
+        run_issue_tracker_session_starter(
+            {"source": "startup"}, False, True, DEFAULT_TIMEOUT
+        )
+        == {}
+    )
+    assert (
+        run_issue_tracker_session_starter(
+            {"source": "startup"}, True, False, DEFAULT_TIMEOUT
+        )
+        == {}
+    )
+
+
+def test_enabled_eligible_startup_emits_directive() -> None:
+    payload = run_issue_tracker_session_starter(
+        {"source": "startup"}, True, True, DEFAULT_TIMEOUT
+    )
+    assert payload["additionalContext"] == ISSUE_TRACKER_SESSION_START_DIRECTIVE
+
+
+def test_timeout_zero_emits_nothing() -> None:
+    assert (
+        run_issue_tracker_session_starter({"source": "startup"}, True, True, 0) == {}
+    )
+
+
+def test_unknown_source_emits_nothing() -> None:
+    assert (
+        run_issue_tracker_session_starter({"source": "weird"}, True, True, DEFAULT_TIMEOUT)
+        == {}
+    )
+
+
+def test_repository_is_registered_fail_closed_empty_registry() -> None:
+    assert repository_is_registered("/any/path", {}) is False  # empty registry fails closed
+
+
+def test_repository_is_registered_matches_git_root(tmp_path: Path) -> None:
+    (tmp_path / ".git").mkdir()
+    child = tmp_path / "pkg"
+    child.mkdir()
+    registry = {"demo": str(tmp_path)}
+    assert repository_is_registered(str(child), registry) is True
+    assert repository_is_registered(str(tmp_path / "other"), {"demo": str(tmp_path / "nope")}) is False
+
+
+def test_main_disabled_prints_nothing() -> None:
+    environment_by_key = os.environ.copy()
+    environment_by_key.pop(ISSUE_TRACKER_SESSION_STARTER_ENABLED_ENV_VAR, None)
+    completed = subprocess.run(
+        [sys.executable, str(STARTER_SCRIPT)],
+        input=json.dumps({"source": "startup"}),
+        capture_output=True,
+        text=True,
+        check=False,
+        env=environment_by_key,
+    )
+    assert completed.returncode == 0
+    assert completed.stdout.strip() == ""

package/hooks/session/test_orchestrator_auto_starter.py

@@ -0,0 +1,99 @@
+"""Tests for the opt-in orchestrator SessionStart auto-starter."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from hooks_constants.orchestrator_auto_starter_constants import (
+    ORCHESTRATOR_AUTO_STARTER_ENABLED_ENV_VAR,
+    ORCHESTRATOR_SESSION_START_DIRECTIVE,
+    ORCHESTRATOR_STARTER_TIMEOUT_MILLISECONDS,
+)
+from session.orchestrator_auto_starter import (
+    orchestrator_auto_starter_enabled_in_environment,
+    run_orchestrator_auto_starter,
+)
+
+STARTER_SCRIPT = Path(__file__).resolve().parent / "orchestrator_auto_starter.py"
+DEFAULT_TIMEOUT = ORCHESTRATOR_STARTER_TIMEOUT_MILLISECONDS
+
+
+def test_default_environment_is_disabled(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv(ORCHESTRATOR_AUTO_STARTER_ENABLED_ENV_VAR, raising=False)
+    assert orchestrator_auto_starter_enabled_in_environment() is False
+
+
+def test_enabled_env_values(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(ORCHESTRATOR_AUTO_STARTER_ENABLED_ENV_VAR, "1")
+    assert orchestrator_auto_starter_enabled_in_environment() is True
+    monkeypatch.setenv(ORCHESTRATOR_AUTO_STARTER_ENABLED_ENV_VAR, "true")
+    assert orchestrator_auto_starter_enabled_in_environment() is True
+
+
+def test_disabled_path_emits_empty_without_context() -> None:
+    payload = run_orchestrator_auto_starter(
+        {"source": "startup"}, False, DEFAULT_TIMEOUT
+    )
+    assert payload == {}
+
+
+def test_enabled_startup_emits_orchestrator_directive() -> None:
+    payload = run_orchestrator_auto_starter(
+        {"source": "startup"}, True, DEFAULT_TIMEOUT
+    )
+    assert payload["additionalContext"] == ORCHESTRATOR_SESSION_START_DIRECTIVE
+
+
+@pytest.mark.parametrize("source", ("startup", "resume", "clear", "compact"))
+def test_enabled_known_sources_emit_directive(source: str) -> None:
+    payload = run_orchestrator_auto_starter({"source": source}, True, DEFAULT_TIMEOUT)
+    assert ORCHESTRATOR_SESSION_START_DIRECTIVE in payload.get("additionalContext", "")
+
+
+def test_enabled_unknown_source_emits_nothing() -> None:
+    payload = run_orchestrator_auto_starter({"source": "not-real"}, True, DEFAULT_TIMEOUT)
+    assert payload == {}
+
+
+def test_timeout_budget_zero_emits_nothing() -> None:
+    payload = run_orchestrator_auto_starter({"source": "startup"}, True, 0)
+    assert payload == {}
+
+
+def test_main_stdin_enabled_prints_json() -> None:
+    completed = subprocess.run(
+        [sys.executable, str(STARTER_SCRIPT)],
+        input=json.dumps({"source": "startup"}),
+        capture_output=True,
+        text=True,
+        check=False,
+        env={**os.environ, ORCHESTRATOR_AUTO_STARTER_ENABLED_ENV_VAR: "1"},
+    )
+    assert completed.returncode == 0
+    parsed = json.loads(completed.stdout)
+    assert parsed["additionalContext"] == ORCHESTRATOR_SESSION_START_DIRECTIVE
+
+
+def test_main_stdin_disabled_prints_nothing() -> None:
+    environment_by_key = os.environ.copy()
+    environment_by_key.pop(ORCHESTRATOR_AUTO_STARTER_ENABLED_ENV_VAR, None)
+    completed = subprocess.run(
+        [sys.executable, str(STARTER_SCRIPT)],
+        input=json.dumps({"source": "startup"}),
+        capture_output=True,
+        text=True,
+        check=False,
+        env=environment_by_key,
+    )
+    assert completed.returncode == 0
+    assert completed.stdout.strip() == ""

package/hooks/session/test_working_style_prompt.py

@@ -0,0 +1,47 @@
+"""Tests for working_style_prompt — SessionStart hook that injects working-style text."""
+
+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 working_style_prompt as starter
+
+from hooks_constants.working_style_prompt_constants import (
+    WORKING_STYLE_PROMPT,
+)
+
+
+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 TestWorkingStylePrompt:
+    def test_main_emits_additional_context(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "additionalContext" in emitted
+
+    def test_additional_context_matches_prompt_exactly(self) -> None:
+        emitted = json.loads(_run_main())
+        assert emitted["additionalContext"] == WORKING_STYLE_PROMPT
+
+    def test_emitted_prompt_carries_ledger_and_scope_lines(self) -> None:
+        emitted = json.loads(_run_main())
+        prompt_text = emitted["additionalContext"]
+        assert "scratch txt file you'll keep running as you go; ledger, if you will." in prompt_text
+        assert "Deliver what was asked, at the scope intended." in prompt_text
+        assert 'answer "what happened" or "what did you find,"' in prompt_text
+
+    def test_build_session_directive_returns_the_shared_constant(self) -> None:
+        assert starter.build_session_directive() == WORKING_STYLE_PROMPT

package/hooks/session/untracked_repo_detector.py

@@ -21,12 +21,11 @@ if _hooks_dir not in sys.path:
 
 from hooks_constants.dynamic_stderr_handler import DynamicStderrHandler  # noqa: E402
 from hooks_constants.project_paths_reader import (  # noqa: E402
+    find_git_root,
     load_registry,
     registry_contains_path,
     registry_file_path,
 )
-from hooks_constants.setup_project_paths_constants import GIT_DIRECTORY_SEGMENT_NAME  # noqa: E402
-
 
 _logger = logging.getLogger("untracked_repo_detector")
 if not _logger.handlers:
@@ -42,28 +41,6 @@ def current_working_directory() -> str:
     return os.getcwd()
 
 
-def find_git_root(start_path: str) -> str | None:
-    """Walk upward from start_path looking for a .git directory.
-
-    The walk is bounded by the user's home directory: once the candidate
-    reaches the home directory without finding ``.git``, the search stops.
-    This prevents a stray ``.git`` above the user's home (for example a
-    parent dotfiles repo) from being falsely reported as the session's repo.
-
-    Returns the absolute path of the repo root, or None if not found.
-    """
-    home_directory = Path.home().resolve()
-    candidate = Path(start_path).resolve()
-    while True:
-        if (candidate / GIT_DIRECTORY_SEGMENT_NAME).exists():
-            return str(candidate)
-        if candidate == home_directory:
-            return None
-        parent = candidate.parent
-        if parent == candidate:
-            return None
-        candidate = parent
-
 
 def _build_confirm_instruction(repo_root: str) -> str:
     config_file_path = str(registry_file_path())

package/hooks/session/working_style_prompt.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""SessionStart hook — inject working-style guidance into the session.
+
+At session start this hook emits an ``additionalContext`` block carrying a fixed
+working-style prompt: keep a running ledger, write in plain English, narrate
+before the first tool call, lead with the outcome, and stay at the asked scope.
+The hook writes nothing and runs no tools itself.
+"""
+
+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.working_style_prompt_constants import (  # noqa: E402
+    WORKING_STYLE_PROMPT,
+)
+
+
+def build_session_directive() -> str:
+    """Return the working-style prompt emitted at session start."""
+    return WORKING_STYLE_PROMPT
+
+
+def main() -> None:
+    """Emit the working-style prompt as SessionStart additionalContext."""
+    print(json.dumps({"additionalContext": build_session_directive()}))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/validators/_path_setup.py

@@ -0,0 +1,19 @@
+"""Add the hooks directory to sys.path for cross-package validator imports.
+
+Importing this module inserts the hooks directory (this file's parent's parent)
+at the front of sys.path, so a validator module can import the ``blocking`` and
+``hooks_constants`` packages while every import stays at module top.
+"""
+
+import sys
+from pathlib import Path
+
+hooks_directory_on_path = str(Path(__file__).resolve().parent.parent)
+"""The hooks directory this module places on ``sys.path``.
+
+An importer binds this name so the bootstrap import reads as used rather than as
+a stray side-effect import.
+"""
+
+if hooks_directory_on_path not in sys.path:
+    sys.path.insert(0, hooks_directory_on_path)

package/hooks/validators/run_all_validators.py

@@ -19,6 +19,7 @@ from datetime import datetime
 from pathlib import Path
 from typing import Callable, Dict, List, Optional, Tuple
 
+from ._path_setup import hooks_directory_on_path  # noqa: F401
 from .config.directory_exemption_constants import (
     ALL_DIRECTORY_EXEMPTION_SEGMENT_NAMES,
     ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS,
@@ -29,23 +30,17 @@ from .mypy_integration import check_mypy_available, run_mypy_check
 from .output_formatter import OutputFormatter, OutputMode, ValidatorResultDict
 from .python_style_checks import fix_file
 from .ruff_integration import check_ruff_available, run_ruff_check
-
+from blocking.code_rules_shared import is_ephemeral_path
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.multi_edit_reconstruction import (
+    apply_edits,
+    edits_for_tool,
+)
 
 VALIDATORS_DIR = Path(__file__).parent
 hooks_dir = VALIDATORS_DIR.parent
 package_name = VALIDATORS_DIR.name
 
-_hooks_directory_on_path = str(hooks_dir.resolve())
-if _hooks_directory_on_path not in sys.path:
-    sys.path.insert(0, _hooks_directory_on_path)
-
-from blocking.code_rules_shared import is_ephemeral_path  # noqa: E402
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
-from hooks_constants.multi_edit_reconstruction import (  # noqa: E402
-    apply_edits,
-    edits_for_tool,
-)
-
 
 def _windows_non_unc_working_directory_string(
     candidate_directory_strings: list[str | None],
@@ -824,7 +819,7 @@ def _is_absolute_path_under_system_temporary_directory(file_path: str) -> bool:
 
     ::
 
-        ok:   "C:/Users/.../Temp/pytest-of-x/test_foo0/a.py" -> True
+        ok:   "<windows-temp-root>/pytest-of-x/test_foo0/a.py"  -> True
         ok:   "/home/runner/work/_temp/pytest-basetemp/.../a.py" when RUNNER_TEMP
         flag: "packages/demo/test_helpers/worker.py"         -> False (relative)
         flag: "C:/repo/pkg/test_helpers/worker.py"           -> False (project)

package/installable-surfaces.manifest.json

@@ -0,0 +1,21 @@
+{
+  "directories": [
+    "bin",
+    "rules",
+    "docs",
+    "commands",
+    "agents",
+    "output-styles",
+    "skills",
+    "hooks",
+    "system-prompts",
+    "scripts",
+    "_shared",
+    "audit-rubrics"
+  ],
+  "root_files": [
+    "CLAUDE.md",
+    "codex-capability-map.json",
+    "installable-surfaces.manifest.json"
+  ]
+}

package/output-styles/CLAUDE.md

@@ -4,9 +4,7 @@ Output-style instruction files installed into `~/.claude/output-styles/` by `bin
 
 ## Files
 
-| File | Style | Effect |
-|---|---|---|
-| `caveman-agent.md` | Caveman Agent | Terse fragments, lead with answer, smallest artifact that solves the stated problem, question premise before building |
+No output-style instruction files ship in this directory. The active caveman behavior lives in `agents/caveman.md`.
 
 ## Format
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.9.0",
+    "version": "2.11.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -8,7 +8,7 @@
         "codex-compat": "bin/codex-compat.mjs"
     },
     "scripts": {
-        "test": "node --test \"bin/*.test.mjs\" \"skills/**/*.test.mjs\""
+        "test": "node --test \"bin/*.test.mjs\" \"skills/**/*.test.mjs\" \"scripts/profile-isolation-launchers/**/*.test.mjs\" \"tests/fresh-session/**/*.test.mjs\""
     },
     "files": [
         "bin/",
@@ -22,6 +22,8 @@
         "system-prompts/",
         "scripts/",
         "codex-capability-map.json",
+        "settings.json",
+        "installable-surfaces.manifest.json",
         "_shared/",
         "audit-rubrics/",
         "CLAUDE.md",

package/rules/CLAUDE.md

@@ -39,6 +39,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 | `nas-ssh-invocation.md` | Reach the NAS through the paramiko-backed `nas_ssh_key.py` runner, which signs in-process; every ssh-family client reads the key through file permissions, refuses it, and stalls an unattended run on a password prompt |
 | `no-cross-skill-duplicate-helpers.md` | Within one skill a duplicated helper is blocked; across two skill folders a small self-contained copy is a sanctioned isolation tradeoff that draws a non-blocking advisory naming the source skill |
 | `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
+| `opus5-communication-contract.md` | Visible concision, one-sentence first progress, important-change-only updates, outcome-first finals, thinking-disabled tool narration (`opus5-communication-contract-v1`) |
 | `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
 | `parallel-tools.md` | Make all independent tool calls in a single response |
 | `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 |

package/rules/durable-post-artifacts.md

@@ -19,7 +19,7 @@ Handle the two kinds of content differently:
 
 ## Volatile paths that must not appear in a post body
 
-- A job scratch directory (`.claude-editor/jobs/`)
+- A job scratch directory (`.claude-profile-a/jobs/`)
 - A worktree (`.claude/worktrees/`)
 - A system temp location (`AppData\Local\Temp`, `%TEMP%`, `$env:TEMP`, `/tmp/`)
 - The job scratch environment variable (`$CLAUDE_JOB_DIR`)
@@ -28,7 +28,7 @@ Both slash directions count.
 
 The worktree and job-scratch entries count as a path when either:
 
-- A `/` or `\` sits right before them — a drive-letter path (`C:\Users\me\.claude\worktrees\wt\f.py`), a home path (`~/.claude/worktrees/wt`), or a POSIX absolute path (`/home/me/.claude-editor/jobs/j/log.txt`).
+- A `/` or `\` sits right before them — a drive-letter path (`C:\Users\me\.claude\worktrees\wt\f.py`), a home path (`~/.claude/worktrees/wt`), or a POSIX absolute path (`/home/me/.claude-profile-a/jobs/j/log.txt`).
 - A path segment follows them — a relative path that names a child under that directory (`see .claude/worktrees/wt-1/notes.md`, a markdown link target, or `cd .claude/worktrees/wt-199`).
 
 With neither anchor the text names the directory rather than something inside it, and it posts — a quoted config constant, a backticked directory name, or a placeholder form such as `.claude/worktrees/<name>`. Un-backticked prose that puts a word immediately after the marker reads the same as a relative path and is blocked; the placeholder form is the documented escape.

package/rules/eli11-replies.md

@@ -7,7 +7,7 @@
 1. **Bold keyword first** — open every line and bullet with its load-bearing words in bold. Eyes land on the first words of a line, then fall down the left edge — the [F-pattern](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content-discovered/).
 2. **One idea per line** — a second idea in the same line is invisible to a skimmer.
 3. **Conclusion first** — the outcome goes in sentence one. Detail sits below it, or gets cut.
-4. **Half the words** — write it, halve it, halve it again. Cap a reply at about 120 words.
+4. **Half the words** — write it, halve it, halve it again. Stay brief by default; a requested full report may run long.
 
 **Measured gains** ([NN/g eyetracking](https://www.nngroup.com/articles/how-users-read-on-the-web/)): concise +58%, scannable layout +47%, both together +124%.
 
@@ -25,7 +25,12 @@
 - **Cut findings first** — when a reply runs long, drop findings and keep the action steps.
 - **Skim test** — reading only the bold words tells the whole story.
 
+## Progress and finals
+
+Mid-run and closing narration follow [`opus5-communication-contract.md`](opus5-communication-contract.md) (`opus5-communication-contract-v1`): first progress update is one sentence; later updates only for important discoveries or direction changes; the final starts with the outcome.
+
 ## Relationship to other rules
 
 - **[`plain-language`](plain-language.md)** owns word choice; this rule owns reply length and shape.
+- **[`opus5-communication-contract`](opus5-communication-contract.md)** owns progress updates, outcome-first finals, and thinking-disabled tool narration.
 - **`AskUserQuestion`** carries every question to the user, in the same short style.

package/rules/hedging-claims.md

@@ -2,8 +2,10 @@
 
 State a claim with the evidence that backs it, or name the claim unverified. A hedge word stands in for evidence you did not gather.
 
-`hedging_language_blocker` (Stop hook, hosted by `stop_dispatcher`) blocks a response carrying one — `likely`, `probably`, `presumably`, `perhaps`, `possibly`, `seemingly`, `apparently`, `arguably`, `supposedly`, `ostensibly`, `conceivably`, `plausibly`, `unlikely`, `probable`, and the phrases `might be`, `could be`, `seems to be`, `appears to be`, `in all likelihood`, `more likely than not`, `it's possible that`.
+`hedging_language_blocker` (Stop hook, hosted by `stop_dispatcher`) runs when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (see [`docs/references/prose-style-enforcement.md`](../docs/references/prose-style-enforcement.md)). It blocks a response that carries a bare hedge word — `likely`, `probably`, `presumably`, `perhaps`, `possibly`, `seemingly`, `apparently`, `arguably`, `supposedly`, `ostensibly`, `conceivably`, `plausibly`, `unlikely`, `probable`, and the phrases `might be`, `could be`, `seems to be`, `appears to be`, `in all likelihood`, `more likely than not`, `it's possible that` — **unless the same sentence** labels the claim with explicit uncertainty (`unverified`, `I don't know`, `I do not know`, `no source for this claim`, `without a source`).
 
-Deleting the hedge word and keeping the claim does not clear the block. Gather the source, run the probe, or ask the user through `AskUserQuestion` — then re-output the whole revised response.
+A label in another sentence does not clear a bare hedge. Deleting the hedge word and keeping the claim does not clear the block. Gather the source, run the probe, label the claim unverified in that sentence, or ask the user through `AskUserQuestion` — then re-output the whole revised response.
+
+When enforcement is off, bare hedges still emit privacy-safe advisory candidates for precision measurement (OP-07B).
 
 Sibling rules: [`research-mode.md`](research-mode.md) names what counts as a citation; [`verify-runtime-state.md`](verify-runtime-state.md) names the live probe a runtime verdict rests on.

package/rules/long-horizon-autonomy.md

@@ -30,9 +30,11 @@ On a long build, set a checkpoint cadence and hold to it. At each interval, chec
 
 Before you report progress, check each claim against a tool result from this session. State only what the evidence backs; name anything unverified as unverified. If tests fail, say so with the output; if a step was skipped, say that.
 
+Visible progress follows [`opus5-communication-contract.md`](opus5-communication-contract.md) (`opus5-communication-contract-v1`): the **first progress update is one sentence**; later updates mark only **important discoveries or a direction change**.
+
 ## Re-ground the final message
 
-Terse shorthand between tool calls is fine — that is you thinking. The final message is for a reader who saw none of it. After a long or unwatched run, write it as a fresh briefing: the outcome in one sentence, then the one or two things you need from the reader, each explained as if new. Drop the working vocabulary, arrow chains, and stacked-hyphen compounds; give each file, commit, or flag its own plain clause. When short and clear pull apart, choose clear.
+Terse shorthand between tool calls is fine — that is you thinking. The final message is for a reader who saw none of it. After a long or unwatched run, write it as a fresh briefing: the **outcome in one sentence first**, then the one or two things you need from the reader, each explained as if new. Drop the working vocabulary, arrow chains, and stacked-hyphen compounds; give each file, commit, or flag its own plain clause. When short and clear pull apart, choose clear.
 
 ## Keep going on context
 

package/rules/opus5-communication-contract.md

@@ -0,0 +1,45 @@
+# Opus 5 communication contract
+
+**Marker:** `opus5-communication-contract-v1`
+
+Positive contract for visible replies. Complements [`eli11-replies.md`](eli11-replies.md) (shape) and [`plain-language.md`](plain-language.md) (word choice).
+
+## Visible output
+
+1. **Concise by default.** A simple answer stays brief. When the user asks for a full audit or deep dump, the reply may run long enough to cover the substance.
+2. **First progress update is one sentence.** After the first tool batch on a multi-step task, one short status line is enough.
+3. **Later updates only for important change.** Further mid-run narration marks only important discoveries or a direction change — not every tool call.
+4. **Final starts with the outcome.** The closing message leads with what happened; artifacts scale to their substance.
+5. **Material corrections only.** Narrate a correction only when it changes code, a conclusion, or a decision.
+
+## Thinking-disabled tool narration
+
+When thinking is disabled in the harness:
+
+1. Speak one brief natural-language sentence before a tool call that needs user-visible context.
+2. When no fitting tool exists, say so in plain language.
+3. Never put internal-system XML in visible output.
+
+## Positive examples
+
+### Short answer
+
+User: "What is the default branch?"  
+Reply: "**Default branch** is `main`."
+
+### Requested full audit
+
+User: "Audit every hook registration and list gaps."  
+Reply: Outcome first, then a structured audit long enough to cover each gap — ELI11 caps still guide skim shape, not a hard character ceiling when depth was asked.
+
+### First progress update
+
+After the first tool batch: "**Checked** `hooks.json` registration paths."
+
+### Important discovery mid-run
+
+"**Blocker:** the package suite shadows `config` — running as two sessions."
+
+### Outcome-first final
+
+"**Shipped** draft PR #123. CI green on head `abc1234`. Merge still needs your OK."

package/rules/plain-language.md

@@ -2,8 +2,8 @@
 
 All prose a person reads (chat, `AskUserQuestion`, docs, PR/issue bodies, commits): everyday words, short active sentences, lead with the answer, define jargon on first use, and give only the detail the reader needs to act (progressive disclosure). Aim for first-pass readability by a non-specialist. Exact identifiers, file paths, and API names stay exact; code is out of scope.
 
-The `plain_language_blocker` PreToolUse hook (AskUserQuestion + `.md` Write/Edit/MultiEdit) blocks a heavy word and names the everyday swap; code fences, inline code, blockquotes, URLs, and file paths are skipped.
+The `plain_language_blocker` PreToolUse hook (AskUserQuestion + `.md` Write/Edit/MultiEdit) names an everyday swap for a heavy word when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off). That path is **allow with a systemMessage advisory** — it does not deny the write. AskUserQuestion lean-block structure stays always on and still denies chat detail. When the flag is off, heavy-word hits only emit privacy-safe advisory candidates (see [`docs/references/prose-style-enforcement.md`](../docs/references/prose-style-enforcement.md)). Code fences, inline code, blockquotes, URLs, and file paths are skipped.
 
-[`eli11-replies`](eli11-replies.md) governs reply length and shape; this rule governs word choice.
+[`eli11-replies`](eli11-replies.md) governs reply length and shape; [`opus5-communication-contract`](opus5-communication-contract.md) governs progress and finals; this rule governs word choice.
 
 A project can keep its own domain words out of the check with a `.claude/plain-language-allow.json` file: a JSON array of terms. An exact, case-insensitive, whole-word match on any term passes. The hook reads this file only from inside the project tree, up to the repository root, so each project's allowlist stays with its own code.

package/rules/research-mode.md

@@ -30,4 +30,4 @@ Creative thinking, brainstorming, and novel ideas don't require citation. You ca
 
 - [`explore-thoroughly.md`](explore-thoroughly.md) — grounds an implementation plan in the codebase, as this rule grounds a factual claim in a source.
 - [`verify-runtime-state.md`](verify-runtime-state.md) — a runtime verdict needs a live probe from this session, not a citation.
-- [`hedging-claims.md`](hedging-claims.md) — the Stop hook that catches an unverified claim wearing a hedge word.
+- [`hedging-claims.md`](hedging-claims.md) — the Stop hook that catches a bare hedge word; an explicit uncertainty label in the same sentence is the allowed alternative to a citation.

package/scripts/CLAUDE.md

@@ -16,6 +16,8 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 | `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
 | `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |
 | `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); applies `require_timeout_within_bounds` before the preflight, so an out-of-bounds `--timeout-seconds` prints a `timeout_out_of_bounds` outcome and exits 3 on every tier; protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
+| `active_capability_references.py` | Inventories committed skill, agent, and command names and scans package markdown for active slash or backticked capability references; fails ban-listed names outside inert historical/example fences |
+| `verify_installable_package.py` | Verifies the published package: runs real `npm pack`, checks every surface in `installable-surfaces.manifest.json` appears in the tarball, requires each `hooks.json` `.py` command to be git-tracked, and smoke-compiles those scripts (`node --check` on `bin/install.mjs`) |
 
 ## PowerShell scripts
 
@@ -24,6 +26,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 | `Audit-ShellPolicy.ps1` | Audits Bash tool calls in session transcripts against the `pwsh`-only shell policy |
 | `Migrate-ShellPolicy.ps1` | Applies automated fixes for common shell-policy violations found by the audit script |
 | `Install-SweepEmptyDirs.ps1` | Registers `sweep_empty_dirs.py` as a scheduled task on Windows |
+| `Sync-RepoMain.ps1` | Fast-forwards a main-tracking mirror (`-RepoPath`, required) to its remote main using `merge --ff-only`; refuses a different checkout or a diverged branch, logs each run to `-LogPath`, and exits non-zero so a scheduled-task history row surfaces the problem. `-StashDirty` stashes tracked changes right before the fast-forward under a dated `pre-sync stash` message and leaves the stash in the list |
 | `check.ps1` | Runs the full code-quality check suite |
 | `Show-Asset.ps1` | Opens files on screen, sizing each image window to the image's pixel dimensions (scaled to fit the screen); non-image files open in their default application |
 | `Get-SessionAccount.ps1` | Reports which Claude account the current session is actually logged into by comparing `~/.claude.json`'s CLI login against a `CLAUDE_USER_DATA_DIR` desktop profile's `lastKnownAccountUuid`, recovering the desktop account's email from profile storage when the two accounts differ |
@@ -33,7 +36,9 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 
 | Entry | Description |
 |---|---|
+| `ci/` | CI-only adapters; `windows-installer-lifecycle.ps1` runs the Node installer 16-check driver under isolated HOME/USERPROFILE/GIT_CONFIG_GLOBAL and writes bounded evidence |
 | `dev_env_scripts_constants/` | Named constants (`timing.py`, `grok_worker_constants.py`, …) for scripts in this directory, including worker-advisor placeholder launcher/model/effort, four verdict signals, correction cap, and advisor timeout |
+| `profile-isolation-launchers/` | Profile-launcher contract plus MCP activation, Windows shortcut source semantics, and version preflight: profiles manifest, shared-path allowlist, profile resolver, `CLAUDE_CONFIG_DIR` authority, lean/full MCP bundle materialization into profile `mcp.json`, pure CLI/Desktop version-compatibility classifier consumed by launcher preflight, read-only shortcut inventory and preview reconcile under `windows/`. Live launcher execution, provenance pin, live shortcut mutation, and L1 deploy stay residual |
 | `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
 | `tests/` | pytest suite for the Python scripts and Pester (`*.Tests.ps1`) suite for the PowerShell scripts in this directory |
 
@@ -45,6 +50,12 @@ Python scripts (pytest):
 python -m pytest packages/claude-dev-env/scripts/tests/
 ```
 
+Profile-isolation launcher contract (node:test):
+
+```bash
+node --test packages/claude-dev-env/scripts/profile-isolation-launchers/**/*.test.mjs
+```
+
 PowerShell scripts (Pester 5+, `*.Tests.ps1`):
 
 ```powershell