@event4u/agent-config 1.19.0 → 1.20.0

package/scripts/check_references.py

@@ -33,8 +33,10 @@ class BrokenRef:
 
 SCAN_DIRS = [".agent-src", "agents"]
 SKIP_DIRS = [
-    "agents/roadmaps/archive",  # archived roadmaps have historical refs
-    "agents/council-sessions",  # per-user audit trail (gitignored), captured provider output
+    "agents/roadmaps/archive",   # archived roadmaps have historical refs
+    "agents/council-sessions",   # per-user audit trail (gitignored), captured provider output
+    "agents/council-questions",  # design Q&A trail — forward-refs to planned artifacts
+    "agents/analysis",           # plate-comparison working docs — forward-refs to planned artifacts
 ]
 ROOT = Path(".")
 
@@ -280,6 +282,14 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
                 # checkable file paths.
                 if not resolved and raw_ref.startswith("agents/state/"):
                     resolved = True
+                # `agents/.agent-prices.md` is a runtime-bootstrapped pricing
+                # cache — gitignored (.gitignore:/agents/.agent-prices.md),
+                # auto-generated by scripts/ai_council/pricing.py from
+                # _default_prices.py if missing. Same class as agents/state/*
+                # but a single named file, not a directory pattern, so the
+                # carve-out stays narrow.
+                if not resolved and raw_ref == "agents/.agent-prices.md":
+                    resolved = True
             if not resolved:
                 broken.append(BrokenRef(
                     file=str(filepath), line=i, ref=m.group(1),

package/scripts/council_cli.py

@@ -62,12 +62,17 @@ def build_members(
     settings: dict[str, Any],
     *,
     invocation_mode: str | None = None,
+    model_overrides: dict[str, str] | None = None,
 ) -> list[ExternalAIClient]:
     """Construct enabled council members from settings.
 
     Honours `ai_council.enabled` (master switch) and per-member
     `enabled` flags. Raises `CouncilDisabledError` when the council is
     off or no member is wired up.
+
+    `model_overrides` is a per-invocation `{member_name: model_id}`
+    map that wins over the per-member `model` in settings. Members not
+    listed fall back to the settings value, then the per-client default.
     """
     ai = (settings.get("ai_council") or {}) if isinstance(settings, dict) else {}
     if not ai.get("enabled"):
@@ -77,6 +82,13 @@ def build_members(
         )
     members_cfg = ai.get("members") or {}
     global_mode = ai.get("mode")
+    overrides = model_overrides or {}
+    unknown = set(overrides) - set(members_cfg)
+    if unknown:
+        raise CouncilDisabledError(
+            f"--model targets unknown member(s) {sorted(unknown)!r}; "
+            f"known members: {sorted(members_cfg)!r}."
+        )
     members: list[ExternalAIClient] = []
     for name, cfg in members_cfg.items():
         cfg = cfg or {}
@@ -88,7 +100,7 @@ def build_members(
             member_settings=cfg,
             global_mode=global_mode,
         )
-        model = cfg.get("model")
+        model = overrides.get(name) or cfg.get("model")
         if mode == "api" and name == "anthropic":
             members.append(AnthropicClient(model=model or "claude-sonnet-4-5",
                                            api_key=load_anthropic_key()))
@@ -163,7 +175,11 @@ def cmd_estimate(
     if settings is None:
         settings = load_settings()
     if members is None:
-        members = build_members(settings, invocation_mode=args.mode_override)
+        members = build_members(
+            settings,
+            invocation_mode=args.mode_override,
+            model_overrides=_parse_model_overrides(getattr(args, "model", None)),
+        )
     if table is None:
         table = load_prices()
     question, _ = build_question(
@@ -219,7 +235,11 @@ def cmd_run(
     if settings is None:
         settings = load_settings()
     if members is None:
-        members = build_members(settings, invocation_mode=args.mode_override)
+        members = build_members(
+            settings,
+            invocation_mode=args.mode_override,
+            model_overrides=_parse_model_overrides(getattr(args, "model", None)),
+        )
     if table is None:
         table = load_prices()
     question, artefact = build_question(
@@ -295,6 +315,28 @@ def cmd_render(args: argparse.Namespace) -> int:
 # ── argparse + main ─────────────────────────────────────────────────
 
 
+def _parse_model_overrides(items: list[str] | None) -> dict[str, str]:
+    """Parse repeated `--model name=model-id` flags into a dict.
+
+    Empty/None list → empty dict (no override). Bad shape raises
+    `argparse.ArgumentTypeError` so the CLI surfaces the error.
+    """
+    out: dict[str, str] = {}
+    for raw in items or []:
+        if "=" not in raw:
+            raise argparse.ArgumentTypeError(
+                f"--model expects '<member>=<model-id>', got {raw!r}."
+            )
+        name, model = raw.split("=", 1)
+        name, model = name.strip(), model.strip()
+        if not name or not model:
+            raise argparse.ArgumentTypeError(
+                f"--model member and model-id must both be non-empty: {raw!r}."
+            )
+        out[name] = model
+    return out
+
+
 def _add_common_input_args(p: argparse.ArgumentParser) -> None:
     p.add_argument("question", type=str,
                    help="Path to the question file (text or roadmap).")
@@ -305,6 +347,13 @@ def _add_common_input_args(p: argparse.ArgumentParser) -> None:
                    help="Per-member output budget (default: 1024).")
     p.add_argument("--mode-override", choices=["api", "manual"], default=None,
                    help="Override every member's transport mode.")
+    p.add_argument("--model", action="append", default=None, dest="model",
+                   metavar="MEMBER=MODEL_ID",
+                   help="Per-invocation model override, e.g. "
+                        "--model anthropic=claude-sonnet-4-5. Repeatable. "
+                        "Wins over `ai_council.members.<name>.model` in "
+                        ".agent-settings.yml; the settings file is not "
+                        "modified.")
     p.add_argument("--original-ask", default="",
                    help="The user's framing sentence (flows into handoff).")
 
@@ -347,7 +396,8 @@ def main(argv: list[str] | None = None) -> int:
     except CouncilDisabledError as exc:
         sys.stderr.write(f"❌  council:{args.cmd}: {exc}\n")
         return 2
-    except (BundleTooLarge, InvalidModeError, FileNotFoundError) as exc:
+    except (BundleTooLarge, InvalidModeError, FileNotFoundError,
+            argparse.ArgumentTypeError) as exc:
         sys.stderr.write(f"❌  council:{args.cmd}: {exc}\n")
         return 2
     return 1

package/scripts/hook_manifest.yaml

@@ -60,6 +60,27 @@ platforms:
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
 
+  # Cowork — the Claude desktop app's local-agent-mode runtime, built
+  # on top of the Claude Code CLI. Same lifecycle vocabulary, same
+  # event-payload shape (PascalCase native names; Stop carries
+  # `transcript_path`). Listed as a separate platform so chat-history
+  # entries can attribute events to Cowork vs CLI Claude Code via the
+  # `agent` field.
+  #
+  # Upstream caveat (anthropics/claude-code#40495, #27398): Cowork
+  # sessions currently ignore all three Claude Code settings sources
+  # (user, project, env), and `--setting-sources user` excludes
+  # plugin-scope hooks. Until those land, the dispatcher binding
+  # below is structurally ready but lifecycle events do not fire.
+  # Decision matrix + upstream blockers tracked in
+  # agents/contexts/chat-history-platform-hooks.md § Cowork.
+  cowork:
+    session_start:    [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_end:      [chat-history]
+    stop:             [chat-history, verify-before-complete]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
+
   # Phase 7.5 — Cursor. `.cursor/hooks.json` (project) is read by the
   # IDE and CLI; `~/.cursor/hooks.json` (user) is opt-in via
   # `install.py --cursor-user-hooks` and uses scripts/hooks/cursor-dispatcher.sh
@@ -146,6 +167,18 @@ native_event_aliases:
     PostToolUse:       post_tool_use
     PreToolUse:        pre_tool_use
     PreCompact:        pre_compact
+  # Cowork shares Claude Code's PascalCase event vocabulary verbatim
+  # (Cowork is Claude Code under the hood). Native names are duplicated
+  # here rather than aliased so dispatcher logs / feedback carry the
+  # platform tag the operator expects.
+  cowork:
+    SessionStart:      session_start
+    SessionEnd:        session_end
+    Stop:              stop
+    UserPromptSubmit:  user_prompt_submit
+    PostToolUse:       post_tool_use
+    PreToolUse:        pre_tool_use
+    PreCompact:        pre_compact
   cursor:
     sessionStart:        session_start
     sessionEnd:          session_end

package/scripts/hooks/augment-chat-history.sh

@@ -21,6 +21,16 @@ set -u
 
 EVENT_DATA="$(cat)"
 
+# Debug-only: when ~/.augment/.chat-history-debug exists, dump the raw
+# stdin payload for offline inspection. No-op otherwise. Used to probe
+# what Augment's hook events actually carry.
+if [ -f "$HOME/.augment/.chat-history-debug" ]; then
+    DUMP_DIR="$HOME/.augment/chat-history-debug"
+    mkdir -p "$DUMP_DIR" 2>/dev/null
+    printf '%s' "$EVENT_DATA" \
+        > "$DUMP_DIR/event-$(date +%Y%m%d-%H%M%S)-$$.json" 2>/dev/null || true
+fi
+
 # Extract workspace_roots[0] using whichever JSON tool is available.
 WORKSPACE=""
 if command -v jq >/dev/null 2>&1; then

package/scripts/hooks/cowork-dispatcher.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Cowork universal hook trampoline.
+#
+# Cowork is the Claude desktop app's local-agent-mode runtime. It runs
+# the Claude Code CLI inside a sandbox VM, so hook events use the
+# Claude Code shape (PascalCase native names; Stop carries
+# `transcript_path`). The payload typically carries `cwd` (Claude
+# Code's standard field) rather than Augment's `workspace_roots[0]`.
+# We accept either, falling back through both.
+#
+# Upstream caveat: as of writing this trampoline, lifecycle events do
+# not actually fire from Cowork sessions —
+# anthropics/claude-code#40495 reports all three Claude Code settings
+# sources (user, project, env) are ignored inside Cowork's sandbox,
+# and #27398 reports plugin-scope `hooks/hooks.json` is excluded
+# because Cowork spawns the CLI with `--setting-sources user`. The
+# trampoline is structurally ready; install plumbing is deferred
+# until upstream resolves the bugs and a stable settings location is
+# documented. See `agents/contexts/chat-history-platform-hooks.md`
+# § Cowork.
+#
+# Behaviour mirrors cursor-dispatcher.sh:
+#   - Read JSON event from stdin into a buffer.
+#   - Extract cwd (Claude Code) or workspace_roots[0] (fallback);
+#     bail silently when neither resolves to a directory.
+#   - cd into that workspace; bail silently when it lacks ./agent-config.
+#   - Re-pipe the original JSON into
+#       ./agent-config dispatch:hook --platform cowork \
+#           --event $1 --native-event $2
+#   - Always exit 0 — chat-history must never block the agent loop.
+
+set -u
+
+# Args from the platform's hooks config (whatever shape Cowork ends up
+# using once upstream lands the fix):
+#   $1 = agent-config event name (session_start, post_tool_use, …)
+#   $2 = Cowork-native event name (SessionStart, PostToolUse, …)
+EVENT="${1-}"
+NATIVE_EVENT="${2-}"
+
+if [ -z "$EVENT" ]; then
+    exit 0
+fi
+
+EVENT_DATA="$(cat)"
+
+# Debug-only: when ~/.claude/.cowork-chat-history-debug exists, dump
+# the raw stdin payload for offline inspection. No-op otherwise.
+# Useful once upstream fixes #40495 to verify the actual payload shape.
+if [ -f "$HOME/.claude/.cowork-chat-history-debug" ]; then
+    DUMP_DIR="$HOME/.claude/cowork-chat-history-debug"
+    mkdir -p "$DUMP_DIR" 2>/dev/null
+    printf '%s' "$EVENT_DATA" \
+        > "$DUMP_DIR/event-$(date +%Y%m%d-%H%M%S)-$$.json" 2>/dev/null || true
+fi
+
+# Extract workspace path. Try Claude Code's `cwd` first, then fall
+# back to Augment-style `workspace_roots[0]`. Either is acceptable —
+# we need a directory containing ./agent-config.
+WORKSPACE=""
+if command -v jq >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" \
+        | jq -r '.cwd // .workspace_roots[0] // empty' 2>/dev/null)"
+elif command -v python3 >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+cwd = data.get("cwd")
+if isinstance(cwd, str) and cwd:
+    print(cwd)
+    sys.exit(0)
+roots = data.get("workspace_roots") or []
+if roots:
+    print(roots[0])
+' 2>/dev/null)"
+fi
+
+if [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE" ]; then
+    exit 0
+fi
+
+cd "$WORKSPACE" 2>/dev/null || exit 0
+
+if [ ! -x ./agent-config ]; then
+    exit 0
+fi
+
+printf '%s' "$EVENT_DATA" \
+    | ./agent-config dispatch:hook \
+        --platform cowork \
+        --event "$EVENT" \
+        --native-event "$NATIVE_EVENT" \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/hooks/dispatch_hook.py

@@ -167,6 +167,40 @@ def _resolve_concerns(manifest: dict, platform: str, event: str) -> list[dict]:
     return out
 
 
+def _maybe_capture_payload(args: argparse.Namespace, payload_text: str) -> None:
+    """Write the raw stdin payload to a capture directory when
+    ``AGENT_HOOK_CAPTURE_DIR`` is set. Used by the verified-platforms
+    discovery roadmap (`agents/roadmaps/road-to-verified-chat-history-platforms.md`)
+    to lock real payload shapes before extractor branches are added.
+
+    Fail-silent: any IO / JSON error must not break dispatch.
+    """
+    capture_dir = os.environ.get("AGENT_HOOK_CAPTURE_DIR", "").strip()
+    if not capture_dir:
+        return
+    try:
+        target = Path(capture_dir).expanduser()
+        target.mkdir(parents=True, exist_ok=True)
+        try:
+            payload = json.loads(payload_text) if payload_text.strip() else {}
+        except (ValueError, TypeError):
+            payload = {"_raw_text": payload_text}
+        record = {
+            "captured_at": _now_iso(),
+            "platform": args.platform,
+            "event": args.event,
+            "native_event": args.native_event or "",
+            "raw_payload": payload,
+        }
+        ts = int(time.time() * 1000)
+        native = (args.native_event or args.event).replace("/", "_")
+        fname = f"{args.platform}__{native}__{ts}__{os.getpid()}.json"
+        (target / fname).write_text(
+            json.dumps(record, indent=2) + "\n", encoding="utf-8")
+    except OSError:
+        return
+
+
 def _build_envelope(args: argparse.Namespace, payload_text: str) -> dict:
     try:
         payload = json.loads(payload_text) if payload_text.strip() else {}
@@ -298,6 +332,7 @@ def main(argv: list[str] | None = None) -> int:
     manifest = _load_yaml(manifest_path)
 
     payload_text = "" if sys.stdin.isatty() else sys.stdin.read()
+    _maybe_capture_payload(args, payload_text)
     concerns = _resolve_concerns(manifest, args.platform, args.event)
 
     if args.dry_run:

package/scripts/hooks_status.py

@@ -25,9 +25,20 @@ import dispatch_hook  # noqa: E402  — reuse the manifest loader
 
 # (label, project-relative bridge path, install hint).
 # Path may be a directory (cline) — existence => any file inside.
+#
+# Cowork has no project-scope bridge path: the Claude desktop app's
+# local-agent-mode runtime is upstream-blocked from reading any of
+# Claude Code's three settings sources (anthropics/claude-code#40495,
+# #27398). We register cowork here so the manifest's `cowork:`
+# bindings are surfaced in the status report, but the empty bridge
+# path resolves to status="n/a" — strict mode does not fail on
+# n/a (see _final_exit_code), matching Copilot's no-bridge posture.
+# Once upstream lands the fix and a stable settings location is
+# documented, swap the empty path here for that location.
 PLATFORM_BRIDGES: dict[str, tuple[str, str]] = {
     "augment":  (".augment/settings.json",      "scripts/install.py"),
     "claude":   (".claude/settings.json",       "scripts/install.py"),
+    "cowork":   ("",                            "upstream-blocked: anthropics/claude-code#40495 + #27398 (settings.json ignored in Cowork sandbox)"),
     "cursor":   (".cursor/hooks.json",          "scripts/install.py"),
     "cline":    (".clinerules/hooks",           "scripts/install.py"),
     "windsurf": (".windsurf/hooks.json",        "scripts/install.py"),
@@ -65,7 +76,7 @@ def collect(project_root: Path, manifest: dict) -> dict:
             "bridge_path": rel or None,
             "fallback_only": fallback_only,
             "bindings": bindings,
-            "hint": hint if status in {"missing", "empty", "degraded"} else None,
+            "hint": hint if status in {"missing", "empty", "degraded", "n/a"} else None,
         })
     return {"schema_version": 1, "platforms": rows}
 

package/scripts/install-hooks.sh

@@ -63,7 +63,7 @@ echo "✅  Pre-commit hook installed."
 # lifecycle hooks) cannot fire SessionStart/Stop/PostToolUse. Git hooks
 # are the platform-agnostic lifecycle surface that fires regardless of
 # IDE — every commit, merge, checkout, and rewrite turns into a phase
-# boundary in .agent-chat-history when an agent session is active.
+# boundary in agents/.agent-chat-history when an agent session is active.
 #
 # The hooks are silent no-ops when no agent session is active (the
 # chat_history.py hook-append script returns "skipped_no_sidecar" with
@@ -75,7 +75,7 @@ write_chat_history_hook() {
     local phase_tag="$2"
     cat > "$HOOKS_DIR/$name" << EOF
 #!/usr/bin/env bash
-# $name: append a phase boundary to .agent-chat-history when an agent
+# $name: append a phase boundary to agents/.agent-chat-history when an agent
 # session is active. Silent no-op otherwise. Never blocks git.
 
 if [ -x ./agent-config ]; then

package/scripts/install.sh

@@ -563,6 +563,40 @@ copy_if_missing() {
     cp "$source" "$target"
 }
 
+# Migrate legacy infra files from project root to agents/.
+# Pre-2.x layout: .agent-chat-history (+ .bak), .agent-prices.md lived at
+# the project root. They now live under agents/. Move them in place before
+# any other content sync so the updated gitignore block (which lists
+# /agents/.agent-chat-history*) and the chat-history hooks operate on the
+# already-migrated layout. Idempotent: skips silently if the target already
+# exists; never overwrites.
+migrate_legacy_root_infra() {
+    local project_root="$1"
+    local agents_dir="$project_root/agents"
+    local items=(".agent-chat-history" ".agent-chat-history.bak" ".agent-prices.md")
+
+    for name in "${items[@]}"; do
+        local old="$project_root/$name"
+        local new="$agents_dir/$name"
+
+        [[ -e "$old" ]] || continue
+
+        if [[ -e "$new" ]]; then
+            log_warn "Legacy $name found at project root, but agents/$name already exists — leaving root copy in place"
+            continue
+        fi
+
+        if $DRY_RUN; then
+            log_verbose "would migrate $name → agents/$name"
+            continue
+        fi
+
+        mkdir -p "$agents_dir"
+        mv "$old" "$new"
+        log_info "Migrated $name → agents/$name"
+    done
+}
+
 # Ensure .gitignore contains the managed agent-config block.
 # Delegates to scripts/sync_gitignore.py so the installer and the
 # standalone /sync-gitignore command share one source of truth
@@ -632,6 +666,9 @@ main() {
     $DRY_RUN && ! $QUIET && echo "    Mode: DRY RUN"
     echo ""
 
+    # 0. Migrate legacy infra files (root → agents/) before any content sync.
+    migrate_legacy_root_infra "$TARGET_DIR"
+
     # 1. Hybrid sync payload → target/.augment/
     sync_hybrid "$SOURCE_PAYLOAD" "$TARGET_DIR/.augment"
     log_info "Synced .augment/ (rules copied, rest symlinked)"

package/scripts/lint_handoffs.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Lint cross-wing handoffs declared in senior-tier skills' ``## Related Skills`` blocks.
+
+Builds a directed graph from every ``tier: senior`` skill's Related Skills
+block (markdown links pointing at peer ``SKILL.md`` files), then enforces
+the rules from ``docs/contracts/cross-wing-handoff.md`` § 4:
+
+  handoff_cycle           — graph must be a DAG.
+  handoff_dangling        — every linked target must exist.
+  handoff_tier_mismatch   — senior may delegate only to senior.
+
+Hooked into ``task lint-handoffs`` and ``task ci`` (between ``lint-skills``
+and ``test``). Output mirrors ``scripts/skill_linter.py``: ``file:line:reason``.
+
+Exit codes:
+  0  no violations
+  1  one or more violations
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+REPO = Path(__file__).resolve().parents[1]
+SKILLS_DIR = REPO / ".agent-src.uncompressed" / "skills"
+
+LINK_RE = re.compile(r"\[`?([a-z0-9][a-z0-9-]*)`?\]\(([^)]+SKILL\.md)\)")
+RELATED_HEADING_RE = re.compile(r"^##\s+Related\s+Skills\s*$", re.IGNORECASE)
+NEXT_HEADING_RE = re.compile(r"^##\s+\S")
+WHEN_USE_RE = re.compile(r"^\*\*WHEN\s+to\s+use\s+this\*\*\s*$", re.IGNORECASE)
+WHEN_NOT_RE = re.compile(r"^\*\*WHEN\s+NOT\s+to\s+use\s+this\*\*\s*$", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class Violation:
+    file: Path
+    line: int
+    code: str
+    message: str
+
+    def render(self, repo: Path) -> str:
+        rel = self.file.relative_to(repo) if self.file.is_absolute() else self.file
+        return f"{rel}:{self.line}:{self.code}: {self.message}"
+
+
+def parse_frontmatter_tier(text: str) -> str | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    for raw in text[4:end].splitlines():
+        if ":" not in raw:
+            continue
+        key, _, val = raw.partition(":")
+        if key.strip() == "tier":
+            return val.strip().strip('"').strip("'")
+    return None
+
+
+def extract_related_block(text: str) -> tuple[int, list[tuple[int, str]]] | None:
+    """Return (block_start_line, [(line, raw_line), ...]) for ``## Related Skills``."""
+    lines = text.splitlines()
+    start: int | None = None
+    for idx, line in enumerate(lines):
+        if RELATED_HEADING_RE.match(line):
+            start = idx
+            break
+    if start is None:
+        return None
+    body: list[tuple[int, str]] = []
+    for idx in range(start + 1, len(lines)):
+        if NEXT_HEADING_RE.match(lines[idx]):
+            break
+        body.append((idx + 1, lines[idx]))
+    return start + 1, body
+
+
+def split_when_subblocks(body: list[tuple[int, str]]) -> tuple[
+    list[tuple[int, str]], list[tuple[int, str]]
+]:
+    """Split a ``## Related Skills`` body into (when_to_use, when_not_to_use).
+
+    WHEN-to-use links are composition (delegation) edges — graph for cycles.
+    WHEN-NOT-to-use links are alternative pointers (peer cognition the user
+    picks instead) — never composition edges. Lines outside both sub-blocks
+    are treated as WHEN-to-use for backward compatibility.
+    """
+    when_use: list[tuple[int, str]] = []
+    when_not: list[tuple[int, str]] = []
+    current = when_use
+    for lineno, raw in body:
+        if WHEN_USE_RE.match(raw):
+            current = when_use
+            continue
+        if WHEN_NOT_RE.match(raw):
+            current = when_not
+            continue
+        current.append((lineno, raw))
+    return when_use, when_not
+
+
+def extract_links(body: list[tuple[int, str]]) -> list[tuple[int, str, str]]:
+    """Yield ``(line, slug, target_path)`` for every markdown link in the block."""
+    out: list[tuple[int, str, str]] = []
+    for lineno, raw in body:
+        for match in LINK_RE.finditer(raw):
+            out.append((lineno, match.group(1), match.group(2)))
+    return out
+
+
+def resolve_target(skill_file: Path, link: str) -> Path:
+    return (skill_file.parent / link).resolve()
+
+
+def detect_cycles(graph: dict[Path, set[Path]]) -> list[list[Path]]:
+    cycles: list[list[Path]] = []
+    visited: set[Path] = set()
+    stack: list[Path] = []
+    on_stack: set[Path] = set()
+
+    def dfs(node: Path) -> None:
+        if node in on_stack:
+            i = stack.index(node)
+            cycles.append(stack[i:] + [node])
+            return
+        if node in visited:
+            return
+        visited.add(node)
+        on_stack.add(node)
+        stack.append(node)
+        for nxt in graph.get(node, ()):
+            dfs(nxt)
+        stack.pop()
+        on_stack.discard(node)
+
+    for node in list(graph):
+        dfs(node)
+    return cycles
+
+
+def lint(skills_dir: Path) -> list[Violation]:
+    senior_skills: dict[Path, str] = {}
+    all_skills: dict[Path, str] = {}
+    for skill_md in sorted(skills_dir.rglob("SKILL.md")):
+        text = skill_md.read_text(encoding="utf-8")
+        tier = parse_frontmatter_tier(text)
+        all_skills[skill_md.resolve()] = tier or ""
+        if tier == "senior":
+            senior_skills[skill_md.resolve()] = text
+
+    violations: list[Violation] = []
+    graph: dict[Path, set[Path]] = {}
+
+    for skill_path, text in senior_skills.items():
+        block = extract_related_block(text)
+        if block is None:
+            continue
+        _, body = block
+        when_use, when_not = split_when_subblocks(body)
+
+        # WHEN-to-use links: composition edges (graph) + dangling/tier checks.
+        for lineno, slug, link in extract_links(when_use):
+            target = resolve_target(skill_path, link)
+            graph.setdefault(skill_path, set()).add(target)
+            if target not in all_skills:
+                violations.append(Violation(skill_path, lineno, "handoff_dangling",
+                    f"link to `{slug}` resolves to missing file {link}"))
+                continue
+            if all_skills[target] != "senior":
+                violations.append(Violation(skill_path, lineno, "handoff_tier_mismatch",
+                    f"senior skill links to non-senior `{slug}` "
+                    f"(tier={all_skills[target] or 'unset'!r})"))
+
+        # WHEN-NOT-to-use links: alternative pointers, NOT composition edges.
+        # Dangling + tier-mismatch still apply (a broken alternative is wrong);
+        # cycles do not (mutual "use X instead" pointers are intentional).
+        for lineno, slug, link in extract_links(when_not):
+            target = resolve_target(skill_path, link)
+            if target not in all_skills:
+                violations.append(Violation(skill_path, lineno, "handoff_dangling",
+                    f"link to `{slug}` resolves to missing file {link}"))
+                continue
+            if all_skills[target] != "senior":
+                violations.append(Violation(skill_path, lineno, "handoff_tier_mismatch",
+                    f"senior skill links to non-senior `{slug}` "
+                    f"(tier={all_skills[target] or 'unset'!r})"))
+
+    for cycle in detect_cycles(graph):
+        names = " → ".join(p.parent.name for p in cycle)
+        violations.append(Violation(cycle[0], 1, "handoff_cycle",
+            f"composition cycle: {names}"))
+    return violations
+
+
+def main(argv: list[str] | None = None) -> int:
+    skills_dir = SKILLS_DIR
+    if argv:
+        skills_dir = Path(argv[0]).resolve()
+    violations = lint(skills_dir)
+    if not violations:
+        print(f"✅  lint_handoffs: no violations under {skills_dir.relative_to(REPO)}")
+        return 0
+    for v in violations:
+        print(v.render(REPO))
+    print(f"\n❌  lint_handoffs: {len(violations)} violation(s)", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))