@caddis/cli 0.2.5 → 0.3.0

package/bundles/antigravity-plugin/scripts/claude-deepseek.ps1

@@ -0,0 +1,4 @@
+# claude-deepseek — convenience alias: a Claude Code session on DeepSeek (provider preset "deepseek").
+# Thin delegator so the logic lives once in claude-oss.ps1.
+& "$PSScriptRoot\claude-oss.ps1" deepseek @args
+exit $LASTEXITCODE

package/bundles/antigravity-plugin/scripts/claude-deepseek.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# claude-deepseek — convenience alias: a Claude Code session on DeepSeek (provider preset "deepseek").
+exec "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/claude-oss.sh" deepseek "$@"

package/bundles/antigravity-plugin/scripts/claude-glm.ps1

@@ -0,0 +1,4 @@
+# claude-glm — convenience alias: a Claude Code session on GLM (provider preset "glm").
+# Thin delegator so the logic lives once in claude-oss.ps1.
+& "$PSScriptRoot\claude-oss.ps1" glm @args
+exit $LASTEXITCODE

package/bundles/antigravity-plugin/scripts/claude-glm.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# claude-glm — convenience alias: a Claude Code session on GLM (provider preset "glm").
+exec "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/claude-oss.sh" glm "$@"

package/bundles/antigravity-plugin/scripts/claude-oss.ps1

@@ -0,0 +1,64 @@
+# claude-oss / claude-glm — launch a Claude Code session against an OSS provider's
+# Anthropic-protocol endpoint (GLM, DeepSeek, or a custom OSS_BASE_URL/OSS_MODEL;
+# OpenRouter/local models need an Anthropic-compatible gateway — see LOCAL-MODELS.md).
+#
+# Usage:
+#   claude-oss <provider> [claude args...]     # e.g. claude-oss glm -p "say ok"
+#   claude-glm [claude args...]                # convenience alias (provider = glm)
+#
+# Endpoint/model/key are resolved by oss_model.py (keys are never hardcoded — see
+# CADDIS_KEYS_FILE). This reads $args directly and declares NO parameter block: a
+# declared parameter would swallow claude's own flags (e.g. -p) before claude sees them.
+# The ANTHROPIC_* env is saved and RESTORED in finally, so your default `claude` in this
+# session is untouched.
+$ErrorActionPreference = "Stop"
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$invoked = [System.IO.Path]::GetFileNameWithoutExtension($MyInvocation.MyCommand.Name)
+
+# claude-glm forces provider=glm and passes every arg to claude; otherwise the first
+# arg is the provider and the rest go to claude.
+if ($invoked -like "claude-glm*") {
+  $provider = "glm"
+  $rest = $args
+} else {
+  $provider = if ($args.Count -ge 1) { $args[0] } else { $null }
+  $rest = if ($args.Count -ge 2) { $args[1..($args.Count - 1)] } else { @() }
+}
+
+if (-not $provider) {
+  Write-Error "usage: claude-oss <provider> [claude args...]   (providers: deepseek, glm, openrouter)"
+  exit 2
+}
+
+# Save the current ANTHROPIC_* so we can restore them — this launcher shares the session.
+$restore = @{}
+foreach ($name in "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL", "ANTHROPIC_AUTH_TOKEN", "CADDIS_HEADLESS") {
+  $restore[$name] = [Environment]::GetEnvironmentVariable($name)
+}
+
+# claude's -p/--print means no human is watching. Say so in the env so the caddis hooks can
+# act on it — the SessionStart relay injection is skipped for headless runs, because a run
+# handed its task on the command line does not need a resume pointer and was observed
+# EXECUTING the relay's leftover next step before its own prompt.
+$headless = $false
+foreach ($a in $rest) { if ($a -eq "-p" -or $a -eq "--print") { $headless = $true } }
+if ($headless) { $env:CADDIS_HEADLESS = "1" }
+
+try {
+  # Resolve endpoint/model/key. The three stdout lines are captured into a variable and
+  # assigned to the env — the key is never written to the console.
+  $cfg = & python "$scriptDir\oss_model.py" $provider
+  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+  $env:ANTHROPIC_BASE_URL   = $cfg[0]
+  $env:ANTHROPIC_MODEL      = $cfg[1]
+  $env:ANTHROPIC_AUTH_TOKEN = $cfg[2]
+
+  & claude @rest
+  exit $LASTEXITCODE
+} finally {
+  foreach ($name in $restore.Keys) {
+    Set-Item -Path "Env:$name" -Value $restore[$name] -ErrorAction SilentlyContinue
+    if ($null -eq $restore[$name]) { Remove-Item -Path "Env:$name" -ErrorAction SilentlyContinue }
+  }
+}

package/bundles/antigravity-plugin/scripts/claude-oss.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# claude-oss / claude-glm — launch a Claude Code session against an OSS provider's
+# Anthropic-protocol endpoint (GLM, DeepSeek, or a custom OSS_BASE_URL/OSS_MODEL;
+# OpenRouter/local models need an Anthropic-compatible gateway — see LOCAL-MODELS.md).
+#
+# Usage:
+#   claude-oss <provider> [claude args...]     # e.g. claude-oss glm -p "say ok"
+#   claude-glm [claude args...]                # convenience alias (provider = glm)
+#
+# The endpoint/model/key are resolved by oss_model.py (keys are never hardcoded — see
+# CADDIS_KEYS_FILE). This runs as its OWN process and `exec`s claude, so the
+# ANTHROPIC_* env it sets dies with it — your default `claude` is untouched.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# claude-glm is the same launcher symlinked/renamed: force provider=glm and treat every
+# arg as a claude arg. Otherwise the first arg is the provider.
+case "$(basename "$0")" in
+  claude-glm*) provider="glm" ;;
+  *)
+    provider="${1:-}"
+    if [ "$#" -gt 0 ]; then shift; fi
+    ;;
+esac
+
+if [ -z "${provider}" ]; then
+  echo "usage: claude-oss <provider> [claude args...]   (providers: deepseek, glm, openrouter)" >&2
+  exit 2
+fi
+
+# claude's -p/--print means no human is watching. Say so in the env so the caddis hooks can
+# act on it — the SessionStart relay injection is skipped for headless runs, because a run
+# handed its task on the command line does not need a resume pointer and was observed
+# EXECUTING the relay's leftover next step before its own prompt.
+for _arg in "$@"; do
+  case "$_arg" in
+    -p|--print) export CADDIS_HEADLESS=1 ;;
+  esac
+done
+
+# Prefer python3, fall back to python.
+PY="python3"; command -v "$PY" >/dev/null 2>&1 || PY="python"
+
+# Resolve endpoint/model/key. On failure the resolver prints an actionable message to
+# stderr and exits non-zero — propagate that (command substitution lets us check it).
+if ! _out="$("$PY" "$SCRIPT_DIR/oss_model.py" "$provider")"; then
+  exit 3
+fi
+
+# Split the three lines (base_url, model, api_key) into the env WITHOUT echoing them.
+{
+  IFS= read -r ANTHROPIC_BASE_URL
+  IFS= read -r ANTHROPIC_MODEL
+  IFS= read -r ANTHROPIC_AUTH_TOKEN
+} <<< "$_out"
+export ANTHROPIC_BASE_URL ANTHROPIC_MODEL ANTHROPIC_AUTH_TOKEN
+
+# Hand off to the real claude with all remaining args (exec = env dies with this process).
+exec claude "$@"

package/bundles/antigravity-plugin/scripts/claudster_config.py

@@ -0,0 +1,126 @@
+"""Shared identity + config reader for a repo's caddis artifact dir — fail-open, dependency-free.
+
+Two jobs:
+
+1. **Functional identity in ONE place.** The artifact dir name, the env-var prefix, and the
+   repo/tarball URL are constants here, so a future rename edits a constant instead of sweeping
+   the tree. Anything that needs them imports from this module.
+2. **The optional per-repo ``config.toml`` reader**, so the doc-coverage checker and Dream Memory
+   don't each reimplement it (the guard hook keeps its own tiny reader — it lives under hooks/ and
+   is safety-critical, so it stays self-contained). Every function returns a safe default rather
+   than raising: a missing file, a parse error, a missing section, or a wrong-typed value all
+   degrade to the caller's default — the "degrade gracefully, never block" bar of the rest of caddis.
+
+The per-repo artifact dir is always ``.caddis`` — use :func:`artifact_root` / :func:`artifact_read` /
+:func:`artifact_write`. A repo still carrying a pre-rename ``.claudster/`` (there should be none left
+in this fleet) can be converted with ``/caddis:migrate-dir`` (``scripts/caddis_migrate_dir.py``);
+nothing renames a repo's dir behind its back.
+
+Config schema (see ``.caddis/config.toml.example``)::
+
+    [doc_coverage]
+    route_tree = "frontend/src/routeTree.gen.ts"
+    page_guide = "UI_PAGE_GUIDE.md"
+    claude_md_budget = 200
+    ignore_routes = ["/health"]
+
+    [dream_memory]
+    prune_age_days = 14
+    max_facts = 200
+    surface_limit = 5
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# ── functional identity (rename here, not everywhere) ────────────────────────
+#: The per-repo artifact directory caddis writes into.
+ARTIFACT_DIR = ".caddis"
+#: Read-preference order for the artifact dir. Single-element tuple kept so importers that iterate
+#: this (a future rename adds an element here, not at each call site) don't need to change shape.
+ARTIFACT_DIRS: tuple[str, ...] = (ARTIFACT_DIR,)
+
+#: Environment-variable prefix — every caddis env var is ``<ENV_PREFIX>_<SUFFIX>``.
+ENV_PREFIX = "CADDIS"
+
+#: The published plugin repo (mirror). Everything URL-shaped derives from this one slug.
+REPO_SLUG = "saajunaid/caddis-plugin"
+REPO_URL = f"https://github.com/{REPO_SLUG}"
+TARBALL_URL = f"https://codeload.github.com/{REPO_SLUG}/tar.gz/refs/heads/main"
+
+
+def env_name(suffix: str) -> str:
+    """The current env-var name for ``suffix`` (e.g. ``"GUARD_DISABLED"`` → ``CADDIS_GUARD_DISABLED``)."""
+    return f"{ENV_PREFIX}_{suffix}"
+
+
+def env_get(suffix: str, default: str | None = None) -> str | None:
+    """``$CADDIS_<suffix>``."""
+    val = os.environ.get(env_name(suffix))
+    return default if val is None else val
+
+
+# ── artifact-dir resolution ───────────────────────────────────────────────────
+def artifact_root(root) -> Path:
+    """The artifact dir to WRITE into for ``root`` — always ``.caddis``.
+
+    Returns a path that may not exist yet — callers ``mkdir`` as needed.
+    """
+    return Path(root) / ARTIFACT_DIR
+
+
+def artifact_dir_name(root) -> str:
+    """Just the directory NAME the repo lives in (``".caddis"``) — for messages."""
+    return artifact_root(root).name
+
+
+def artifact_read(root, *parts) -> Path:
+    """``.caddis/<parts>`` — the path to read an artifact from."""
+    return artifact_root(root).joinpath(*parts)
+
+
+def artifact_write(root, *parts) -> Path:
+    """Path under :func:`artifact_root` — where a NEW artifact should be written."""
+    return artifact_root(root).joinpath(*parts)
+
+
+def load_config(root, section: str) -> dict:
+    """Return the ``[section]`` table from the repo's ``.caddis/config.toml``, or ``{}`` on any problem."""
+    try:
+        import tomllib  # Python 3.11+ stdlib
+    except Exception:
+        return {}
+    cfg = artifact_read(root, "config.toml")
+    if not cfg.is_file():
+        return {}
+    try:
+        with open(cfg, "rb") as fh:
+            data = tomllib.load(fh)
+    except Exception:
+        return {}
+    sec = data.get(section, {})
+    return sec if isinstance(sec, dict) else {}
+
+
+def get_int(cfg: dict, key: str, default: int) -> int:
+    """A positive int from ``cfg[key]``, else ``default`` (rejects bool, non-int, and < 1)."""
+    v = cfg.get(key, default)
+    if isinstance(v, bool) or not isinstance(v, int) or v < 1:
+        return default
+    return v
+
+
+def get_str(cfg: dict, key: str, default: str) -> str:
+    """A non-empty string from ``cfg[key]``, else ``default``."""
+    v = cfg.get(key, default)
+    return v if isinstance(v, str) and v.strip() else default
+
+
+def get_str_list(cfg: dict, key: str, default: list[str]) -> list[str]:
+    """A list-of-strings from ``cfg[key]``, else ``default``."""
+    v = cfg.get(key, default)
+    if isinstance(v, list) and all(isinstance(x, str) for x in v):
+        return v
+    return default

package/bundles/antigravity-plugin/scripts/claudster_doctor.py

@@ -0,0 +1,356 @@
+"""claudster_doctor — read-only health + maintenance report for a caddis install, any harness.
+
+Diagnoses the things that silently break a cross-harness setup: a harness binary missing from PATH
+(the Windows "new terminal" gotcha), a harness version that has drifted past the probed contract,
+rules-file integrity (root AGENTS.md present; CLAUDE.md is a shim, not a fork), the user-level skills
+path, and python for the tooling itself. It also computes DETERMINISTIC maintenance signals (no LLM):
+an oversize always-loaded AGENTS.md, dangling DOC-MAP links, harness-contract version drift, and days
+since the last doctor run. Read-only; exit 1 on a hard failure.
+
+Usage:
+    python claudster_doctor.py                 # check cwd + all known harnesses
+    python claudster_doctor.py --dest <proj>   # check a specific project's rules
+    python claudster_doctor.py --quiet         # only the one-line maintenance nudge (for SessionStart)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Probed contract versions (docs/analysis/*-contract.md). WARN when the installed binary drifts past
+# these — the recorded schemas may be stale and want a re-probe.
+PROBED_VERSIONS = {"codex": "0.137", "agy": "1.1.5"}
+AGENTS_MD_BUDGET = 200  # always-loaded rules file line budget (mirrors check_doc_coverage)
+
+# Per-repo artifact dir + env prefix, mirrored from claude-harness/scripts/claudster_config.py —
+# the doctor is a standalone, import-free diagnostic that must run from a bare checkout.
+ARTIFACT_DIRS = (".caddis",)
+ENV_PREFIX = "CADDIS"
+
+
+def _home() -> Path:
+    return Path(os.environ.get(f"{ENV_PREFIX}_FAKE_HOME") or Path.home())
+
+
+def _user_scope_path(name: str) -> Path:
+    """A ``~/.caddis/<name>`` user-scope file."""
+    return _home() / ".caddis" / name
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _which(name: str) -> str | None:
+    hit = shutil.which(name)
+    if hit:
+        return hit
+    # off-PATH but installed (the agy case on Windows): probe the known install dir
+    if name == "agy":
+        cand = _home() / "AppData" / "Local" / "agy" / "bin" / "agy.exe"
+        if cand.is_file():
+            return str(cand)
+    return None
+
+
+def _binary_version(path: str) -> str | None:
+    try:
+        out = subprocess.run([path, "--version"], capture_output=True, text=True, timeout=20)
+        return (out.stdout or out.stderr).strip().splitlines()[0] if (out.stdout or out.stderr) else None
+    except Exception:
+        return None
+
+
+# ── rules integrity (self-contained fork detector — same rule as claudster_migrate_rules --check) ──
+_SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", "done", "archive"}
+
+
+def _is_shim(text: str) -> bool:
+    return any(ln.strip() == "@AGENTS.md" for ln in text.splitlines())
+
+
+def rules_findings(dest: Path) -> list[str]:
+    """Fork detector: a non-shim CLAUDE.md beside an AGENTS.md, or a bare CLAUDE.md with no sibling."""
+    dest = Path(dest)
+    out: list[str] = []
+    for dirpath, dirnames, filenames in os.walk(dest):
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+        if "CLAUDE.md" not in filenames:
+            continue
+        d = Path(dirpath)
+        rel = (d / "CLAUDE.md").relative_to(dest).as_posix()
+        try:
+            text = (d / "CLAUDE.md").read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if "AGENTS.md" in filenames:
+            if not _is_shim(text):
+                out.append(f"{rel}: not a shim but a sibling AGENTS.md exists (drifted shim)")
+        else:
+            out.append(f"{rel}: bare CLAUDE.md with no sibling AGENTS.md (fork — run /caddis:add-rules)")
+    return out
+
+
+def oversize_rules_files(dest: Path, budget: int = AGENTS_MD_BUDGET) -> list[tuple[str, int]]:
+    """Always-loaded rules files (AGENTS.md, or CLAUDE.md pre-migration) over the line budget."""
+    dest = Path(dest)
+    out: list[tuple[str, int]] = []
+    for dirpath, dirnames, filenames in os.walk(dest):
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+        d = Path(dirpath)
+        f = "AGENTS.md" if "AGENTS.md" in filenames else ("CLAUDE.md" if "CLAUDE.md" in filenames else None)
+        if not f:
+            continue
+        try:
+            n = len((d / f).read_text(encoding="utf-8", errors="replace").splitlines())
+        except OSError:
+            continue
+        if n > budget:
+            out.append(((d / f).relative_to(dest).as_posix(), n))
+    return out
+
+
+def _severity_word(ratio: float) -> str:
+    """Coarse severity label so a 1.1x overage doesn't read identically to a 5x one
+    (register 0e: the nudge used to print the exact same sentence for both)."""
+    if ratio >= 3.0:
+        return "way"
+    if ratio >= 1.5:
+        return "well"
+    return "slightly"
+
+
+def oversize_message(rel_path: str, lines: int, budget: int = AGENTS_MD_BUDGET) -> str:
+    """One-line, severity-scaled description of an oversize rules file. Shared by the
+    SessionStart/PreCompact nudge (nudge_line) and the PostToolUse re-warn
+    (hooks/rules_budget_nudge.py) so both read identically and the threshold lives in
+    exactly one place: ``AGENTS_MD_BUDGET`` above (mirrored in check_doc_coverage.py)."""
+    ratio = lines / budget if budget else 0.0
+    return (f"AGENTS.md {_severity_word(ratio)} over budget "
+            f"({rel_path}: {lines} lines, {ratio:.1f}x the {budget}-line budget) — run claude-md-curator")
+
+
+def docmap_dangling(dest: Path) -> list[str]:
+    """Dangling `.md` links in <artifact-dir>/kb/DOC-MAP.md (the '/caddis:kb' signal)."""
+    dm = next((p for p in (Path(dest) / n / "kb" / "DOC-MAP.md" for n in ARTIFACT_DIRS) if p.is_file()), None)
+    if dm is None:
+        return []
+    import re
+    text = dm.read_text(encoding="utf-8", errors="replace")
+    text = re.sub(r"\A---\r?\n.*?\r?\n---\r?\n", "", text, flags=re.DOTALL)
+    text = re.sub(r"<!--.*?-->", "", text, flags=re.DOTALL)
+    dangling = []
+    for target in re.findall(r"\]\(([^)]+\.md)\)", text):
+        target = target.strip()
+        if target.startswith(("http://", "https://")):
+            continue
+        resolved = (dm.parent / target).resolve()
+        if not resolved.exists():
+            dangling.append(target)
+    return dangling
+
+
+# ── maintenance signals + nudge ──────────────────────────────────────────────
+def _last_doctor_path() -> Path:
+    return _user_scope_path("last-doctor.json")
+
+
+def days_since_last_doctor() -> int | None:
+    p = _last_doctor_path()
+    if not p.is_file():
+        return None
+    try:
+        ts = json.loads(p.read_text(encoding="utf-8")).get("timestamp")
+        last = datetime.fromisoformat(ts)
+        return (_now() - last).days
+    except Exception:
+        return None
+
+
+def _stamp_last_doctor() -> None:
+    p = _last_doctor_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps({"timestamp": _now().isoformat(timespec="seconds")}) + "\n", encoding="utf-8")
+
+
+def version_drift() -> list[str]:
+    out = []
+    for name, probed in PROBED_VERSIONS.items():
+        path = _which(name)
+        if not path:
+            continue
+        ver = _binary_version(path) or ""
+        # crude: if the probed version string isn't a substring of the reported version, it drifted
+        digits = "".join(c for c in ver if c.isdigit() or c == ".")
+        if probed not in digits and digits:
+            out.append(f"{name} {digits.strip('.')} vs probed {probed} — re-probe the contract")
+    return out
+
+
+def _is_caddis_source(dest: Path) -> bool:
+    """True for the caddis authoring repo, where `.github/tools/` is the MASTER, not a copy.
+
+    Without this the drift check fires permanently in the one repo where a difference is the
+    normal state — and a check that is always red is a check nobody reads."""
+    return (dest / "claude-harness").is_dir()
+
+
+def _norm(text: str) -> str:
+    return text.replace("\r\n", "\n").strip()
+
+
+def vendored_drift(dest: Path, plugin_root: Path | None = None) -> list[str]:
+    """Vendored `.github/tools/*.py` copies that no longer match the plugin's shipped copy.
+
+    WHY THIS EXISTS
+    ---------------
+    `/caddis:cross-review` resolved its tool as `.github/tools/oss_review.py` FIRST and the plugin
+    copy second, with nothing comparing them. On 2026-08-10 a repo ran a stale vendored
+    `oss_review.py` and got a false CLEAN on a database write path; the fixed copy was sitting
+    unused in the plugin the whole time. The bug had been fixed on 2026-08-01 and the fix simply
+    never reached the caller.
+
+    That is worse than an ordinary stale file. It means **any** caddis fix is untrustworthy in a
+    repo that vendored early, and nothing anywhere reports the skew. The vendoring itself was
+    reasonable when it happened — the plugin did not ship these scripts until 2026-07-30 — which is
+    exactly why the copies are still lying around.
+
+    Pure file comparison, no subprocess, safe for SessionStart. Returns [] when there is nothing to
+    compare against (no plugin root, no vendored dir) — silence, not a complaint.
+    """
+    # The SessionStart hook passes ROOT as a str, not a Path. Coerce rather than assume — the
+    # first version of this function assumed Path and broke the hook's own regression test.
+    dest = Path(dest)
+    if _is_caddis_source(dest):
+        return []
+    root = plugin_root or (Path(os.environ["CLAUDE_PLUGIN_ROOT"])
+                           if os.environ.get("CLAUDE_PLUGIN_ROOT") else None)
+    if root is None:
+        return []
+    tools = dest / ".github" / "tools"
+    if not tools.is_dir():
+        return []
+    out: list[str] = []
+    for local in sorted(tools.glob("*.py")):
+        shipped = root / "scripts" / local.name
+        if not shipped.is_file():
+            continue
+        try:
+            if _norm(local.read_text(encoding="utf-8", errors="ignore")) != \
+               _norm(shipped.read_text(encoding="utf-8", errors="ignore")):
+                out.append(f".github/tools/{local.name} differs from the caddis copy — "
+                           "probably a stale vendor; delete it or keep the change deliberately")
+        except OSError:
+            continue
+    return out
+
+
+def _file_signals(dest: Path) -> list[str]:
+    """PURE FILE-CHECK signals only (no subprocess) — safe + fast for SessionStart. One line each."""
+    signals: list[str] = []
+    over = oversize_rules_files(dest)
+    if over:
+        worst = max(over, key=lambda x: x[1])
+        signals.append(oversize_message(worst[0], worst[1]))
+    dangling = docmap_dangling(dest)
+    if dangling:
+        signals.append(f"{len(dangling)} dangling DOC-MAP link(s) — run /caddis:kb")
+    days = days_since_last_doctor()
+    if days is not None and days >= 30:
+        signals.append(f"{days} days since last caddis doctor — run caddis-init --doctor")
+    # Listed LAST but it is the most dangerous signal here: the others degrade a session's quality,
+    # this one silently runs old code and reports success. It is cheap (a file compare) and almost
+    # always empty, so it costs nothing to carry.
+    signals += vendored_drift(dest)
+    return signals
+
+
+def maintenance_signals(dest: Path) -> list[str]:
+    """All deterministic signals (file checks + harness-version drift). For the full doctor report."""
+    return _file_signals(dest) + version_drift()
+
+
+def nudge_line(dest: Path) -> str | None:
+    """The single SessionStart nudge line, or None. PURE FILE CHECKS only (no subprocess, no LLM, no
+    auto-fix) so it never slows session start; curator/kb stay human-triggered."""
+    sig = _file_signals(dest)
+    if not sig:
+        return None
+    head = sig[0]
+    more = f" (+{len(sig) - 1} more — run caddis doctor)" if len(sig) > 1 else ""
+    return f"[caddis] {head}{more}"
+
+
+# ── report ───────────────────────────────────────────────────────────────────
+def run(dest: Path, quiet: bool) -> int:
+    if quiet:  # SessionStart mode: only the nudge, never non-zero
+        line = nudge_line(dest)
+        if line:
+            print(line)
+        return 0
+
+    hard = 0
+    print(f"=== caddis doctor — {dest} ===")
+    print(f"python: {sys.version.split()[0]}  ({sys.executable})")
+    for name in ("codex", "agy", "claude"):
+        path = _which(name)
+        if path:
+            ver = _binary_version(path) or "?"
+            print(f"  {name:7} OK   {ver}   [{path}]")
+        else:
+            print(f"  {name:7} not found on PATH (install, or open a new terminal so PATH refreshes)")
+
+    print("-- rules integrity")
+    findings = rules_findings(dest)
+    if findings:
+        hard = 1
+        for f in findings:
+            print(f"  FAIL {f}")
+    else:
+        root = dest / "AGENTS.md"
+        print(f"  OK   root AGENTS.md {'present' if root.is_file() else 'ABSENT (not migrated yet?)'}; shims are shims")
+
+    print("-- maintenance signals (deterministic — read-only)")
+    sig = maintenance_signals(dest)
+    if sig:
+        for s in sig:
+            print(f"  ~ {s}")
+    else:
+        print("  none")
+
+    print("-- install registry")
+    reg = _user_scope_path("installs.json")
+    if reg.is_file():
+        try:
+            installs = json.loads(reg.read_text(encoding="utf-8")).get("installs", [])
+            vers = {e.get("version") for e in installs}
+            print(f"  {len(installs)} install(s); versions: {sorted(v for v in vers if v)}"
+                  + ("  ⚠ skew" if len([v for v in vers if v]) > 1 else ""))
+        except Exception:
+            print("  (registry unreadable)")
+    else:
+        print("  no installs recorded")
+
+    _stamp_last_doctor()
+    print(f"\n{'FAIL — fix the above.' if hard else 'OK.'}")
+    return hard
+
+
+def main(argv: list[str] | None = None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(description="caddis health + maintenance report (read-only).")
+    ap.add_argument("--dest", default=".", help="Project dir whose rules to check (default: cwd).")
+    ap.add_argument("--quiet", action="store_true", help="Print only the one-line maintenance nudge (SessionStart).")
+    args = ap.parse_args(argv)
+    return run(Path(args.dest).resolve(), args.quiet)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())