claude-dev-env 2.8.0 → 2.10.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

@@ -0,0 +1,15 @@
+# output-styles
+
+Output-style instruction files installed into `~/.claude/output-styles/` by `bin/install.mjs`. Each file instructs an agent or session to respond in a specific voice or format.
+
+## Files
+
+No output-style instruction files ship in this directory. The active caveman behavior lives in `agents/caveman.md`.
+
+## Format
+
+Each file uses YAML frontmatter (`name`, `description`, optional `keep-coding-instructions`) followed by Markdown instructions. The `keep-coding-instructions: true` flag tells Claude Code to keep the session's coding rules even when this style is active.
+
+## Adding a style
+
+Create a `.md` file with frontmatter and behavioral instructions, then run `bin/install.mjs` to copy it to `~/.claude/output-styles/`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.8.0",
+    "version": "2.10.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/",
@@ -16,11 +16,14 @@
         "docs/",
         "commands/",
         "agents/",
+        "output-styles/",
         "skills/",
         "hooks/",
         "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/code-standards.md

@@ -1,13 +1,39 @@
 # Code Standards
 
-> **MANDATORY REFERENCE:** CODE_RULES.md - Load for ALL code generation.
-> This is the single source of truth for code standards. Non-negotiable.
+> **Canonical policy:** repository-root [`AGENTS.md`](../../../AGENTS.md) — the human and AI review contract for code quality.
+> **Compact projection:** [`CODE_RULES.md`](../docs/CODE_RULES.md) — validated summary for generation load.
+> **Production enforcement:** `hooks/blocking/code_rules_enforcer.py` — hand-maintained Write/Edit gates; each mechanical rule carries a synchronization test.
 
-`CODE_RULES.md` (`~/.claude/docs/CODE_RULES.md`) is the compact reference for every standard: self-documenting names, centralized configuration, constant reuse, no magic literals, full words, complete type hints, required-vs-optional parameters, construction logic in the model, temporary-code `TODO:` markers, behavior-first component names, and TDD.
+## Policy surface map
 
-Two standards live there in full and nowhere else:
+| Layer | Path | Role |
+|---|---|---|
+| Canonical | `AGENTS.md` (repo root) | Full review criteria for PR agents; BugBot sync source |
+| Projection | `docs/CODE_RULES.md` | Compact always-load reference; must not diverge from AGENTS |
+| Enforcer | `hooks/blocking/code_rules_enforcer.py` | Hand-maintained blockers; not generated from the docs |
+| Session rules | `rules/*.md` | Runtime session policy (questions, tasks, shell) |
 
-- **TDD** — CODE_RULES §8 is canonical: red, green, refactor, with no production code before a failing test.
-- **Right-sized engineering** — CODE_RULES §7 is canonical: functions over classes, concrete over abstract, an abstraction added at the commit that introduces its second concrete implementation.
+Load `AGENTS.md` when reviewing a PR or resolving a policy conflict. Load `CODE_RULES.md` when generating code under the compact checklist. Prefer linking these refs over restating rules.
 
-BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers and formulates the behavior a feature needs, then each formulated behavior is built through the CODE_RULES §8 red-green-refactor cycle.
+Two standards live in the canonical policy in full (and in the projection by name):
+
+- **TDD** — CODE_RULES §8 / AGENTS Tests: red, green, refactor; no production code before a failing test.
+- **Right-sized engineering** — CODE_RULES §7 / AGENTS Design: functions over classes; concrete over abstract; add an abstraction at the commit that introduces its second concrete implementation.
+
+BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers and formulates the behavior a feature needs, then each formulated behavior is built through the TDD cycle.
+
+## Session policies (ref docs, not restated here)
+
+| Concern | Rule file |
+|---|---|
+| Question routing | [`ask-user-question-required.md`](ask-user-question-required.md) |
+| Task tracking / worker completion | [`workers-done-before-complete.md`](workers-done-before-complete.md) |
+| Multi-step task list | skill `task-build` (see agents catalog) |
+
+## Synchronization
+
+Mechanical enforcer coverage is checked by `tests/test_agents_policy_parity.py` and the existing `hooks/blocking/test_code_rules_enforcer*.py` suite. BugBot projection drift is checked with:
+
+```
+python .github/scripts/sync_ai_rules.py --check
+```

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%.
 
@@ -20,12 +20,17 @@
 
 ## Rules
 
-- **One command per block** — a command the user runs goes in its own `bash`-tagged fenced block, so the Run button appears. That tag gives the user a Run button; [`shell-invocation-policy`](shell-invocation-policy.md) stays in charge of the agent's own Bash-tool calls, which run pwsh-only.
+- **One command per block** — a command the user runs goes in its own `bash`-tagged fenced block, so the Run button appears. That tag gives the user a Run button; [`shell-invocation-policy`](shell-invocation.md) stays in charge of the agent's own Bash-tool calls, which run pwsh-only.
 - **One line per status** — each background-work update gets a single line.
 - **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."