claude-dev-env 2.9.0 → 2.11.0

package/skills/split-pr/scripts/test_split_pr_paginate.py

@@ -0,0 +1,65 @@
+"""Paginated file intake flattens --slurp pages without losing paths."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from split_pr_paginate import fetch_all_pr_changed_files, parse_paginated_files_payload
+
+
+def test_fetch_all_pr_changed_files_builds_paginated_gh_api_command(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_captured: list[list[str]] = []
+
+    class _Completed:
+        returncode = 0
+        stdout = (
+            '[[{"filename": "x.py", "additions": 1, "deletions": 0, "sha": "s"}]]'
+        )
+        stderr = ""
+
+    def _fake_run(all_command: list[str], **_kwargs: object) -> _Completed:
+        all_captured.append(list(all_command))
+        return _Completed()
+
+    monkeypatch.setattr("split_pr_paginate.subprocess.run", _fake_run)
+    all_files = fetch_all_pr_changed_files("jl-cmd", "claude-dev-env", 1)
+    assert all_files[0]["path"] == "x.py"
+    assert "--paginate" in all_captured[0]
+    assert "--slurp" in all_captured[0]
+
+
+def test_slurp_pages_are_flattened_in_order() -> None:
+    raw = json.dumps(
+        [
+            [{"filename": "a.py", "additions": 1, "deletions": 0, "sha": "1"}],
+            [{"filename": "b.py", "additions": 2, "deletions": 1, "sha": "2"}],
+        ]
+    )
+    all_files = parse_paginated_files_payload(raw)
+    assert [each["path"] for each in all_files] == ["a.py", "b.py"]
+    assert all_files[1]["additions"] == 2
+
+
+def test_single_page_array_still_parses() -> None:
+    raw = json.dumps([{"filename": "only.py", "additions": 3, "deletions": 0}])
+    all_files = parse_paginated_files_payload(raw)
+    assert len(all_files) == 1
+    assert all_files[0]["path"] == "only.py"
+
+
+def test_rest_filename_preferred_over_internal_path_key() -> None:
+    raw = json.dumps(
+        [{"filename": "from-api.py", "path": "stale.py", "additions": 1, "deletions": 0}]
+    )
+    all_files = parse_paginated_files_payload(raw)
+    assert all_files[0]["path"] == "from-api.py"

package/skills/split-pr/scripts/test_split_pr_script_types.py

@@ -0,0 +1,73 @@
+"""Split-plan schema validation rejects unassigned paths."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from split_pr_script_types import build_split_plan, validate_split_plan
+
+
+def test_build_and_validate_full_assignment() -> None:
+    plan = build_split_plan(
+        source_commit="abc123",
+        all_changed_paths=["a.py", "b.md"],
+        all_slices=[
+            {
+                "id": "01-config",
+                "title": "feat: feat: config",
+                "layer": "config",
+                "all_paths": ["a.py"],
+            },
+            {
+                "id": "02-docs",
+                "title": "docs only",
+                "layer": "docs",
+                "all_paths": ["b.md"],
+            },
+        ],
+    )
+    validate_split_plan(plan)
+    assert plan["schema_version"] == 1
+    assert plan["all_slices"][0]["title"] == "feat: config"
+    assert plan["all_slices"][1]["title"] == "chore: docs only"
+
+
+def test_validate_rejects_unassigned_path() -> None:
+    plan = build_split_plan(
+        source_commit="abc123",
+        all_changed_paths=["a.py", "orphan.py"],
+        all_slices=[
+            {
+                "id": "01",
+                "title": "feat: only a",
+                "layer": "backend",
+                "all_paths": ["a.py"],
+            }
+        ],
+    )
+    with pytest.raises(ValueError, match="missing"):
+        validate_split_plan(plan)
+
+
+def test_validate_rejects_empty_slice_id() -> None:
+    plan = build_split_plan(
+        source_commit="abc123",
+        all_changed_paths=["a.py"],
+        all_slices=[
+            {
+                "id": "  ",
+                "title": "feat: bare",
+                "layer": "backend",
+                "all_paths": ["a.py"],
+            }
+        ],
+    )
+    with pytest.raises(ValueError, match="slice id"):
+        validate_split_plan(plan)

package/skills/split-pr/scripts/test_split_pr_title.py

@@ -0,0 +1,28 @@
+"""Title normalization carries exactly one conventional prefix."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from split_pr_title import normalize_split_title
+
+
+def test_single_prefix_unchanged() -> None:
+    assert normalize_split_title("feat: add gate") == "feat: add gate"
+
+
+def test_stacked_prefixes_collapse_to_one() -> None:
+    assert normalize_split_title("feat: feat: add gate") == "feat: add gate"
+
+
+def test_bare_title_gets_default_chore_prefix() -> None:
+    assert normalize_split_title("add gate") == "chore: add gate"
+
+
+def test_scoped_prefix_normalized() -> None:
+    assert normalize_split_title("fix(hooks): repair gate") == "fix: repair gate"

package/skills/split-pr/scripts/test_verify_dependency_graph.py

@@ -0,0 +1,46 @@
+"""Dependency graph verifier CLI and rebuild checks."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from split_pr_dependency_graph import build_dependency_graph
+from verify_dependency_graph import main, verify_dependency_graph_document
+
+
+def test_verify_accepts_rebuilt_graph() -> None:
+    all_slices = [
+        {"id": "01-config", "layer": "config"},
+        {"id": "02-docs", "layer": "docs"},
+    ]
+    graph = build_dependency_graph(all_slices)
+    graph["all_slices"] = all_slices
+    verify_dependency_graph_document(graph)
+
+
+def test_verify_rejects_order_mismatch() -> None:
+    all_slices = [
+        {"id": "01-config", "layer": "config"},
+        {"id": "02-docs", "layer": "docs"},
+    ]
+    graph = build_dependency_graph(all_slices)
+    graph["all_slices"] = all_slices
+    graph["topological_order"] = ["02-docs", "01-config"]
+    with pytest.raises(ValueError, match="mismatch"):
+        verify_dependency_graph_document(graph)
+
+
+def test_cli_ok(tmp_path: Path) -> None:
+    all_slices = [{"id": "a", "layer": "backend"}]
+    graph = build_dependency_graph(all_slices)
+    path = tmp_path / "g.json"
+    path.write_text(json.dumps(graph), encoding="utf-8")
+    assert main(["--graph-json", str(path)]) == 0

package/skills/split-pr/scripts/test_verify_plan.py

@@ -0,0 +1,56 @@
+"""verify_plan accepts full coverage and rejects gaps."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from verify_plan import main, verify_split_plan_coverage
+
+
+def _full_plan() -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "source_commit": "abc",
+        "all_changed_paths": ["src/a.py", "docs/b.md"],
+        "all_slices": [
+            {
+                "id": "01-backend",
+                "title": "feat: a",
+                "layer": "backend",
+                "all_paths": ["src/a.py"],
+            },
+            {
+                "id": "02-docs",
+                "title": "docs: b",
+                "layer": "docs",
+                "all_paths": ["docs/b.md"],
+            },
+        ],
+    }
+
+
+def test_verify_accepts_full_unique_coverage() -> None:
+    verify_split_plan_coverage(_full_plan())
+
+
+def test_verify_rejects_missing_path() -> None:
+    plan = _full_plan()
+    all_slices = plan["all_slices"]
+    assert isinstance(all_slices, list)
+    plan["all_slices"] = [all_slices[0]]
+    with pytest.raises(ValueError, match="missing"):
+        verify_split_plan_coverage(plan)
+
+
+def test_cli_ok_on_temp_plan(tmp_path: Path) -> None:
+    plan_path = tmp_path / "plan.json"
+    plan_path.write_text(json.dumps(_full_plan()), encoding="utf-8")
+    assert main(["--plan-json", str(plan_path)]) == 0

package/skills/split-pr/scripts/test_verify_plan_contract.py

@@ -0,0 +1,50 @@
+"""Contract: source_commit and title normalization are required."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from verify_plan import verify_split_plan_coverage
+
+
+def test_missing_source_commit_fails() -> None:
+    plan = {
+        "schema_version": 1,
+        "source_commit": "",
+        "all_changed_paths": ["a.py"],
+        "all_slices": [
+            {
+                "id": "01",
+                "title": "feat: a",
+                "layer": "backend",
+                "all_paths": ["a.py"],
+            }
+        ],
+    }
+    with pytest.raises(ValueError, match="source_commit"):
+        verify_split_plan_coverage(plan)
+
+
+def test_stacked_title_fails_after_build_would_have_normalized() -> None:
+    plan = {
+        "schema_version": 1,
+        "source_commit": "abc",
+        "all_changed_paths": ["a.py"],
+        "all_slices": [
+            {
+                "id": "01",
+                "title": "feat: feat: a",
+                "layer": "backend",
+                "all_paths": ["a.py"],
+            }
+        ],
+    }
+    with pytest.raises(ValueError, match="title"):
+        verify_split_plan_coverage(plan)

package/skills/split-pr/scripts/test_verify_plan_path_normalization.py

@@ -0,0 +1,45 @@
+"""Path normalization fails closed on unsafe paths."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from verify_plan import normalize_repo_path, verify_split_plan_coverage
+
+
+def test_normalize_strips_dot_slash() -> None:
+    assert normalize_repo_path("./src/a.py") == "src/a.py"
+    assert normalize_repo_path("src\\a.py") == "src/a.py"
+
+
+def test_normalize_rejects_parent_and_absolute() -> None:
+    with pytest.raises(ValueError):
+        normalize_repo_path("../secret")
+    with pytest.raises(ValueError):
+        normalize_repo_path("/etc/passwd")
+    with pytest.raises(ValueError):
+        normalize_repo_path("C:/Windows/system32")
+
+
+def test_verify_normalizes_mixed_separators() -> None:
+    plan = {
+        "schema_version": 1,
+        "source_commit": "abc",
+        "all_changed_paths": ["src\\a.py"],
+        "all_slices": [
+            {
+                "id": "01",
+                "title": "feat: a",
+                "layer": "backend",
+                "all_paths": ["./src/a.py"],
+            }
+        ],
+    }
+    verify_split_plan_coverage(plan)

package/skills/split-pr/scripts/verify_dependency_graph.py

@@ -0,0 +1,111 @@
+"""CLI and checks for a split-plan dependency graph document.
+
+::
+
+    python verify_dependency_graph.py --graph-json graph.json
+    # exit 0 when shape is valid and order matches a rebuild when all_slices set
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+if str(Path(__file__).resolve().parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from config.dependency_constants import (
+    EDGE_KEY_FROM,
+    EDGE_KEY_TO,
+    GRAPH_KEY_EDGES,
+    GRAPH_KEY_NODES,
+    GRAPH_KEY_ORDER,
+)
+from config.plan_constants import (
+    EXIT_CODE_SUCCESS,
+    PLAN_KEY_ALL_SLICES,
+    UTF8_ENCODING,
+)
+from config.split_pr_constants import EXIT_CODE_FAILURE
+from split_pr_dependency_graph import build_dependency_graph
+from split_pr_script_types import JsonObject
+
+
+def verify_dependency_graph_document(all_graph: JsonObject) -> None:
+    """Validate graph shape; when ``all_slices`` is set, match rebuild order.
+
+    Args:
+        all_graph: Graph document with nodes, edges, topological_order, and
+            optional ``all_slices``. Always checks: non-empty unique nodes,
+            order lists each node once, edges reference known nodes. When
+            ``all_slices`` is a non-empty list, rebuilds and requires
+            topological_order to match.
+
+    Raises:
+        ValueError: When shape checks fail or topological_order mismatches
+            a rebuild from ``all_slices``.
+    """
+    all_nodes = all_graph.get(GRAPH_KEY_NODES)
+    all_edges = all_graph.get(GRAPH_KEY_EDGES)
+    all_order = all_graph.get(GRAPH_KEY_ORDER)
+    if not isinstance(all_nodes, list) or not all_nodes:
+        raise ValueError("nodes must be a non-empty list")
+    if not isinstance(all_edges, list):
+        raise ValueError("edges must be a list")
+    if not isinstance(all_order, list):
+        raise ValueError("topological_order must be a list")
+    all_node_ids = [str(each) for each in all_nodes]
+    if len(all_node_ids) != len(set(all_node_ids)):
+        raise ValueError("nodes contains duplicates")
+    all_order_ids = [str(each) for each in all_order]
+    if sorted(all_order_ids) != sorted(all_node_ids):
+        raise ValueError("topological_order must list each node exactly once")
+    all_node_set = set(all_node_ids)
+    for each_edge in all_edges:
+        if not isinstance(each_edge, dict):
+            raise ValueError("each edge must be an object")
+        edge_from = str(each_edge.get(EDGE_KEY_FROM, ""))
+        edge_to = str(each_edge.get(EDGE_KEY_TO, ""))
+        if edge_from not in all_node_set or edge_to not in all_node_set:
+            raise ValueError(f"edge uses unknown node: {each_edge!r}")
+    all_slices = all_graph.get(PLAN_KEY_ALL_SLICES)
+    if isinstance(all_slices, list) and all_slices:
+        rebuilt = build_dependency_graph(all_slices)
+        if rebuilt[GRAPH_KEY_ORDER] != all_order_ids:
+            raise ValueError(
+                f"topological_order mismatch expected {rebuilt[GRAPH_KEY_ORDER]!r} "
+                f"got {all_order_ids!r}"
+            )
+
+
+def main(all_argv: list[str]) -> int:
+    """CLI entry for graph verification.
+
+    Args:
+        all_argv: Args without program name.
+
+    Returns:
+        0 on success, 1 on failure.
+
+    Raises:
+        Does not raise; writes a JSON error payload on failure.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--graph-json", type=Path, required=True)
+    arguments = parser.parse_args(all_argv)
+    try:
+        payload = json.loads(arguments.graph_json.read_text(encoding=UTF8_ENCODING))
+        if not isinstance(payload, dict):
+            raise ValueError("graph root must be an object")
+        verify_dependency_graph_document(payload)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(json.dumps({"ok": False, "error": str(error)}))
+        return EXIT_CODE_FAILURE
+    print(json.dumps({"ok": True}))
+    return EXIT_CODE_SUCCESS
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/split-pr/scripts/verify_plan.py

@@ -0,0 +1,139 @@
+"""Verify complete unique path coverage for a split-plan document.
+
+::
+
+    python verify_plan.py --plan-json plan.json
+    # exit 0 when every changed path is assigned once
+
+Fails closed on unassigned paths, duplicate assignments, empty source
+commit, and non-normalized titles.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+if str(Path(__file__).resolve().parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from config.plan_constants import (
+    EXIT_CODE_SUCCESS,
+    PATH_SEPARATOR,
+    PLAN_KEY_ALL_CHANGED_PATHS,
+    PLAN_KEY_ALL_SLICES,
+    PLAN_KEY_SOURCE_COMMIT,
+    SLICE_KEY_ALL_PATHS,
+    UTF8_ENCODING,
+    VERIFY_PAYLOAD_KEY_OK,
+)
+from config.split_pr_constants import EXIT_CODE_FAILURE, PAYLOAD_KEY_ERROR
+from split_pr_script_types import JsonObject, validate_split_plan
+
+
+def _is_drive_path(path_text: str) -> bool:
+    return len(path_text) >= 2 and path_text[1] == ":"
+
+
+def normalize_repo_path(raw_path: str) -> str:
+    """Normalize a changed-path string for coverage comparison.
+
+    Args:
+        raw_path: Path as stored in the plan or intake list.
+
+    Returns:
+        Forward-slash path without a leading ``./``.
+
+    Raises:
+        ValueError: When the path is empty, absolute, or has ``..`` segments.
+    """
+    text = raw_path.strip().replace("\\", PATH_SEPARATOR)
+    if not text or text.startswith(PATH_SEPARATOR) or _is_drive_path(text):
+        raise ValueError(f"unsafe or empty path: {raw_path!r}")
+    all_parts = [
+        each for each in text.split(PATH_SEPARATOR) if each not in ("", ".")
+    ]
+    if any(each == ".." for each in all_parts):
+        raise ValueError(f"ambiguous parent path segment: {raw_path!r}")
+    if not all_parts:
+        raise ValueError(f"empty path after normalization: {raw_path!r}")
+    return PATH_SEPARATOR.join(all_parts)
+
+
+def _normalize_plan_paths(all_plan: JsonObject) -> JsonObject:
+    all_changed = all_plan.get(PLAN_KEY_ALL_CHANGED_PATHS, [])
+    if not isinstance(all_changed, list):
+        raise ValueError("all_changed_paths must be a list")
+    all_slices = all_plan.get(PLAN_KEY_ALL_SLICES, [])
+    if not isinstance(all_slices, list):
+        raise ValueError("all_slices must be a list")
+    all_normalized_changed = [normalize_repo_path(str(each)) for each in all_changed]
+    all_normalized_slices: list[JsonObject] = []
+    for each_slice in all_slices:
+        if not isinstance(each_slice, dict):
+            raise ValueError("slice must be an object")
+        all_paths = each_slice.get(SLICE_KEY_ALL_PATHS, [])
+        if not isinstance(all_paths, list):
+            raise ValueError("slice all_paths must be a list")
+        all_normalized_slices.append(
+            {
+                **each_slice,
+                SLICE_KEY_ALL_PATHS: [
+                    normalize_repo_path(str(each_path)) for each_path in all_paths
+                ],
+            }
+        )
+    return {
+        **all_plan,
+        PLAN_KEY_ALL_CHANGED_PATHS: all_normalized_changed,
+        PLAN_KEY_ALL_SLICES: all_normalized_slices,
+    }
+
+
+def verify_split_plan_coverage(all_plan: JsonObject) -> None:
+    """Normalize paths then run the schema assignment validator.
+
+    Args:
+        all_plan: Split-plan document.
+
+    Raises:
+        ValueError: When coverage or safety checks fail.
+    """
+    source_commit = all_plan.get(PLAN_KEY_SOURCE_COMMIT)
+    if not isinstance(source_commit, str) or not source_commit.strip():
+        raise ValueError("source_commit is required")
+    normalized = _normalize_plan_paths(all_plan)
+    validate_split_plan(normalized)
+
+
+def main(all_argv: list[str]) -> int:
+    """CLI: verify a plan JSON file.
+
+    Args:
+        all_argv: Args without program name.
+
+    Returns:
+        Exit code 0 on success, 1 on failure.
+
+    Raises:
+        Does not raise; converts failures into a JSON error payload.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--plan-json", type=Path, required=True)
+    arguments = parser.parse_args(all_argv)
+    try:
+        payload = json.loads(arguments.plan_json.read_text(encoding=UTF8_ENCODING))
+        if not isinstance(payload, dict):
+            raise ValueError("plan root must be an object")
+        verify_split_plan_coverage(payload)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(json.dumps({VERIFY_PAYLOAD_KEY_OK: False, PAYLOAD_KEY_ERROR: str(error)}))
+        return EXIT_CODE_FAILURE
+    print(json.dumps({VERIFY_PAYLOAD_KEY_OK: True}))
+    return EXIT_CODE_SUCCESS
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/team-advisor/SKILL.md

@@ -16,25 +16,28 @@ One warm advisor at the strongest tier this session can reach. This session is t
 | Doc | Holds |
 |---|---|
 | [`docs/references/advisor-tool.md`](../../docs/references/advisor-tool.md) | **Consult cadence and weight** — when to call, hard rule before first write, how to treat advice. Read this for every consult. |
-| [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle** — host detect, model floor, warm-up or CLI bind, charter, drift re-bind, CLI fallback, executor paste blocks. |
+| [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle** — host detect, model floor, warm-up, CLI fallback; its read map routes each moment to a `reference/` detail file. |
 | [`agents/session-advisor.md`](../../agents/session-advisor.md) | **Reply contract** — ENDORSE / CORRECTION / PLAN / STOP; SendMessage only. |
+| [`reference/advisor-docs-review.md`](reference/advisor-docs-review.md) | Anthropic advisor-tool source facts: measured effects, Sonnet steering, cost levers, failure modes. Background — read it when tuning the bind, not on every consult. |
 
 ## Bind
 
 1. Detect the host profile first (protocol **Host profiles**), then walk the model floor.
-2. Floor: this session's own tier on Claude; Opus floor with Fable first on a third-party host.
+2. Floor: the stronger of Opus and this session's own tier on Claude; Opus floor with Fable first on a third-party host.
 3. Name: `team-advisor-agent` on Claude (Agent spawn of `session-advisor`); one CLI `session_id` on a third-party host via the protocol Claude-chain.
 4. A Fable-tier spawn or re-spawn carries the exact token `FABLE-SPAWN-AUTHORIZED` in its prompt (protocol warm-up; `fable_spawn_gate` requires it).
 5. Skip the multi-consumer "who you are" opener — sole consumer.
 6. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound Claude advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
-Full walk, charter, consult message shape, and drift re-bind live in the protocol.
+Full walk, charter, consult packet, Sol routing, and drift re-bind live in the protocol read map and its authoritative `reference/` leaves.
 
 ## Consult
 
 Follow **When to call**, **Hard rule**, and **How to treat advice** in `advisor-tool.md`.
 
-Each brief: delta since last consult, live decision or blocker, paths or excerpts needed. Protocol owns the full consult format.
+Build every first brief with [`_shared/advisor/reference/consult-format.md`](../../_shared/advisor/reference/consult-format.md). Later briefs carry only the delta and changed evidence.
+
+Aim for two consults on a normal task: one after orientation and one after writes and validation. Reserve a third for advisory recovery or reconciliation guidance, and add a consult when a material fork produces new evidence. This is an advisory target owned by the task, not a cap or gate.
 
 ## Constraints