@ictechgy/context-guard 0.4.1 → 0.4.4

package/plugins/context-guard/bin/context-guard-setup

@@ -165,6 +165,21 @@ ADAPTER_RULE_BLOCK_END = "<!-- contextguard:end -->"
 CODEX_SKILL_REL = ".agents/skills/context-guard/SKILL.md"
 CODEX_SKILL_MARKER_BEGIN = "<!-- contextguard:codex-skill:begin -->"
 CODEX_SKILL_MARKER_END = "<!-- contextguard:codex-skill:end -->"
+BRIEF_MODE_LEVELS = ("lite", "standard", "ultra")
+BRIEF_MODE_OFF = "off"
+BRIEF_MODE_CHOICES = (*BRIEF_MODE_LEVELS, BRIEF_MODE_OFF)
+BRIEF_MODE_BLOCK_END = "<!-- END context-guard:brief-mode -->"
+BRIEF_MODE_BEGIN_RE = re.compile(
+    r"<!-- BEGIN context-guard:brief-mode level=(?P<level>[a-z]+) version=1 -->"
+)
+BRIEF_MODE_BLOCK_RE = re.compile(
+    r"(?:\n{0,2})?"
+    r"<!-- BEGIN context-guard:brief-mode level=(?P<level>[a-z]+) version=1 -->"
+    r".*?"
+    r"<!-- END context-guard:brief-mode -->"
+    r"(?:\n{0,2})?",
+    re.DOTALL,
+)
 
 
 class CapabilityClass:
@@ -385,6 +400,265 @@ def render_codex_skill() -> str:
     ])
 
 
+def _brief_mode_source_candidates(level: str) -> list[Path]:
+    """Return deterministic source candidates for packaged/repo brief snippets."""
+    filename = f"brief-mode.{level}.md"
+    here = Path(__file__).resolve()
+    return [
+        here.parent / "brief" / filename,
+        here.parent.parent / "brief" / filename,
+        here.parent.parent / "plugins" / "context-guard" / "brief" / filename,
+        here.parent / "plugins" / "context-guard" / "brief" / filename,
+    ]
+
+
+def _extract_brief_mode_block(level: str, text: str) -> str | None:
+    """Extract the single marker-delimited block for ``level`` from a snippet file."""
+    matches = list(BRIEF_MODE_BLOCK_RE.finditer(text))
+    level_matches = [match for match in matches if match.group("level") == level]
+    if len(level_matches) != 1:
+        return None
+    block = level_matches[0].group(0).strip()
+    if BRIEF_MODE_BLOCK_END not in block or not BRIEF_MODE_BEGIN_RE.search(block):
+        return None
+    return block
+
+
+def render_fallback_brief_mode_block(level: str) -> str:
+    """Render a resilient advisory brief-mode block when packaged files are absent."""
+    descriptions = {
+        "lite": "Keep replies focused. Trim pleasantries and repeated context, but keep helpful explanations.",
+        "standard": "Lead with the result, prefer bullets, and keep only one short rationale when it matters.",
+        "ultra": "Use terse result-first bullets or tables with no preamble or self-narration.",
+    }
+    if level not in BRIEF_MODE_LEVELS:
+        raise ValueError(f"unknown brief mode level: {level}")
+    return "\n".join([
+        f"<!-- BEGIN context-guard:brief-mode level={level} version=1 -->",
+        f"## Response style: brief mode ({level}) — advisory",
+        "",
+        descriptions[level],
+        "This is best-effort guidance, not a hard rule.",
+        "",
+        "Always preserve this evidence, even when trimming wording:",
+        "",
+        "- Exact file paths, with line numbers where useful (e.g. `src/app.py:42`).",
+        "- The exact commands you ran.",
+        "- Relevant command output, error messages, stack traces, and exit codes — never hide a failure.",
+        "- Code in fenced blocks whenever code is needed for correctness.",
+        "- Verification status: what you ran and whether it passed or failed.",
+        "- The list of changed files.",
+        "- Known gaps, TODOs, and assumptions.",
+        "- Caveats and anything I should double-check.",
+        "",
+        "This guidance does not promise reduced tokens or cost; measure real results before claiming savings.",
+        BRIEF_MODE_BLOCK_END,
+    ])
+
+
+def render_brief_mode_block(level: str) -> str:
+    """Render the marker-delimited advisory snippet for a brief-mode level."""
+    if level not in BRIEF_MODE_LEVELS:
+        raise ValueError(f"unknown brief mode level: {level}")
+    for candidate in _brief_mode_source_candidates(level):
+        try:
+            text = candidate.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        block = _extract_brief_mode_block(level, text)
+        if block:
+            return block
+    return render_fallback_brief_mode_block(level)
+
+
+def _brief_mode_levels_in_text(text: str) -> list[str]:
+    return [match.group("level") for match in BRIEF_MODE_BLOCK_RE.finditer(text)]
+
+
+def _remove_brief_mode_blocks(text: str) -> tuple[str, list[str]]:
+    """Remove all ContextGuard-managed brief-mode blocks while preserving user text."""
+    levels = _brief_mode_levels_in_text(text)
+    stripped = BRIEF_MODE_BLOCK_RE.sub("\n\n", text)
+    stripped = re.sub(r"\n{3,}", "\n\n", stripped).strip("\n")
+    return ((stripped + "\n") if stripped else "", levels)
+
+
+def _append_managed_block(existing: str, block: str) -> str:
+    if existing.strip():
+        return existing.rstrip("\n") + "\n\n" + block + "\n"
+    return block + "\n"
+
+
+def compose_rule_file_text(
+    existing: str | None,
+    *,
+    with_init: bool,
+    brief_mode: str | None,
+) -> tuple[str, dict[str, Any]]:
+    """Compose final repo rule text for combined init and brief-mode mutations."""
+    text = existing or ""
+    original_text = text
+    existing_brief_levels = _brief_mode_levels_in_text(text)
+    meta: dict[str, Any] = {
+        "init_changed": False,
+        "init_present_before": ADAPTER_RULE_BLOCK_BEGIN in text,
+        "brief_levels_before": existing_brief_levels,
+        "brief_changed": False,
+    }
+    if with_init and ADAPTER_RULE_BLOCK_BEGIN not in text:
+        text = _append_managed_block(text, render_repo_rule_block())
+        meta["init_changed"] = True
+    if brief_mode:
+        stripped, removed_levels = _remove_brief_mode_blocks(text)
+        if brief_mode == BRIEF_MODE_OFF:
+            text = stripped
+            meta["brief_changed"] = bool(removed_levels)
+        else:
+            block = render_brief_mode_block(brief_mode)
+            text = _append_managed_block(stripped, block)
+            meta["brief_changed"] = removed_levels != [brief_mode] or text != original_text
+        meta["brief_levels_removed"] = removed_levels
+    meta["changed"] = text != original_text
+    return text, meta
+
+
+def plan_or_write_rule_file_blocks(
+    path: Path,
+    *,
+    with_init: bool,
+    brief_mode: str | None,
+    applied: bool,
+) -> dict[str, Any]:
+    """Plan or apply managed rule-file blocks with one original backup per changed existing write."""
+    result: dict[str, Any] = {
+        "status": None,
+        "planned_actions": [],
+        "applied_actions": [],
+        "brief_mode_status": None,
+        "brief_mode_existing_levels": [],
+        "brief_mode_backup_path": None,
+        "reason": None,
+    }
+    state = _rule_file_state(path)
+    if state["status"] not in {"missing", "file"}:
+        reason = state.get("reason") or f"refused unsafe rule target: {path.name}"
+        result.update({"status": "skipped", "brief_mode_status": "skipped", "reason": reason})
+        result["planned_actions"].append(reason)
+        return result
+
+    existing = state.get("text")
+    existing_text = str(existing or "")
+    result["brief_mode_existing_levels"] = _brief_mode_levels_in_text(existing_text)
+    rule_present = existing is not None and ADAPTER_RULE_BLOCK_BEGIN in existing_text
+    planned_meta: dict[str, Any] | None = None
+    if brief_mode:
+        _, planned_meta = compose_rule_file_text(existing, with_init=with_init, brief_mode=brief_mode)
+
+    if with_init:
+        if rule_present:
+            result["status"] = "exists"
+            result["planned_actions"].append("advisory ContextGuard rules already present")
+        elif not applied:
+            result["status"] = "planned"
+            result["planned_actions"].append("would add advisory ContextGuard rules")
+    elif not brief_mode:
+        result["status"] = "planned"
+        result["planned_actions"].append("run with --with-init to add advisory ContextGuard rules")
+
+    if brief_mode:
+        brief_changed = bool(planned_meta and planned_meta.get("brief_changed"))
+        if brief_mode == BRIEF_MODE_OFF:
+            if brief_changed:
+                result["brief_mode_status"] = "planned" if not applied else None
+                if not applied:
+                    result["planned_actions"].append("would remove advisory brief-mode rules")
+            else:
+                result["brief_mode_status"] = "absent"
+                result["planned_actions"].append("advisory brief-mode rules already absent")
+        else:
+            levels = result["brief_mode_existing_levels"]
+            if not brief_changed:
+                result["brief_mode_status"] = "exists"
+                result["planned_actions"].append(f"advisory brief-mode {brief_mode} rules already present")
+            elif not applied:
+                result["brief_mode_status"] = "planned"
+                action = "refresh" if levels == [brief_mode] else ("replace" if levels else "add")
+                result["planned_actions"].append(f"would {action} advisory brief-mode {brief_mode} rules")
+
+    if not applied:
+        if result["status"] is None:
+            result["status"] = "planned" if result["planned_actions"] else "unchanged"
+        return result
+
+    final_text, meta = compose_rule_file_text(existing, with_init=with_init, brief_mode=brief_mode)
+    if not meta["changed"]:
+        if result["status"] is None:
+            result["status"] = "exists" if rule_present else "unchanged"
+        if result["brief_mode_status"] is None and brief_mode:
+            result["brief_mode_status"] = "absent" if brief_mode == BRIEF_MODE_OFF else "exists"
+        return result
+
+    backup_path = None
+    if existing is not None:
+        try:
+            backup_path = backup_existing(path)
+        except OSError as exc:
+            reason = f"could not back up repo rule file {path.name}: {exc.__class__.__name__}"
+            result.update({"status": "skipped", "brief_mode_status": "skipped", "reason": reason})
+            result["planned_actions"] = [reason]
+            return result
+    durability_warning = None
+    try:
+        atomic_write(
+            path,
+            final_text,
+            existing_mode_or_default(path, 0o644) if existing is not None else 0o644,
+            dir_mode=0o755,
+        )
+    except AtomicWriteDurabilityError as exc:
+        durability_warning = str(exc)
+    except OSError as exc:
+        reason = f"could not write repo rule file {path.name}: {exc.__class__.__name__}"
+        result.update({"status": "skipped", "brief_mode_status": "skipped", "reason": reason})
+        result["planned_actions"] = [reason]
+        return result
+
+    if backup_path:
+        result["brief_mode_backup_path"] = str(backup_path)
+    if durability_warning:
+        result["status"] = "applied-durability-uncertain"
+        result["reason"] = durability_warning
+    if with_init:
+        if not durability_warning:
+            result["status"] = "applied" if meta["init_changed"] else "exists"
+        if meta["init_changed"]:
+            result["applied_actions"].append("wrote advisory ContextGuard rules")
+        else:
+            result["planned_actions"].append("advisory ContextGuard rules already present")
+    elif result["status"] is None:
+        result["status"] = "unchanged"
+    if brief_mode:
+        if brief_mode == BRIEF_MODE_OFF:
+            result["brief_mode_status"] = "removed" if meta["brief_changed"] else "absent"
+            if meta["brief_changed"]:
+                result["applied_actions"].append("removed advisory brief-mode rules")
+            else:
+                result["planned_actions"].append("advisory brief-mode rules already absent")
+        else:
+            before = meta.get("brief_levels_removed") or []
+            if before and before != [brief_mode]:
+                result["brief_mode_status"] = "replaced"
+            elif before == [brief_mode]:
+                result["brief_mode_status"] = "updated"
+            else:
+                result["brief_mode_status"] = "applied"
+            result["applied_actions"].append(f"wrote advisory brief-mode {brief_mode} rules")
+    if durability_warning:
+        result["planned_actions"].append(durability_warning)
+    result["planned_actions"].extend(result["applied_actions"])
+    return result
+
+
 def _read_rule_file_text(path: Path) -> str | None:
     """Best-effort no-follow read; only a missing file is treated as absent.
 
@@ -399,8 +673,38 @@ def _read_rule_file_text(path: Path) -> str | None:
         return None
 
 
+def _existing_rule_parent_issue(path: Path) -> str | None:
+    """Return a reason when an existing parent component is unsafe to traverse.
+
+    Missing parent directories are intentionally allowed: atomic writes create them
+    with explicit modes. Existing symlink/non-directory parents are not allowed,
+    because plan/apply must agree and must never follow an attacker-swapped rule
+    directory outside the project.
+    """
+    parts = path.parts[1:-1] if path.is_absolute() else path.parts[:-1]
+    if not parts:
+        return None
+    current = Path(path.anchor) if path.is_absolute() else Path()
+    for part in parts:
+        current = current / part
+        try:
+            st = os.lstat(current)
+        except FileNotFoundError:
+            return None
+        except OSError as exc:
+            return f"could not inspect rule parent {current}: {exc.__class__.__name__}"
+        if stat.S_ISLNK(st.st_mode):
+            return f"refused to traverse symlinked rule parent: {current}"
+        if not stat.S_ISDIR(st.st_mode):
+            return f"refused non-directory rule parent: {current}"
+    return None
+
+
 def _rule_file_state(path: Path) -> dict[str, Any]:
     """Return a non-throwing state for project rule/skill files."""
+    parent_issue = _existing_rule_parent_issue(path)
+    if parent_issue:
+        return {"status": "unsafe", "text": None, "reason": parent_issue}
     try:
         st = os.lstat(path)
     except FileNotFoundError:
@@ -433,6 +737,7 @@ def write_repo_rule_init(path: Path) -> dict[str, Any]:
 
     Returns a status dict: ``applied`` (block written), ``exists`` (already
     present), or ``skipped`` (refused, e.g. symlinked target) with a reason.
+    Existing user-owned rule files are backed up before any changed write.
     """
     state = _rule_file_state(path)
     if state["status"] not in {"missing", "file"}:
@@ -443,15 +748,30 @@ def write_repo_rule_init(path: Path) -> dict[str, Any]:
     block = render_repo_rule_block()
     if existing:
         new_text = existing.rstrip("\n") + "\n\n" + block + "\n"
-        mode = existing_mode_or_default(path, 0o644)
     else:
         new_text = block + "\n"
-        mode = 0o644
+    mode = existing_mode_or_default(path, 0o644) if existing is not None else 0o644
+    backup_path = None
+    if existing is not None:
+        try:
+            backup_path = backup_existing(path)
+        except OSError as exc:
+            return {"status": "skipped", "reason": f"could not back up repo rule file {path.name}: {exc.__class__.__name__}"}
+    durability_warning = None
     try:
         atomic_write(path, new_text, mode, dir_mode=0o755)
+    except AtomicWriteDurabilityError as exc:
+        durability_warning = str(exc)
     except OSError as exc:
-        return {"status": "skipped", "reason": f"could not write repo rule file {path.name}: {exc.__class__.__name__}"}
-    return {"status": "applied"}
+        result = {"status": "skipped", "reason": f"could not write repo rule file {path.name}: {exc.__class__.__name__}"}
+        if backup_path:
+            result["backup_path"] = str(backup_path)
+        return result
+    result = {"status": "applied", "backup_path": str(backup_path) if backup_path else None}
+    if durability_warning:
+        result["status"] = "applied-durability-uncertain"
+        result["reason"] = durability_warning
+    return result
 
 
 def codex_skill_status(path: Path) -> str:
@@ -518,12 +838,14 @@ def build_adapter_plan(
     with_init: bool,
     with_skill: bool,
     applied: bool,
+    brief_mode: str | None = None,
 ) -> list[dict[str, Any]]:
     """Render a per-adapter plan, performing safe repo-rule writes when applied.
 
-    Only repo-rule adapters write, and only when both ``with_init`` and ``applied``
-    are set. Native-plugin entries mirror the Claude settings result; native-skill
-    and report-only entries are advisory and never write.
+    Repo-rule adapters write when ``applied`` is set and either ``with_init`` or
+    project-scope ``brief_mode`` requested a managed rule-file block. Native-plugin
+    entries mirror the Claude settings result; native-skill and report-only entries
+    are advisory and never write.
     """
     detected = set(detect_agents(root))
     plan: list[dict[str, Any]] = []
@@ -541,6 +863,14 @@ def build_adapter_plan(
             "applied_actions": [],
             "unsupported_reason": None,
         }
+        if brief_mode:
+            entry["brief_mode"] = brief_mode
+            entry["brief_mode_status"] = "unsupported"
+            entry["brief_mode_level"] = None if brief_mode == BRIEF_MODE_OFF else brief_mode
+            entry["brief_mode_file"] = None
+            entry["brief_mode_existing_levels"] = []
+            entry["brief_mode_backup_path"] = None
+            entry["brief_mode_reason"] = None
         if scope == "user" and adapter.key != "claude":
             entry["status"] = "unsupported"
             entry["writable"] = False
@@ -549,6 +879,8 @@ def build_adapter_plan(
                 "use --scope project or run the helper commands manually."
             )
             entry["planned_actions"] = [entry["unsupported_reason"]]
+            if brief_mode:
+                entry["brief_mode_reason"] = entry["unsupported_reason"]
             plan.append(entry)
             continue
         if adapter.capability == CapabilityClass.NATIVE_PLUGIN:
@@ -562,29 +894,91 @@ def build_adapter_plan(
                 entry["status"] = "planned"
             else:
                 entry["status"] = "unchanged"
+            if brief_mode:
+                rule_path = adapter_rule_path(root, adapter)
+                entry["rule_file"] = str(rule_path.relative_to(root)) if rule_path and scope == "project" else adapter.rule_file
+                entry["brief_mode_file"] = entry.get("rule_file")
+                if scope != "project" or rule_path is None:
+                    entry["brief_mode_status"] = "unsupported"
+                    entry["brief_mode_reason"] = "brief-mode rule-file writes are project-scope only"
+                    entry["planned_actions"].append(entry["brief_mode_reason"])
+                else:
+                    result = plan_or_write_rule_file_blocks(
+                        rule_path,
+                        with_init=False,
+                        brief_mode=brief_mode,
+                        applied=applied,
+                    )
+                    entry["brief_mode_status"] = result["brief_mode_status"]
+                    entry["brief_mode_existing_levels"] = result["brief_mode_existing_levels"]
+                    entry["brief_mode_backup_path"] = result["brief_mode_backup_path"]
+                    entry["brief_mode_reason"] = result.get("reason")
+                    for action in result.get("planned_actions", []):
+                        entry["planned_actions"].append(f"{action} in {entry['rule_file']}")
+                    for action in result.get("applied_actions", []):
+                        entry["applied_actions"].append(f"{action} in {entry['rule_file']}")
+                    if result.get("applied_actions"):
+                        entry["status"] = (
+                            result["status"]
+                            if result.get("status") == "applied-durability-uncertain"
+                            else "applied"
+                        )
+                    if result.get("reason"):
+                        entry["brief_mode_reason"] = result.get("reason")
         elif adapter.capability == CapabilityClass.REPO_RULE:
             entry["writable"] = True
             rule_path = adapter_rule_path(root, adapter)
             entry["rule_file"] = str(rule_path.relative_to(root)) if rule_path else adapter.rule_file
-            if rule_path is not None and repo_rule_block_present(rule_path):
-                entry["status"] = "exists"
-                entry["planned_actions"] = [f"advisory ContextGuard rules already present in {entry['rule_file']}"]
-            elif not with_init:
-                entry["status"] = "planned"
-                entry["planned_actions"] = [f"run with --with-init to add advisory ContextGuard rules to {entry['rule_file']}"]
-            elif not applied:
-                entry["status"] = "planned"
-                entry["planned_actions"] = [f"would add advisory ContextGuard rules to {entry['rule_file']}"]
-            elif rule_path is not None:
-                result = write_repo_rule_init(rule_path)
+            if brief_mode and scope != "project":
+                entry["brief_mode_status"] = "unsupported"
+                entry["brief_mode_reason"] = "brief-mode rule-file writes are project-scope only"
+                entry["planned_actions"].append(entry["brief_mode_reason"])
+            elif brief_mode and rule_path is not None:
+                entry["brief_mode_file"] = entry["rule_file"]
+                result = plan_or_write_rule_file_blocks(
+                    rule_path,
+                    with_init=with_init,
+                    brief_mode=brief_mode,
+                    applied=applied,
+                )
                 entry["status"] = result["status"]
-                if result["status"] == "applied":
-                    entry["applied_actions"] = [f"wrote advisory ContextGuard rules to {entry['rule_file']}"]
-                    entry["planned_actions"] = list(entry["applied_actions"])
-                elif result["status"] == "exists":
+                entry["brief_mode_status"] = result["brief_mode_status"]
+                entry["brief_mode_existing_levels"] = result["brief_mode_existing_levels"]
+                entry["brief_mode_backup_path"] = result["brief_mode_backup_path"]
+                entry["brief_mode_reason"] = result.get("reason")
+                entry["planned_actions"] = [f"{action} in {entry['rule_file']}" for action in result.get("planned_actions", [])]
+                entry["applied_actions"] = [f"{action} in {entry['rule_file']}" for action in result.get("applied_actions", [])]
+                if result.get("applied_actions"):
+                    entry["status"] = (
+                        result["status"]
+                        if result.get("status") == "applied-durability-uncertain"
+                        else "applied"
+                    )
+            else:
+                if rule_path is not None and repo_rule_block_present(rule_path):
+                    entry["status"] = "exists"
                     entry["planned_actions"] = [f"advisory ContextGuard rules already present in {entry['rule_file']}"]
-                else:
-                    entry["planned_actions"] = [result.get("reason", "skipped")]
+                elif not with_init:
+                    entry["status"] = "planned"
+                    entry["planned_actions"] = [f"run with --with-init to add advisory ContextGuard rules to {entry['rule_file']}"]
+                elif not applied:
+                    entry["status"] = "planned"
+                    entry["planned_actions"] = [f"would add advisory ContextGuard rules to {entry['rule_file']}"]
+                elif rule_path is not None:
+                    result = write_repo_rule_init(rule_path)
+                    entry["status"] = result["status"]
+                    if result["status"] in {"applied", "applied-durability-uncertain"}:
+                        entry["applied_actions"] = [f"wrote advisory ContextGuard rules to {entry['rule_file']}"]
+                        entry["planned_actions"] = list(entry["applied_actions"])
+                        if result.get("reason"):
+                            entry["planned_actions"].append(result["reason"])
+                            entry["reason"] = result["reason"]
+                        if result.get("backup_path"):
+                            entry["rule_backup_path"] = result["backup_path"]
+                    elif result["status"] == "exists":
+                        entry["planned_actions"] = [f"advisory ContextGuard rules already present in {entry['rule_file']}"]
+                    else:
+                        entry["planned_actions"] = [result.get("reason", "skipped")]
             if adapter.key == "codex" and adapter.project_skill_rel:
                 skill_path = root / adapter.project_skill_rel
                 entry["project_skill_file"] = adapter.project_skill_rel
@@ -623,8 +1017,16 @@ def build_adapter_plan(
                         entry["planned_actions"].append(skill_result.get("reason", "skipped"))
         elif adapter.capability == CapabilityClass.NATIVE_SKILL:
             entry["planned_actions"] = [adapter.summary]
+            if brief_mode:
+                entry["brief_mode_status"] = "unsupported"
+                entry["brief_mode_reason"] = "adapter has no managed rule-file target"
+                entry["planned_actions"].append(entry["brief_mode_reason"])
         else:  # REPORT_ONLY
             entry["planned_actions"] = [adapter.summary]
+            if brief_mode:
+                entry["brief_mode_status"] = "unsupported"
+                entry["brief_mode_reason"] = "adapter has no managed rule-file target"
+                entry["planned_actions"].append(entry["brief_mode_reason"])
         plan.append(entry)
     return plan
 
@@ -695,9 +1097,9 @@ def validate_settings_target(root: Path, settings_path: Path, *, allow_home_sett
             "pass --root <project>, or use --allow-home-settings if you intentionally want this."
         )
     claude_dir = root / ".claude"
-    if claude_dir.exists() and claude_dir.is_symlink():
+    if claude_dir.is_symlink():
         raise SystemExit(f"Refusing to use symlinked Claude settings directory: {claude_dir}")
-    if settings_path.exists() and settings_path.is_symlink():
+    if settings_path.is_symlink():
         raise SystemExit(f"Refusing to write through symlinked settings file: {settings_path}")
     if claude_dir.exists():
         try:
@@ -885,6 +1287,16 @@ def _read_optional_text_no_follow(path: Path) -> str | None:
         raise SystemExit(f"Could not read {path} without following symlinks: {exc}") from exc
 
 
+def _path_exists_no_follow(path: Path) -> bool:
+    try:
+        path.lstat()
+    except FileNotFoundError:
+        return False
+    except OSError:
+        return False
+    return True
+
+
 def _parse_json_object_text(text: str | None, path: Path) -> dict[str, Any]:
     if text is None:
         return {}
@@ -1218,6 +1630,362 @@ def run_post_setup_diet_scan(root: Path) -> dict[str, Any]:
         return {"status": "failed", "reason": "invalid-report"}
 
 
+def doctor_check(
+    ident: str,
+    status: str,
+    severity: str,
+    message: str,
+    *,
+    detail: Any | None = None,
+    next_action: str | None = None,
+) -> dict[str, Any]:
+    check = {
+        "id": ident,
+        "status": status,
+        "severity": severity,
+        "message": message,
+    }
+    if detail is not None:
+        check["detail"] = detail
+    if next_action:
+        check["next_action"] = next_action
+    return check
+
+
+def _setup_command(args: argparse.Namespace, *, apply: bool, root: Path | None = None) -> str:
+    parts = ["context-guard", "setup", "--scope", normalize_scope(getattr(args, "scope", "project"))]
+    if root is not None and normalize_scope(getattr(args, "scope", "project")) == "project":
+        parts.extend(["--root", str(root)])
+    selected = explicit_agent_selection(args)
+    if selected:
+        parts.extend(["--agent", ",".join(selected)])
+    elif normalize_scope(getattr(args, "scope", "project")) == "user":
+        parts.extend(["--agent", "claude"])
+    if getattr(args, "with_init", False):
+        parts.append("--with-init")
+    if getattr(args, "with_skill", False):
+        parts.append("--with-skill")
+    brief_mode = getattr(args, "brief_mode", None)
+    if brief_mode:
+        parts.extend(["--brief-mode", str(brief_mode)])
+    for attr, flag in (
+        ("no_denies", "--no-denies"),
+        ("no_statusline", "--no-statusline"),
+        ("no_bash_hook", "--no-bash-hook"),
+        ("no_read_guard", "--no-read-guard"),
+        ("no_model_defaults", "--no-model-defaults"),
+        ("no_diet_scan", "--no-diet-scan"),
+    ):
+        if getattr(args, attr, False):
+            parts.append(flag)
+    if getattr(args, "failed_attempt_nudge", None) is False:
+        parts.append("--no-failed-attempt-nudge")
+    elif getattr(args, "failed_attempt_nudge", None) is True:
+        parts.append("--failed-attempt-nudge")
+    parts.append("--yes" if apply else "--plan")
+    return shlex.join(parts)
+
+
+def _doctor_status(checks: list[dict[str, Any]]) -> str:
+    if any(check.get("status") == "error" or check.get("severity") == "error" for check in checks):
+        return "error"
+    if any(check.get("status") == "warning" or check.get("severity") in {"high", "medium"} for check in checks):
+        return "warning"
+    return "ok"
+
+
+def _helper_availability_check(*, include_diet: bool = True) -> dict[str, Any]:
+    helpers = {
+        HELPER_STATUSLINE: "statusline_merged.sh",
+        HELPER_REWRITE_BASH: "rewrite_bash_for_token_budget.py",
+        HELPER_GUARD_READ: "guard_large_read.py",
+        HELPER_FAILED_NUDGE: "failed_attempt_nudge.py",
+    }
+    if include_diet:
+        helpers[HELPER_DIET] = "context_guard_diet.py"
+    resolved: dict[str, str] = {}
+    missing: list[str] = []
+    for helper, kit_script in helpers.items():
+        try:
+            resolved[helper] = shlex.join(helper_argv(helper, kit_script, shell=("bash" if kit_script.endswith(".sh") else None)))
+        except SystemExit:
+            missing.append(helper)
+    if missing:
+        return doctor_check(
+            "helper-availability",
+            "error",
+            "error",
+            "Some ContextGuard helper commands could not be resolved.",
+            detail={"missing": missing, "resolved": resolved},
+            next_action="Reinstall ContextGuard or run from a complete checkout.",
+        )
+    return doctor_check(
+        "helper-availability",
+        "ok",
+        "low",
+        "Required ContextGuard helper commands are resolvable.",
+        detail={"resolved": resolved},
+    )
+
+
+def _adapter_warning_detail(entry: dict[str, Any]) -> dict[str, Any]:
+    detail = {
+        "key": entry.get("key"),
+        "status": entry.get("status"),
+        "planned_actions": entry.get("planned_actions", []),
+        "unsupported_reason": entry.get("unsupported_reason"),
+    }
+    for key in ("brief_mode", "brief_mode_status", "brief_mode_reason", "brief_mode_file"):
+        if key in entry:
+            detail[key] = entry.get(key)
+    return detail
+
+
+def run_doctor(args: argparse.Namespace) -> dict[str, Any]:
+    """Return a read-only setup health report.
+
+    This intentionally mirrors setup planning while never prompting, backing up,
+    writing settings, writing rule files, or creating rollback records.
+    """
+    require_no_follow_file_ops_supported()
+    scope = normalize_scope(getattr(args, "scope", "project"))
+    root = resolve_scope_root(args.root, scope)
+    settings_path = root / SETTINGS_REL
+    helper_check = _helper_availability_check(include_diet=not getattr(args, "no_diet_scan", False))
+    checks: list[dict[str, Any]] = [helper_check]
+    warnings: list[str] = []
+    if scope == "user":
+        warnings.append("user-scope verify is read-only; applying user-scope setup still requires --yes and an explicit agent")
+
+    selected_agents = explicit_agent_selection(args)
+    targets = resolve_target_adapters(root, selected_agents)
+    claude_targeted = any(adapter.key == "claude" for adapter in targets)
+
+    original_text = None
+    original: dict[str, Any] = {}
+    settings: dict[str, Any] = {}
+    if claude_targeted:
+        try:
+            validate_settings_target(root, settings_path, allow_home_settings=(args.allow_home_settings or scope == "user"))
+            original_text = _read_optional_text_no_follow(settings_path)
+            original = _parse_json_object_text(original_text, settings_path)
+            settings = json.loads(json.dumps(original))
+            checks.append(doctor_check(
+                "settings-target",
+                "ok",
+                "low",
+                "Claude settings target is readable without following symlinks.",
+                detail={
+                    "exists": original_text is not None,
+                    "path": str(settings_path),
+                },
+            ))
+        except SystemExit as exc:
+            checks.append(doctor_check(
+                "settings-target",
+                "error",
+                "error",
+                "Claude settings target could not be read as a safe JSON object.",
+                detail={
+                    "exists": _path_exists_no_follow(settings_path),
+                    "path": str(settings_path),
+                    "error": str(exc),
+                },
+                next_action=f"Fix or remove {settings_path} before running setup or verify again.",
+            ))
+            return {
+                "schema_version": "contextguard.doctor.v1",
+                "status": "error",
+                "root": str(root),
+                "scope": scope,
+                "settings_path": str(settings_path),
+                "read_only": True,
+                "warnings": warnings,
+                "checks": checks,
+                "setup_plan": {
+                    "changed": False,
+                    "actions": [],
+                    "adapter_plan": [],
+                },
+                "diet_scan": {"status": "skipped", "reason": "settings-target-error"},
+                "recommended_commands": [],
+            }
+    else:
+        checks.append(doctor_check(
+            "settings-target",
+            "ok",
+            "low",
+            "Claude settings target was not requested for selected adapters.",
+            detail={"path": str(settings_path)},
+        ))
+
+    if helper_check.get("status") == "error":
+        diet_scan = {"status": "skipped", "reason": "helper-unavailable"}
+        return {
+            "schema_version": "contextguard.doctor.v1",
+            "status": "error",
+            "root": str(root),
+            "scope": scope,
+            "settings_path": str(settings_path),
+            "read_only": True,
+            "warnings": warnings,
+            "checks": checks,
+            "setup_plan": {
+                "changed": False,
+                "actions": [],
+                "adapter_plan": [],
+            },
+            "diet_scan": diet_scan,
+            "recommended_commands": [],
+        }
+
+    choices = choices_from_args(args)
+    actions = apply_choices(settings, choices) if claude_targeted else []
+    changed = (settings != original) if claude_targeted else False
+    if changed:
+        checks.append(doctor_check(
+            "setup-plan",
+            "warning",
+            "medium",
+            "ContextGuard setup is not fully applied for the requested selections.",
+            detail={"planned_action_count": len(actions), "planned_actions": actions},
+            next_action=_setup_command(args, apply=False, root=root),
+        ))
+    else:
+        checks.append(doctor_check(
+            "setup-plan",
+            "ok",
+            "low",
+            "Requested setup settings are already satisfied.",
+            detail={"planned_action_count": 0},
+        ))
+
+    adapter_plan = build_adapter_plan(
+        root,
+        targets,
+        scope=scope,
+        claude_actions=actions,
+        claude_changed=changed,
+        claude_applied=False,
+        with_init=bool(getattr(args, "with_init", False)),
+        with_skill=bool(getattr(args, "with_skill", False)),
+        applied=False,
+        brief_mode=getattr(args, "brief_mode", None),
+    )
+    adapter_warnings = [
+        _adapter_warning_detail(entry)
+        for entry in adapter_plan
+        if entry.get("status") in {"planned", "unsupported", "skipped"}
+    ]
+    if adapter_warnings:
+        checks.append(doctor_check(
+            "adapter-plan",
+            "warning",
+            "medium",
+            "Some requested adapters still have planned or unsupported setup actions.",
+            detail={"adapters": adapter_warnings},
+            next_action=_setup_command(args, apply=False, root=root),
+        ))
+    else:
+        checks.append(doctor_check(
+            "adapter-plan",
+            "ok",
+            "low",
+            "Requested adapter setup plan has no pending supported writes.",
+            detail={"adapter_count": len(adapter_plan)},
+        ))
+
+    diet_scan = None
+    if getattr(args, "no_diet_scan", False):
+        diet_scan = {"status": "skipped", "reason": "disabled-by-flag"}
+        checks.append(doctor_check(
+            "diet-scan",
+            "ok",
+            "low",
+            "Context hygiene scan was skipped by flag.",
+            detail=diet_scan,
+        ))
+    else:
+        diet_next_action = shlex.join(["context-guard", "diet", "scan", str(root), "--json"])
+        diet_scan = run_post_setup_diet_scan(root)
+        if diet_scan.get("status") != "completed":
+            checks.append(doctor_check(
+                "diet-scan",
+                "warning",
+                "medium",
+                "Context hygiene scan could not complete.",
+                detail=diet_scan,
+                next_action=diet_next_action,
+            ))
+        else:
+            counts = diet_scan.get("severity_counts", {})
+            high_medium = int(counts.get("high", 0) or 0) + int(counts.get("medium", 0) or 0)
+            if high_medium:
+                checks.append(doctor_check(
+                    "diet-scan",
+                    "warning",
+                    "medium",
+                    "Context hygiene scan found high/medium findings.",
+                    detail=diet_scan,
+                    next_action=diet_next_action,
+                ))
+            else:
+                checks.append(doctor_check(
+                    "diet-scan",
+                    "ok",
+                    "low",
+                    "Context hygiene scan has no high/medium findings.",
+                    detail=diet_scan,
+                ))
+
+    recommended = [_setup_command(args, apply=False, root=root)]
+    if changed or adapter_warnings:
+        recommended.append(_setup_command(args, apply=True, root=root))
+    return {
+        "schema_version": "contextguard.doctor.v1",
+        "status": _doctor_status(checks),
+        "root": str(root),
+        "scope": scope,
+        "settings_path": str(settings_path),
+        "read_only": True,
+        "warnings": warnings,
+        "checks": checks,
+        "setup_plan": {
+            "changed": changed,
+            "actions": actions,
+            "adapter_plan": adapter_plan,
+        },
+        "diet_scan": diet_scan,
+        "recommended_commands": recommended,
+    }
+
+
+def render_doctor_text(report: dict[str, Any]) -> str:
+    lines = [
+        f"ContextGuard doctor ({report.get('status', 'unknown')})",
+        "read-only health check; no changes made",
+        f"scope={report.get('scope')}",
+        f"root={report.get('root')}",
+        f"settings={report.get('settings_path')}",
+    ]
+    warnings = report.get("warnings") or []
+    if warnings:
+        lines.append("warnings:")
+        lines.extend(f"- {warning}" for warning in warnings)
+    lines.append("checks:")
+    for check in report.get("checks", []):
+        lines.append(
+            f"- [{str(check.get('status', '')).upper()}] {check.get('id')}: {check.get('message')}"
+        )
+        if check.get("next_action"):
+            lines.append(f"  next: {check['next_action']}")
+    commands = report.get("recommended_commands") or []
+    if commands:
+        lines.append("recommended next commands:")
+        lines.extend(f"- {command}" for command in commands)
+    return "\n".join(lines) + "\n"
+
+
 def apply_choices(settings: dict[str, Any], choices: Choices) -> list[str]:
     actions: list[str] = []
     if choices.model_defaults:
@@ -1461,12 +2229,17 @@ def render_text(result: SetupResult) -> str:
     # Only surface the cross-agent section when a non-Claude adapter is engaged,
     # keeping the default Claude-only text output unchanged.
     extra_adapters = [entry for entry in (result.adapter_plan or []) if entry.get("key") != "claude"]
-    if extra_adapters:
+    brief_adapters = [entry for entry in (result.adapter_plan or []) if entry.get("brief_mode")]
+    if extra_adapters or brief_adapters:
         lines.append("cross-agent adapters:")
         for entry in result.adapter_plan or []:
             lines.append(f"- {entry['key']} [{entry['capability']}] status={entry['status']}")
             for action in entry.get("planned_actions", []):
                 lines.append(f"  - {action}")
+            if entry.get("brief_mode_backup_path"):
+                lines.append(f"  - backup={entry['brief_mode_backup_path']}")
+            if entry.get("rule_backup_path"):
+                lines.append(f"  - backup={entry['rule_backup_path']}")
     if result.apply_requested and not result.applied:
         lines.append("No supported writes were applied.")
     elif not result.applied:
@@ -1575,8 +2348,8 @@ def run(args: argparse.Namespace) -> SetupResult:
         finally:
             release_settings_lock(lock_fd)
 
-    # Build the per-adapter plan; repo-rule writes happen here only when both
-    # --with-init and an applying run (--yes) are in effect.
+    # Build the per-adapter plan; repo-rule writes happen here when an applying
+    # run (--yes) requested --with-init or project-scope --brief-mode.
     adapter_plan = build_adapter_plan(
         root,
         targets,
@@ -1587,6 +2360,7 @@ def run(args: argparse.Namespace) -> SetupResult:
         with_init=bool(getattr(args, "with_init", False)),
         with_skill=bool(getattr(args, "with_skill", False)),
         applied=apply_requested,
+        brief_mode=getattr(args, "brief_mode", None),
     )
     # Surface any repo-rule writes in the top-level actions for visibility. Claude
     # actions are already in ``actions``; only adapter-side writes are appended.
@@ -1634,6 +2408,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--yes", action="store_true", help="apply the recommended/selected setup without prompts")
     parser.add_argument("--plan", action="store_true", help="show the setup plan without writing files")
     parser.add_argument("--dry-run", action="store_true", help="alias for --plan")
+    parser.add_argument("--verify", action="store_true", help="run a read-only setup health check; never writes or prompts")
     parser.add_argument("--json", action="store_true", help="print machine-readable result")
     parser.add_argument("--no-backup", action="store_true", help="do not create .bak-* before modifying existing settings")
     parser.add_argument("--no-denies", action="store_true", help="skip recommended permissions.deny rules")
@@ -1670,6 +2445,12 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="also generate optional project-local skill files where supported, currently Codex .agents/skills/context-guard/SKILL.md.",
     )
+    parser.add_argument(
+        "--brief-mode",
+        choices=BRIEF_MODE_CHOICES,
+        default=None,
+        help="plan/apply advisory brief-mode snippets in project rule files; choose lite, standard, ultra, or off to remove.",
+    )
     parser.add_argument(
         "--list-adapters",
         dest="list_adapters",
@@ -1699,6 +2480,8 @@ def main() -> int:
     args = parser.parse_args()
     if args.dry_run:
         args.plan = True
+    if args.verify and args.yes:
+        parser.error("--verify is read-only and cannot be combined with --yes")
     if getattr(args, "list_adapters", False):
         payload = adapter_registry_payload()
         if args.json:
@@ -1708,6 +2491,14 @@ def main() -> int:
             for item in payload:
                 print(f"- {item['key']} [{item['capability']}] {item['display_name']}: {item['summary']}")
         return 0
+    if args.verify:
+        args.plan = True
+        result = run_doctor(args)
+        if args.json:
+            print(json.dumps(result, indent=2, sort_keys=True))
+        else:
+            print(render_doctor_text(result))
+        return 0
     # Safety default for non-interactive Claude Code Bash calls: do not write
     # unless --yes is explicit.
     if not sys.stdin.isatty() and not args.yes: