@event4u/agent-config 5.3.0 → 5.4.1

package/scripts/condense.py

@@ -876,8 +876,72 @@ def _iter_commands():
         yield source_file, _command_slug(source_file)
 
 
+# --- Per-skill model auto-switch (ADR-035 / road-to-model-capability-tiers) ---
+
+# The SINGLE generator-owned tier→Claude-model mapping (ADR-035 § 3). Claude
+# Code is the only surface that consumes a native `model:`, so this is the only
+# place a capability tier resolves to a concrete model. `inherit`/absent emit
+# nothing and stay pure symlinks. Non-Claude agents never get a per-vendor
+# table — the rule surfaces the tier name as a suggestion.
+_TIER_TO_CLAUDE_MODEL = {"high": "opus", "medium": "sonnet", "lite": "haiku"}
+_MODEL_TIER_RE = re.compile(r'^model_tier:\s*"?([a-z]+)"?\s*$', re.MULTILINE)
+
+
+def _read_model_auto_switch() -> str:
+    """Read `model.auto_switch` from .agent-settings.yml.
+
+    Returns `auto` | `suggest` | `off`; default `suggest`. Only `auto` makes
+    the generator emit a native Claude `model:` key (ADR-034 § 4) — `suggest`
+    and `off` keep skills/commands as pure symlinks so the package never
+    silently overrides a user's explicit `/model` choice.
+    """
+    try:
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+    data = load_agent_settings(project_path=SETTINGS_FILE)
+    model = data.get("model")
+    value = model.get("auto_switch") if isinstance(model, dict) else None
+    if isinstance(value, str) and value.strip().lower() in ("auto", "suggest", "off"):
+        return value.strip().lower()
+    return "suggest"
+
+
+def _model_tier(skill_md: Path) -> str | None:
+    """Return the `model_tier` frontmatter value, or None if absent."""
+    if not skill_md.exists():
+        return None
+    text = skill_md.read_text(encoding="utf-8", errors="replace")
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    m = _MODEL_TIER_RE.search(text[4:end])
+    return m.group(1) if m else None
+
+
+def _render_native_model_md(src_md: Path, tier: str) -> str:
+    """Rewrite the source `model_tier: <tier>` line to a native Claude
+    `model: <mapped>` key via the generator-owned mapping (ADR-035 § 3). The
+    rest of the SKILL.md is byte-identical."""
+    text = src_md.read_text(encoding="utf-8")
+    model = _TIER_TO_CLAUDE_MODEL[tier]
+    return _MODEL_TIER_RE.sub(f"model: {model}", text, count=1)
+
+
 def generate_claude_skills() -> int:
-    """Create .claude/skills/ symlinks for ALL skills in .agent-src/skills/.
+    """Create .claude/skills/ entries for ALL skills in .agent-src/skills/.
+
+    Default: a directory symlink → .agent-src/skills/<name> (verbatim).
+    When `model.auto_switch: auto` AND a skill declares
+    `model_tier: lite|medium|high`, the entry becomes a real directory whose
+    sub-files are symlinked but whose SKILL.md is a rendered copy carrying a
+    native Claude `model:` key (ADR-034 Option (b) — only model-bearing skills
+    break the symlink). Idempotent: each entry is rebuilt from scratch.
     """
     if not SKILLS_SOURCE.exists():
         print("  ⚠️  .agent-src/skills/ not found — skipping skills", file=sys.stderr)
@@ -885,26 +949,58 @@ def generate_claude_skills() -> int:
 
     # All skill directories in .agent-src/skills/
     skills = sorted([d.name for d in SKILLS_SOURCE.iterdir() if d.is_dir()])
+    skill_set = set(skills)
     # All command slugs (to protect from stale cleanup)
     command_slugs = {slug for _, slug in _iter_commands()}
 
     CLAUDE_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+    auto = _read_model_auto_switch() == "auto"
 
-    # Clean stale symlinks (but not converted commands or README)
+    # Clean stale entries (symlinks AND rendered skill dirs) — but never touch
+    # command dirs (real dir whose SKILL.md is a symlink) or the README.
     for item in CLAUDE_SKILLS_DIR.iterdir():
-        if item.is_symlink() and item.name not in skills and item.name not in command_slugs and item.name != "README.md":
+        if item.name in skill_set or item.name in command_slugs or item.name == "README.md":
+            continue
+        if item.is_symlink():
             item.unlink()
+        elif item.is_dir():
+            skill_md = item / "SKILL.md"
+            # A rendered skill dir has a *real* SKILL.md copy; a command dir has
+            # a SKILL.md *symlink* (left for generate_claude_commands to manage).
+            if skill_md.is_file() and not skill_md.is_symlink():
+                shutil.rmtree(item)
 
     count = 0
+    rendered = 0
     for skill in skills:
         link = CLAUDE_SKILLS_DIR / skill
-        if link.exists() or link.is_symlink():
+        src_dir = SKILLS_SOURCE / skill
+        value = _model_tier(src_dir / "SKILL.md") if auto else None
+        # Rebuild from scratch for idempotency (symlink ↔ rendered-dir flips).
+        if link.is_symlink():
             link.unlink()
-        rel_target = Path("../../.agent-src/skills") / skill
-        link.symlink_to(rel_target)
+        elif link.is_dir():
+            shutil.rmtree(link)
+        elif link.exists():
+            link.unlink()
+        if value in _TIER_TO_CLAUDE_MODEL:
+            link.mkdir(parents=True)
+            for entry in sorted(src_dir.iterdir()):
+                if entry.name == "SKILL.md":
+                    (link / "SKILL.md").write_text(
+                        _render_native_model_md(entry, value), encoding="utf-8"
+                    )
+                else:
+                    (link / entry.name).symlink_to(
+                        Path("../../../.agent-src/skills") / skill / entry.name
+                    )
+            rendered += 1
+        else:
+            link.symlink_to(Path("../../.agent-src/skills") / skill)
         count += 1
 
-    info(f"  ✅  Created {count} skill symlinks in .claude/skills/")
+    suffix = f" ({rendered} rendered with native model:)" if rendered else ""
+    info(f"  ✅  Created {count} skill entries in .claude/skills/{suffix}")
     return count
 
 
@@ -945,6 +1041,8 @@ def generate_claude_commands() -> int:
     current_slugs: set[str] = set()
     count = 0
     skipped = 0
+    rendered = 0
+    auto = _read_model_auto_switch() == "auto"
     for source_file, slug in _iter_commands():
         # Skip if a real skill with the same name exists — skill takes priority
         if slug in skill_names:
@@ -953,7 +1051,7 @@ def generate_claude_commands() -> int:
 
         current_slugs.add(slug)
 
-        # Create skill directory (real dir, symlinked SKILL.md inside)
+        # Create skill directory (real dir, SKILL.md symlinked or rendered)
         skill_dir = CLAUDE_SKILLS_DIR / slug
         skill_dir.mkdir(parents=True, exist_ok=True)
 
@@ -961,10 +1059,18 @@ def generate_claude_commands() -> int:
         if skill_file.exists() or skill_file.is_symlink():
             skill_file.unlink()
 
-        # Symlink: .claude/skills/{slug}/SKILL.md → ../../../.agent-src/commands/<rel-path>
         rel_path = source_file.relative_to(COMMANDS_SOURCE)
-        rel_target = Path("../../../.agent-src/commands") / rel_path
-        skill_file.symlink_to(rel_target)
+        value = _model_tier(source_file) if auto else None
+        if value in _TIER_TO_CLAUDE_MODEL:
+            # Render a copy carrying the native Claude model: key (ADR-034).
+            skill_file.write_text(
+                _render_native_model_md(source_file, value), encoding="utf-8"
+            )
+            rendered += 1
+        else:
+            # Symlink: .claude/skills/{slug}/SKILL.md → ../../../.agent-src/commands/<rel-path>
+            rel_target = Path("../../../.agent-src/commands") / rel_path
+            skill_file.symlink_to(rel_target)
         count += 1
 
     # Clean stale command skill directories — real dirs from removed commands.
@@ -976,14 +1082,20 @@ def generate_claude_commands() -> int:
         if item.name in skill_names or item.name in current_slugs:
             continue
         skill_md = item / "SKILL.md"
-        if skill_md.is_symlink():
+        # Stale command dir = exactly one SKILL.md, either symlinked (default)
+        # or a rendered copy (native-model command, ADR-034). Skill-render dirs
+        # are protected above (item.name in skill_names) and via the skills
+        # generator, so this only reaps removed commands.
+        if skill_md.is_symlink() or skill_md.is_file():
             entries = list(item.iterdir())
             if len(entries) == 1 and entries[0].name == "SKILL.md":
                 skill_md.unlink()
                 item.rmdir()
                 removed_dirs += 1
 
-    msg = f"  ✅  Created {count} command symlinks in .claude/skills/"
+    msg = f"  ✅  Created {count} command entries in .claude/skills/"
+    if rendered:
+        msg += f" ({rendered} rendered with native model:)"
     if skipped:
         msg += f" ({skipped} skipped — same-name skill exists)"
     if removed_dirs:
@@ -1080,8 +1192,12 @@ def generate_plugin_hooks() -> int:
     ``settings.local.json``. Claude Code merges plugin-scope and
     settings-scope hooks and dedups by command string.
 
-    The command is rooted at ``$CLAUDE_PROJECT_DIR`` so it resolves from
-    plugin scope regardless of cwd; the universal dispatcher then reads
+    The command resolves the binary project-local-first
+    (``$CLAUDE_PROJECT_DIR/agent-config`` when executable — maintainer dev-loop)
+    and falls back to ``agent-config`` on PATH (global-only consumer per
+    ADR-020, where the repo carries no wrapper). It always passes
+    ``--project-dir "$CLAUDE_PROJECT_DIR"`` so a globally resolved binary still
+    scans the project the event fired in. The universal dispatcher then reads
     ``scripts/hook_manifest.yaml`` at runtime to fan out to the active
     concerns (each a no-op when its feature is disabled).
     """
@@ -1092,6 +1208,7 @@ def generate_plugin_hooks() -> int:
         return 0
 
     manifest = yaml.safe_load(manifest_path.read_text(encoding="utf-8")) or {}
+    hook_spec = manifest.get("schema_version", 1)
     claude_events = manifest.get("platforms", {}).get("claude", {}) or {}
     aliases = manifest.get("native_event_aliases", {}).get("claude", {}) or {}
     # Reverse the native→agent-config map so we can emit native event names.
@@ -1104,9 +1221,17 @@ def generate_plugin_hooks() -> int:
         native = ac_to_native.get(ac_event)
         if native is None:
             continue
+        # Resolve the binary project-local-first, PATH-fallback: a maintainer
+        # dev-loop (or any repo carrying a project-local wrapper) uses its own
+        # ./agent-config; a global-only consumer (ADR-020 — nothing in the
+        # repo) falls back to the globally-installed `agent-config` on PATH.
+        # Either way pass --project-dir "$CLAUDE_PROJECT_DIR" so a globally
+        # resolved binary still scans the project the event fired in.
         command = (
-            '"$CLAUDE_PROJECT_DIR"/agent-config dispatch:hook '
-            f"--platform claude --event {ac_event} --native-event {native}"
+            'BIN="$CLAUDE_PROJECT_DIR/agent-config"; [ -x "$BIN" ] || BIN=agent-config; '
+            f'"$BIN" dispatch:hook --platform claude --event {ac_event} '
+            f'--native-event {native} --project-dir "$CLAUDE_PROJECT_DIR" '
+            f'--min-version {hook_spec}'
         )
         hooks[native] = [{"hooks": [{"type": "command", "command": command}]}]
 

package/scripts/hooks/dispatch_hook.py

@@ -349,8 +349,36 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--manifest", default=str(MANIFEST_PATH))
     parser.add_argument("--dry-run", action="store_true",
                         help="Resolve concerns and print plan; do not invoke them.")
+    parser.add_argument("--project-dir", default="",
+                        help="Project root the event fired in (the Claude "
+                             "plugin passes $CLAUDE_PROJECT_DIR). A globally "
+                             "resolved binary (ADR-020 global-only) has no "
+                             "implicit project context, so concerns are "
+                             "resolved relative to this directory.")
+    parser.add_argument("--min-version", type=int, default=0,
+                        help="Minimum hook-spec (manifest schema_version) the "
+                             "caller — typically the Claude marketplace plugin "
+                             "— was generated against. Plugin and binary update "
+                             "on independent cadences; when the binary's "
+                             "manifest is older than the plugin expects, warn "
+                             "(never block).")
     args = parser.parse_args(argv)
 
+    # Honour --project-dir: chdir so workspace_root (envelope) and every
+    # concern's cwd resolve consumer-local paths (agents/roadmaps/,
+    # agents/runtime/state/) against the project the event fired in, not the
+    # cwd a globally-installed binary happened to inherit. Fail loud (never
+    # block) when the path is bad — a wrong project root is a silent-no-op
+    # trap otherwise.
+    if args.project_dir:
+        project_dir = Path(args.project_dir).expanduser()
+        if project_dir.is_dir():
+            os.chdir(project_dir)
+        else:
+            sys.stderr.write(
+                f"dispatch_hook: --project-dir is not a directory: "
+                f"{project_dir} — resolving against cwd {Path.cwd()}\n")
+
     if args.event not in EVENT_VOCABULARY:
         sys.stderr.write(f"dispatch_hook: unknown event '{args.event}'; allowed: "
                          f"{sorted(EVENT_VOCABULARY)}\n")
@@ -362,6 +390,17 @@ def main(argv: list[str] | None = None) -> int:
         return EXIT_ALLOW
     manifest = _load_yaml(manifest_path)
 
+    # Plugin↔binary drift guard (never blocks). The Claude marketplace plugin
+    # embeds the hook-spec it was generated against; if this globally-installed
+    # binary carries an older manifest, surface a one-line upgrade hint.
+    if args.min_version:
+        local_spec = manifest.get("schema_version") or 0
+        if isinstance(local_spec, int) and local_spec < args.min_version:
+            sys.stderr.write(
+                f"dispatch_hook: plugin expects hook-spec >= {args.min_version} "
+                f"but this agent-config provides {local_spec}; "
+                f"run `agent-config upgrade`.\n")
+
     payload_text = "" if sys.stdin.isatty() else sys.stdin.read()
     _maybe_capture_payload(args, payload_text)
     concerns = _resolve_concerns(manifest, args.platform, args.event)

package/scripts/install

@@ -394,4 +394,18 @@ if ! $SKIP_BRIDGES; then
     run_bridges || RC=$?
 fi
 
+# Post-install PATH advisory. The Claude plugin hook resolves `agent-config`
+# from PATH on a global-only consumer (ADR-020); if it is unreachable every
+# PostToolUse hook silently no-ops — the documented "dashboard never updates"
+# failure. Advisory only: a bad PATH must not fail an otherwise-clean install.
+if [[ $RC -eq 0 ]] && ! command -v agent-config >/dev/null 2>&1; then
+    $QUIET || {
+        echo "  ⚠️   \`agent-config\` is not on your PATH." >&2
+        echo "      Claude plugin hooks resolve it from PATH; without it the" >&2
+        echo "      roadmap-progress dashboard (and other hooks) will not fire." >&2
+        echo "      Add your npm global bin dir (\`npm prefix -g\`/bin) to PATH," >&2
+        echo "      then verify with \`agent-config doctor\`." >&2
+    }
+fi
+
 exit $RC

package/scripts/lint_framework_leakage_allowlist.json

@@ -5,37 +5,37 @@
     {
       "file": ".agent-src.uncondensed/skills/module-detect-on-the-fly/SKILL.md",
       "lines": [
-        33,
-        95
+        34,
+        96
       ],
       "reason": "Cross-stack noise-segment enumeration (vendor + node_modules + dist/Modules) documenting the module-detection path filter"
     },
     {
       "file": ".agent-src.uncondensed/skills/using-git-worktrees/SKILL.md",
       "lines": [
-        133,
         134,
         135,
-        155
+        136,
+        156
       ],
       "reason": "Multi-stack package-manager comparison table"
     },
     {
       "file": ".agent-src.uncondensed/skills/refine-prompt/SKILL.md",
       "lines": [
-        91,
-        93,
-        95,
-        140,
-        183,
-        272
+        92,
+        94,
+        96,
+        141,
+        184,
+        273
       ],
       "reason": "Project-detection enumeration listing all supported stacks"
     },
     {
       "file": ".agent-src.uncondensed/commands/analyze-reference-repo.md",
       "lines": [
-        53
+        54
       ],
       "reason": "Manifest-file enumeration across ecosystems"
     },
@@ -77,51 +77,51 @@
     {
       "file": ".agent-src.uncondensed/skills/api-endpoint/SKILL.md",
       "lines": [
-        44,
-        61
+        45,
+        62
       ],
       "reason": "Cross-stack validation primitive enumeration and pointer to laravel-api-endpoint carve-out"
     },
     {
       "file": ".agent-src.uncondensed/skills/code-review/SKILL.md",
       "lines": [
-        43,
         44,
         45,
-        52,
-        65,
+        46,
+        53,
         66,
-        77,
-        86,
-        88,
-        90,
-        222
+        67,
+        78,
+        87,
+        89,
+        91,
+        223
       ],
       "reason": "Cross-stack code-review checklist enumerates handler shape, validation, authz, ORM, escaping per framework"
     },
     {
       "file": ".agent-src.uncondensed/skills/security/SKILL.md",
       "lines": [
-        19,
-        26,
-        30,
+        20,
+        27,
         31,
-        40,
-        44,
-        51,
-        61,
-        79
+        32,
+        41,
+        45,
+        52,
+        62,
+        80
       ],
       "reason": "Cross-stack security review enumerates auth primitives (Policies, voters, guards, middleware) and config paths"
     },
     {
       "file": ".agent-src.uncondensed/skills/verify-completion-evidence/SKILL.md",
       "lines": [
-        56,
         57,
         58,
-        103,
-        180
+        59,
+        104,
+        181
       ],
       "reason": "Evidence-mapping table enumerates the type-checker / linter / refactor tool per stack including PHPStan, Rector, ECS"
     },
@@ -473,7 +473,7 @@
     {
       "file": ".agent-src.uncondensed/skills/code-review/SKILL.md",
       "lines": [
-        226
+        227
       ],
       "reason": "Multi-stack formatter enumeration (ECS, Prettier, Ruff, gofmt) \u2014 comparative example, no project mandate"
     },
@@ -492,16 +492,16 @@
     {
       "file": ".agent-src.uncondensed/skills/context-document/SKILL.md",
       "lines": [
-        54,
         55,
-        78
+        56,
+        79
       ],
       "reason": "Cross-stack target-directory examples (Laravel / Symfony) for module-scoped context docs \u2014 comparative example, no mandate"
     },
     {
       "file": ".agent-src.uncondensed/skills/roadmap-writing/SKILL.md",
       "lines": [
-        19
+        20
       ],
       "reason": "Single Laravel-shape example showing how `{module_root}/{agent_folder}/roadmaps/` resolves on a Laravel HMVC project"
     },
@@ -522,52 +522,52 @@
     {
       "file": ".agent-src.uncondensed/commands/context/create.md",
       "lines": [
-        52
+        53
       ],
       "reason": "Single Laravel-shape example for module-context target directory (road-to-configurable-modules Phase D)"
     },
     {
       "file": ".agent-src.uncondensed/commands/context/refactor.md",
       "lines": [
-        26
+        27
       ],
       "reason": "Single Laravel-shape example for module-context discovery path (road-to-configurable-modules Phase D)"
     },
     {
       "file": ".agent-src.uncondensed/commands/feature/explore.md",
       "lines": [
-        122
+        123
       ],
       "reason": "Single Laravel-shape example showing how `enumerate_modules()` resolves on a Laravel HMVC project (road-to-configurable-modules Phase D)"
     },
     {
       "file": ".agent-src.uncondensed/commands/feature/plan.md",
       "lines": [
-        141,
-        170,
-        254
+        142,
+        171,
+        255
       ],
       "reason": "Laravel-shape examples for module-scoped contexts and feature target paths (road-to-configurable-modules Phase D)"
     },
     {
       "file": ".agent-src.uncondensed/commands/feature/refactor.md",
       "lines": [
-        26
+        27
       ],
       "reason": "Single Laravel-shape example for module-feature discovery path (road-to-configurable-modules Phase D)"
     },
     {
       "file": ".agent-src.uncondensed/commands/feature/roadmap.md",
       "lines": [
-        26,
-        126
+        27,
+        127
       ],
       "reason": "Laravel-shape examples for module-feature/roadmap discovery and target paths (road-to-configurable-modules Phase D)"
     },
     {
       "file": ".agent-src.uncondensed/commands/optimize/agents-dir.md",
       "lines": [
-        23
+        24
       ],
       "reason": "Single Laravel-shape example for per-module agents directory (road-to-configurable-modules Phase D)"
     }

package/scripts/lint_model_tier_coverage.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Fail when a skill or command lacks a `model_tier` value.
+
+Phase 5 coverage gate of `road-to-model-capability-tiers.md` (ADR-035):
+every skill and command MUST declare an explicit `model_tier`
+(`opus | sonnet | gpt`) or `inherit`. An untagged artefact is an error — it
+leaves the per-skill model-switch surface with a silent gap. Run
+`python3 scripts/backfill_model_tier.py` to seed missing tags.
+
+The enum itself is validated by `scripts/validate_frontmatter.py`; this gate
+only enforces *presence* (an explicit decision was made for every artefact).
+
+CLI: python3 scripts/lint_model_tier_coverage.py [--quiet]
+Exit: 0 clean · 1 at least one untagged skill/command.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from validate_frontmatter import parse_frontmatter  # noqa: E402
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _targets():
+    for root in artefact_roots():
+        sdir = root / "skills"
+        if sdir.exists():
+            for p in sorted(sdir.rglob("SKILL.md")):
+                yield "skill", p
+        cdir = root / "commands"
+        if cdir.exists():
+            for p in sorted(cdir.rglob("*.md")):
+                if p.name != "AGENTS.md":
+                    yield "command", p
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args(argv)
+
+    total = 0
+    missing = []
+    for kind, path in _targets():
+        total += 1
+        fm, _ = parse_frontmatter(path.read_text(encoding="utf-8"))
+        if not isinstance(fm, dict) or not fm.get("model_tier"):
+            missing.append((kind, path.relative_to(ROOT).as_posix()))
+
+    if missing:
+        for kind, rel in missing[:40]:
+            print(f"❌  [{kind}] {rel}: missing `model_tier` "
+                  f"(set lite/medium/high or inherit)")
+        if len(missing) > 40:
+            print(f"  ... and {len(missing) - 40} more")
+        print(
+            f"\n== model_tier coverage: {len(missing)}/{total} artefact(s) "
+            "untagged. Run `python3 scripts/backfill_model_tier.py`. ==",
+            file=sys.stderr,
+        )
+        return 1
+    if not args.quiet:
+        print(f"✅  lint-model-tier-coverage: {total} artefact(s) tagged.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/roadmap_progress_hook.py

@@ -75,6 +75,26 @@ def _candidate_paths(payload: dict) -> list[str]:
     return out
 
 
+def _relativize(path: str, root: Path) -> str:
+    """Make an absolute path project-relative so the `agents/roadmaps/` prefix
+    check fires.
+
+    Claude Code passes an absolute `tool_input.file_path`
+    (`/Users/.../<repo>/agents/roadmaps/x.md`); Augment passes a repo-relative
+    one. Without this, an absolute path never matches the relative prefix and
+    the hook silently no-ops. Already-relative paths and out-of-tree paths are
+    returned unchanged — an out-of-tree roadmap correctly fails the prefix
+    check downstream.
+    """
+    p = Path(path)
+    if not p.is_absolute():
+        return path
+    try:
+        return str(p.resolve().relative_to(root.resolve()))
+    except (ValueError, OSError):
+        return path
+
+
 def _is_roadmap_touch(path: str) -> bool:
     """Return True if `path` is a roadmap file we should react to."""
     norm = path.lstrip("./").replace("\\", "/")
@@ -126,7 +146,7 @@ def run(stdin_text: str, *, consumer_root: Path, verbose: bool = False) -> int:
     if not isinstance(tool, str) or tool not in WRITE_TOOLS:
         return 0
 
-    paths = _candidate_paths(payload)
+    paths = [_relativize(p, consumer_root) for p in _candidate_paths(payload)]
     if not any(_is_roadmap_touch(p) for p in paths):
         return 0
 
@@ -188,10 +208,16 @@ def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--platform", default="generic",
                         help="informational platform tag (augment/claude/...)")
+    parser.add_argument("--project-dir", default="",
+                        help="project root override; falls back to cwd. The "
+                             "Claude plugin passes $CLAUDE_PROJECT_DIR so a "
+                             "globally-resolved binary (ADR-020) scans the "
+                             "right project's agents/roadmaps/.")
     parser.add_argument("--verbose", action="store_true",
                         help="emit one stderr line per invocation")
     args = parser.parse_args(argv)
-    return run(sys.stdin.read(), consumer_root=Path.cwd(), verbose=args.verbose)
+    root = Path(args.project_dir).expanduser() if args.project_dir else Path.cwd()
+    return run(sys.stdin.read(), consumer_root=root, verbose=args.verbose)
 
 
 if __name__ == "__main__":  # pragma: no cover