@delorenj/pjangler 1.3.0 → 1.4.2

package/templates/commonproject/template/.mise/scripts/sync-skills.py

@@ -11,6 +11,7 @@ import argparse
 import hashlib
 import json
 import os
+import pathlib
 import re
 import shutil
 import stat
@@ -82,6 +83,23 @@ class PackUnavailable(Exception):
     """
 
 
+# --------------------------------------------------------------------------- #
+# Which repo does this script own?
+#
+# A mise ENTER hook runs with cwd set to the directory the user cd'd into, not
+# to config_root -- and that is true for a PARENT config's hook too, so entering
+# 33GOD/pjangler fired 33GOD's copy of this script with cwd=pjangler. It then
+# loaded pjangler's manifest and rewrote pjangler's .agents/ and CLI skill dirs.
+# `mise run <task>` DOES run at config_root, which is why the cwd assumption
+# looked correct for years: only the enter-hook path was ever wrong.
+#
+# So the subject is taken explicitly, defaulting to $MISE_CONFIG_ROOT (mise
+# exports it per hook, correctly), and it must match the root this script file
+# actually lives in. A repo-local script never acts on cwd, and never on a
+# sibling.
+# --------------------------------------------------------------------------- #
+
+
 def parse_args():
     parser = argparse.ArgumentParser(
         description="Sync skills from manifest to agent CLIs."
@@ -100,9 +118,63 @@ def parse_args():
             "directories.  Without this flag they are only reported."
         ),
     )
+    parser.add_argument(
+        "--no-reconcile",
+        action="store_true",
+        help=(
+            "Keep managed projection links this sync did not declare.  By "
+            "default a projection is reconciled: a symlink into a managed "
+            "registry root that no declared skill or pack accounts for is "
+            "removed, because leaving it is what turns a projection into "
+            "sediment (81 of pjangler's 132 links were dangling)."
+        ),
+    )
+    parser.add_argument(
+        "--reconcile-dry-run",
+        action="store_true",
+        help=(
+            "Print the links reconcile WOULD remove and remove nothing.  Run "
+            "this first against any projection that has never been synced -- "
+            "notably --scope global, whose projection is shared by every CLI "
+            "and every project on the machine.  Suppresses deletions only: "
+            "links are still created and relinked."
+        ),
+    )
+    parser.add_argument(
+        "--root",
+        default=os.environ.get("MISE_CONFIG_ROOT") or None,
+        help=(
+            "Project root this sync owns; defaults to $MISE_CONFIG_ROOT.  Never "
+            "cwd: a parent mise config's enter hook runs with cwd set to the "
+            "child directory you entered, so cwd names a sibling repo."
+        ),
+    )
     return parser.parse_args()
 
 
+def own_root():
+    """The repo this script file belongs to: <root>/.mise/scripts/<this>."""
+    return pathlib.Path(__file__).resolve().parents[2]
+
+
+def resolved_project_root(args):
+    mine = own_root()
+    if args.scope != "project":
+        return mine
+    if not args.root:
+        raise SystemExit(
+            "sync-skills: --root (or $MISE_CONFIG_ROOT) is required for "
+            "--scope project; refusing to infer the subject repo from cwd"
+        )
+    requested = pathlib.Path(args.root).resolve(strict=True)
+    if requested != mine:
+        raise SystemExit(
+            f"sync-skills: refusing to act on {requested}; this script belongs "
+            f"to {mine}.  A nested repo must ship its own .mise/scripts copy."
+        )
+    return requested
+
+
 def load_manifest(manifest_path):
     if not manifest_path.exists():
         return {"skills": []}
@@ -165,6 +237,95 @@ def assert_real_directory_chain(root, target):
             raise ValueError(f"Destination parent is not a directory: {current}")
 
 
+def alias_root_exclusions():
+    """Managed roots that may NOT host the projection directory itself.
+
+    `~/.agents/.cache` is a managed root for reconcile purposes, but
+    `sync_registry()` CLONES and PULLS arbitrary remote git repositories into it.
+    A projection living inside one would be rewritten by whoever controls the
+    registry, so the alias may only land in a checkout the operator owns and this
+    engine never fetches into.
+    """
+    return (Path(os.path.expanduser("~/.agents/.cache")),)
+
+
+def canonical_alias_roots():
+    """The roots the single managed-skills alias may resolve into."""
+    excluded = set()
+    for candidate in alias_root_exclusions():
+        try:
+            excluded.add(candidate.resolve(strict=True))
+        except OSError:
+            continue
+    return {root for root in default_managed_roots() if root not in excluded}
+
+
+def assert_safe_resolved_chain(root, resolved):
+    """Every component from `root` down to `resolved` is a real, safe directory.
+
+    Both arguments are already realpath-normalized, so this is a plain lstat walk:
+    no component is a symlink, each is a directory, each is owned by this user,
+    and none is world-writable.
+
+    Group-writability is deliberately ALLOWED. The canonical checkout is 0775
+    under the operator's own primary group, so a "no group-write" rule would
+    refuse the very topology this exists to admit. World-write is what actually
+    hands the path to someone else.
+    """
+    uid = os.getuid() if hasattr(os, "getuid") else None
+    try:
+        relative = resolved.relative_to(root)
+    except ValueError as error:
+        raise ValueError(f"Resolved alias escapes its managed root {root}: {resolved}") from error
+    current = root
+    for part in relative.parts:
+        current = current / part
+        info = current.lstat()
+        if stat.S_ISLNK(info.st_mode):
+            raise ValueError(f"Resolved alias chain contains a symlink: {current}")
+        if not stat.S_ISDIR(info.st_mode):
+            raise ValueError(f"Resolved alias chain component is not a directory: {current}")
+        if uid is not None and info.st_uid != uid:
+            raise ValueError(f"Resolved alias chain component is not owned by this user: {current}")
+        if info.st_mode & stat.S_IWOTH:
+            raise ValueError(f"Resolved alias chain component is world-writable: {current}")
+
+
+def resolve_managed_alias(alias, allowed_roots):
+    """Resolve the ONE admissible symlinked projection, or refuse.
+
+    Every containment assertion in this engine is LEXICAL -- `symlink_target.parent
+    != real_cli_dir`, `assert_destinations_contained`. A lexical guard is sound
+    only over a symlink-free path, which is why `assert_real_directory_chain`
+    refused any symlinked destination outright.
+
+    That refusal made `--scope global` unrunnable, because the canonical topology
+    IS a symlink: `~/.agents/skills -> ~/code/skillex/skill-sets/global`. The
+    relaxation admits exactly that shape and nothing else -- the alias must be a
+    symlink owned by this user that resolves, with no further symlink in the
+    chain, into a managed registry root the operator owns. Callers then address
+    the RESOLVED path for every mutation, so re-pointing the alias mid-run cannot
+    redirect a write.
+    """
+    if not allowed_roots:
+        raise ValueError(f"No managed registry root is available to host {alias}")
+    info = alias.lstat()
+    uid = os.getuid() if hasattr(os, "getuid") else None
+    if uid is not None and info.st_uid != uid:
+        raise ValueError(f"Managed skills alias is not owned by this user: {alias}")
+    resolved = alias.resolve(strict=True)
+    for root in sorted(allowed_roots, key=lambda candidate: len(str(candidate)), reverse=True):
+        try:
+            resolved.relative_to(root)
+        except ValueError:
+            continue
+        assert_safe_resolved_chain(root, resolved)
+        return resolved
+    raise ValueError(
+        f"Managed skills alias does not resolve into a managed registry root: "
+        f"{alias} -> {resolved}"
+    )
+
 def cli_skill_dirs(scope):
     try:
         return CLI_SKILL_DIRS[scope]
@@ -187,6 +348,41 @@ def lexical_symlink_target(link):
     return Path(os.path.normpath(str(lexical)))
 
 
+def assert_nonrecursive_skill_link(destination, source):
+    """Reject a link that would point from inside a skill back to that skill.
+
+    A repository may legitimately be the source of a globally distributed
+    skill.  When fanout runs inside that same repository, however, projecting
+    ``<repo>/.claude/skills/<name> -> <repo>`` creates an unbounded filesystem
+    cycle for every symlink-following walker.  Compare the lexical destination
+    against the resolved source so the check also catches a catalog alias that
+    points at the repository root.
+
+    The one safe equality is an existing real directory in the shared managed
+    projection.  That directory is already in its final location and the
+    caller preserves it instead of creating a symlink.
+    """
+    destination = Path(destination).absolute()
+    source = Path(source).resolve(strict=True)
+    if destination == source and is_real_directory(destination):
+        return
+    try:
+        destination.relative_to(source)
+    except ValueError:
+        return
+    raise ValueError(
+        "Refusing recursive skill symlink: destination "
+        f"{destination} is inside its resolved source {source}"
+    )
+
+
+def assert_nonrecursive_skill_topology(active_cli_dirs, skill_sources):
+    """Validate every proposed source/destination pair before any mutation."""
+    for _cli_dir, expected_cli in active_cli_dirs:
+        for name, source in skill_sources.items():
+            assert_nonrecursive_skill_link(expected_cli / validate_skill_name(name), source)
+
+
 def preflight_cli_dirs(
     cli_dirs_base,
     skill_names,
@@ -232,17 +428,35 @@ def preflight_cli_dirs(
             canonical_alias = lexical_symlink_target(cli_dir) == managed_skills
             if not canonical_alias:
                 raise ValueError(f"Refusing symlinked CLI skills directory: {cli_dir}")
-            assert_real_directory_chain(base, managed_skills)
-            if (
-                not managed_skills.exists()
-                or managed_skills.is_symlink()
-                or not managed_skills.is_dir()
-            ):
-                raise ValueError(
-                    f"Managed skills alias target is not a real directory: {managed_skills}"
-                )
+            assert_real_directory_chain(base, managed_skills.parent)
+            # In the canonical Skillex topology the projection directory IS the
+            # registry checkout, reached through a symlink
+            # (`~/.agents/skills -> ~/code/skillex/skill-sets/global`), so
+            # demanding a real directory here made `--scope global` unrunnable on
+            # the only machine that has the topology. Admit exactly that shape
+            # through resolve_managed_alias() and nothing else.
+            if managed_skills.is_symlink():
+                if scope != "global":
+                    # A generated PROJECT always owns a real `.agents/skills` --
+                    # pjangler's TypeScript mirror (projectSkillTopologyIssues in
+                    # src/parity/rules.ts) says so too. Relaxing only the global
+                    # scope keeps every project destination on the strict rule.
+                    raise ValueError(
+                        f"Managed skills alias target is not a real directory: {managed_skills}"
+                    )
+                resolved_alias = resolve_managed_alias(managed_skills, canonical_alias_roots())
+            else:
+                if (
+                    not managed_skills.exists()
+                    or not managed_skills.is_dir()
+                ):
+                    raise ValueError(
+                        f"Managed skills alias target is not a real directory: {managed_skills}"
+                    )
+                assert_real_directory_chain(base, managed_skills)
+                resolved_alias = managed_skills.resolve(strict=True)
             resolved_cli = cli_dir.resolve(strict=True)
-            if resolved_cli != managed_skills.resolve(strict=True):
+            if resolved_cli != resolved_alias:
                 raise ValueError(
                     f"Managed skills alias escapes managed project skills: {cli_dir}"
                 )
@@ -251,7 +465,12 @@ def preflight_cli_dirs(
             # instead would silently drop every `skills[]` entry on a project
             # where every supported CLI is aliased -- `provision-packs.py`
             # only ever materializes pack members.
-            managed_expected = managed_skills.parent.resolve(strict=True) / managed_skills.name
+            # Pin the RESOLVED directory as the expected destination. Every later
+            # mutation then addresses the real path directly instead of
+            # re-traversing the alias, so re-pointing the alias mid-run cannot
+            # redirect a write; revalidate_cli_dir() re-checks it still resolves
+            # here before each one.
+            managed_expected = resolved_alias
             # Containment first, so an escaping name is reported as an escape
             # rather than as whatever it happens to collide with.
             assert_destinations_contained(managed_expected)
@@ -259,7 +478,7 @@ def preflight_cli_dirs(
             # real, hand-authored skill directories.  Never let the fanout
             # rmtree one of those; fail here, before anything is mutated.
             for name in skill_names:
-                destination = managed_skills / name
+                destination = resolved_alias / name
                 if not is_real_directory(destination):
                     continue
                 source = skill_sources.get(name) if skill_sources is not None else None
@@ -284,6 +503,8 @@ def preflight_cli_dirs(
             if cli_dir.exists() and cli_dir.resolve(strict=True) != expected_cli:
                 raise ValueError(f"CLI skills directory escapes its parent: {cli_dir}")
         add_target(cli_dir, expected_cli)
+    if skill_sources is not None:
+        assert_nonrecursive_skill_topology(active, skill_sources)
     return active
 
 
@@ -293,11 +514,22 @@ def revalidate_cli_dir(cli_dirs_base, cli_dir, expected_cli):
     assert_real_directory_chain(base, cli_dir.parent)
     if cli_dir.parent.is_symlink() or not cli_dir.parent.is_dir():
         raise ValueError(f"Unsafe CLI destination parent after preflight: {cli_dir.parent}")
+    if cli_dir.is_symlink():
+        # Exactly ONE symlinked destination is admissible -- the canonical
+        # managed-skills alias -- and only while it still resolves to the very
+        # directory preflight pinned as `expected_cli`. `expected_cli != cli_dir`
+        # is what tells the global alias (pinned to its RESOLVED target) apart
+        # from a project's real `.agents/skills`, where the two are the same
+        # path; a project destination that turned into a symlink after preflight
+        # therefore still fails here.
+        if cli_dir != managed_skills_dir(base) or expected_cli == cli_dir:
+            raise ValueError(f"CLI skills directory changed to a symlink after preflight: {cli_dir}")
+        if resolve_managed_alias(cli_dir, canonical_alias_roots()) != expected_cli:
+            raise ValueError(f"Managed skills alias re-pointed after preflight: {cli_dir}")
+        return
     current_expected = cli_dir.parent.resolve(strict=True) / cli_dir.name
     if current_expected != expected_cli:
         raise ValueError(f"CLI destination parent changed after preflight: {cli_dir}")
-    if cli_dir.is_symlink():
-        raise ValueError(f"CLI skills directory changed to a symlink after preflight: {cli_dir}")
     if cli_dir.exists():
         if not cli_dir.is_dir() or cli_dir.resolve(strict=True) != expected_cli:
             raise ValueError(f"Unsafe CLI skills directory after preflight: {cli_dir}")
@@ -776,7 +1008,7 @@ def select_pack_version(pack_dir):
     The discriminator is what those children ARE: a child holding a regular
     SKILL.md is a skill, so its parent cannot be a version root.  Contrast
     `packs/bmad/`, also pack.toml-less and also all real directories, but whose
-    children (6.10.1-next.31/, 6.10.2/) hold no top-level SKILL.md -- that IS a
+    children (1.2.0-next.3/, 1.3.0/) hold no top-level SKILL.md -- that IS a
     version layout and the highest version is selected.
 
     `packs/Kurzgesagt/` is NOT an example of this: its twelve children are all
@@ -1330,7 +1562,7 @@ def resolve_pack(
 
         {"name", "root", "family_root", "declared"}
 
-    `root` is the exact pack root (e.g. `packs/bmad/6.10.2`); `family_root` is
+    `root` is the exact pack root (e.g. `packs/bmad/1.3.0`); `family_root` is
     `packs/bmad` when the pack lives under a version directory, else None. The
     two are reported SEPARATELY on purpose: a sibling version under the same
     family root is NOT this pack, so callers must never treat the family root
@@ -1526,12 +1758,81 @@ def handle_retired_dirs(cli_dirs_base, managed_roots, prune=False):
 # --------------------------------------------------------------------------- #
 
 
+def reconcile_projection(real_cli_dir, skills_map, managed_roots, project_root=None, apply=True):
+    """Remove managed projection links this sync does not account for.
+
+    `fanout_to_cli` only ever added and overwrote. Nothing removed a link, so a
+    projection was a monotonically growing record of every skill the repo ever
+    declared: rename a skill, retire a pack, or move a registry cache and the
+    old link stayed forever, dangling. Measured on the reporting machine: 81 of
+    pjangler's 132 `.claude/skills` links pointed at BMAD pack versions that no
+    longer exist, and a hand-planted broken link -- including one whose name IS
+    a declared entry -- survived a re-run untouched.
+
+    Deliberately narrow. Only a SYMLINK is ever removed, and only when its
+    LEXICAL target (never a resolved one -- resolving a hostile link would walk
+    outside the project first) lies inside a managed registry root. So:
+
+      - a real directory is never touched: that is BMAD's installer output in
+        `<cli>/skills`, or a hand-authored skill in `.agents/skills`;
+      - a link pointing anywhere outside the managed roots is the operator's
+        own and is left alone;
+      - a pack member survives, because `skills_map` already contains every
+        name the declared packs resolved to before fanout runs.
+    """
+    removed = []
+    try:
+        entries = sorted(os.listdir(real_cli_dir))
+    except OSError:
+        return removed
+    for name in entries:
+        if name in skills_map:
+            continue
+        candidate = real_cli_dir / name
+        if not candidate.is_symlink():
+            continue
+        try:
+            target = lexical_symlink_target(candidate)
+        except OSError:
+            continue
+        dangling = not candidate.exists()
+        # A DANGLING link is removed wherever it points. It names a skill and
+        # resolves to nothing, so it cannot be serving anyone, and the managed-root
+        # test would miss exactly the ones that hurt most: the relics of a retired
+        # intermediate hop. `<repo>/.claude/skills/hindsight ->
+        # 33GOD/skills/hindsight` outlived that farm entry and is not inside any
+        # registry root, so it would have rotted here forever. A link that still
+        # resolves is only removed inside a managed root, where this engine is the
+        # only writer.
+        # A live link is removable inside a managed registry root -- and inside the
+        # PROJECT ROOT itself, which is equally this engine's territory. Seven
+        # links in pjangler pointed at `<repo>/skills/<name>` for names the global
+        # scope already provides: leftovers from the era when inherit_global
+        # materialized the whole global manifest into every project. They resolve,
+        # so the managed-root test left them, and they are precisely the duplicate
+        # copy this engine now exists to stop making. A repo's own skill is not
+        # caught by this: discovery puts it in skills_map, so it is declared.
+        own_territory = is_inside_managed_root(target, managed_roots)
+        if not own_territory and project_root is not None:
+            own_territory = is_inside_managed_root(target, {Path(project_root).resolve()})
+        if not dangling and not own_territory:
+            continue
+        state = "dangling" if dangling else "undeclared"
+        if apply:
+            candidate.unlink()
+        removed.append((candidate, target, state))
+        print(f"{'✗' if apply else 'would remove'} {candidate} ({state} -> {target})")
+    return removed
+
 def fanout_to_cli(
     cli_dirs_base,
     skills_map,
     active_cli_dirs=None,
     before_mutation=None,
     scope="project",
+    managed_roots=None,
+    reconcile=True,
+    reconcile_apply=True,
 ):
     """
     Creates symlinks in each of the supported CLI skill dirs relative to
@@ -1539,7 +1840,12 @@ def fanout_to_cli(
     """
     skill_names = [validate_skill_name(name) for name in skills_map]
     if active_cli_dirs is None:
-        active_cli_dirs = preflight_cli_dirs(cli_dirs_base, skill_names, scope)
+        active_cli_dirs = preflight_cli_dirs(
+            cli_dirs_base,
+            skill_names,
+            scope,
+            skill_sources=skills_map,
+        )
     if skill_names and not active_cli_dirs:
         # A sync that resolves skills but has nowhere to put them has FAILED.
         # Reporting success here is how a topology change silently unprojects
@@ -1564,6 +1870,7 @@ def fanout_to_cli(
             symlink_target = real_cli_dir / name
             if symlink_target.parent != real_cli_dir:
                 raise ValueError(f"Skill destination escapes CLI directory: {symlink_target}")
+            assert_nonrecursive_skill_link(symlink_target, actual_path)
 
             # A project-local source may already be the exact destination in
             # the shared `.agents/skills` projection. Preserve that real
@@ -1591,16 +1898,103 @@ def fanout_to_cli(
                     symlink_target.unlink()
 
             revalidate_cli_dir(cli_dirs_base, cli_dir, expected_cli)
+            assert_nonrecursive_skill_link(symlink_target, actual_path)
             os.symlink(actual_path, symlink_target)
             linked_total += 1
             print(f"→ {symlink_target} -> {actual_path}")
 
+    removed_total = 0
+    if reconcile and managed_roots:
+        for cli_dir, expected_cli in active_cli_dirs:
+            revalidate_cli_dir(cli_dirs_base, cli_dir, expected_cli)
+            removed_total += len(
+                reconcile_projection(
+                    expected_cli.resolve(strict=True),
+                    skills_map,
+                    managed_roots,
+                    # `cli_dirs_base` is the REPO at project scope -- and $HOME at
+                    # global scope, where "inside the project root" would mean
+                    # "anywhere under $HOME", i.e. every skill source on the
+                    # machine. That is not a narrow rule, it is no rule: the
+                    # global farm would reclaim every undeclared link it holds.
+                    # Global scope keeps the managed-root test only.
+                    project_root=None if scope == "global" else cli_dirs_base,
+                    apply=reconcile_apply,
+                )
+            )
+
     print(
-        f"sync-skills: {linked_total} new/updated symlink(s) "
-        f"across CLIs in {cli_dirs_base}"
+        f"sync-skills: {linked_total} new/updated symlink(s), "
+        f"{removed_total} stale link(s) "
+        + ("removed " if reconcile_apply else "to remove (dry run) ")
+        + f"across CLIs in {cli_dirs_base}"
     )
 
 
+def report_global_inheritance(global_manifest_path):
+    """Verify that the user scope is reachable; project NOTHING from it.
+
+    `inherit_global: true` used to prepend the whole global manifest as layer 0
+    of a PROJECT run, so every global skill was materialized as a fresh symlink
+    inside every project CLI skill dir -- 38 resolvable global skills x2 present
+    CLI dirs = 76 links per project, re-created on every `cd`.
+
+    That work is dead. Every agent CLI installed on a machine like this one
+    reads the user scope implicitly, and each of its global skill roots is
+    already a single dir-level symlink to ~/.agents/skills:
+
+        ~/.claude/skills ~/.codex/skills ~/.gemini/skills ~/.copilot/skills
+        ~/.kimi-code/skills ~/.config/opencode/skills ~/.openclaw/skills
+
+    One projection, N aliases -- so a global skill is visible in a project
+    because the CLI inherits the user scope, not because someone copied a link
+    into the repo. A project projection holds only that repo's own declared
+    skills and its declared packs.
+
+    What is left here is the check: if the user-scope alias is missing or points
+    somewhere else, global skills are NOT reachable and the operator should hear
+    about it rather than have this script quietly paper over it with copies.
+    """
+    home = Path(os.path.expanduser("~"))
+    managed = managed_global_skills_dir(home)
+    reachable, broken = [], []
+    for cli_rel_path in cli_skill_dirs("global"):
+        alias = home / cli_rel_path
+        if not alias.exists() and not alias.is_symlink():
+            continue
+        try:
+            if alias.resolve(strict=True) == managed.resolve(strict=True):
+                reachable.append(cli_rel_path)
+                continue
+        except OSError:
+            pass
+        broken.append(cli_rel_path)
+    # This runs from an enter hook on every `cd`, so say nothing when the user
+    # scope is intact. Report only what an operator has to act on.
+    if not broken and reachable:
+        return
+    declared = len(load_manifest(global_manifest_path).get("skills", []))
+    for cli_rel_path in broken:
+        print(
+            f"Warning: ~/{cli_rel_path} does not resolve to {managed}; global "
+            f"skills are not reachable for that CLI.  Fix the alias "
+            f"(ln -sfn {managed} ~/{cli_rel_path}); do not copy links into "
+            f"projects.",
+            file=sys.stderr,
+        )
+    if not reachable:
+        print(
+            f"Warning: no user-scope alias of {managed} was found, so none of "
+            f"the {declared} global skill(s) declared in {global_manifest_path} "
+            f"are reachable from any CLI.",
+            file=sys.stderr,
+        )
+
+
+def managed_global_skills_dir(home):
+    """The single user-scope projection every global CLI root aliases."""
+    return home.joinpath(*MANAGED_SKILLS_RELATIVE)
+
 def manifest_layer(manifest_path):
     manifest = load_manifest(manifest_path)
     validate_manifest_skill_names(manifest)
@@ -1613,30 +2007,88 @@ def manifest_layer(manifest_path):
     }
 
 
+def repo_local_skill_layer(project_root, inherited_names):
+    """Project `<repo>/skills/<name>/SKILL.md` without anyone declaring it.
+
+    "Repo-specific skills live in the repo" is only true if the repo's own
+    skills reach an agent working in it. They did not: pjangler authored
+    `pjangler-dev` and `pjangler-parity-rules` and projected neither into any CLI
+    directory at any scope, so the skills describing how to develop pjangler were
+    invisible to every agent developing pjangler.
+
+    Discovered rather than declared, on purpose. `.agents/skills.json` is
+    generated and gitignored in these repos, so a hand-written entry there does
+    not survive a fresh clone; and a declaration that merely restates the
+    contents of a directory is a second copy of the truth that can drift from the
+    first. A directory holding a SKILL.md IS the declaration.
+
+    A name the GLOBAL scope already provides is skipped: every CLI inherits the
+    user scope implicitly, so projecting it here would be the copy this engine
+    exists to stop making. That is why pjangler gets exactly its two repo-only
+    skills and not the seven it authors for machine-wide use.
+
+    Lowest precedence. A declared pack or an explicit skills[] entry of the same
+    name still wins, because explicit beats discovered.
+    """
+    skills_root = project_root / "skills"
+    if not skills_root.is_dir() or skills_root.is_symlink():
+        return None
+    entries = []
+    for child in sorted(skills_root.iterdir()):
+        if child.name.startswith("."):
+            continue
+        if child.is_symlink() or not child.is_dir():
+            continue
+        if not (child / "SKILL.md").is_file():
+            continue
+        name = validate_skill_name(child.name)
+        if name in inherited_names:
+            continue
+        entries.append({"name": name, "source": child.resolve(strict=True).as_uri()})
+    if not entries:
+        return None
+    print(f"Discovered {len(entries)} repo-local skill(s) in {skills_root}")
+    return {
+        "manifest": {"skills": entries},
+        "packs": [],
+        "base_dir": project_root,
+        "registry": DEFAULT_REGISTRY,
+    }
+
 def main():
     args = parse_args()
 
+    project_root = resolved_project_root(args)
     global_manifest_path = Path(os.path.expanduser("~/.agents/skills.json"))
-    project_manifest_path = Path(os.getcwd()) / ".agents" / "skills.json"
+    project_manifest_path = project_root / ".agents" / "skills.json"
 
     # Destination topology is a security boundary.  Validate every active CLI
     # directory before cloning/updating registries, creating caches, or changing
     # any skill link so one unsafe/broken symlink produces zero mutation.
     #
     # Precedence, lowest to highest (contract section 5):
-    #   global packs[] -> global skills[] -> project packs[] -> project skills[]
+    #   global packs[] -> global skills[] -> <repo>/skills discovery
+    #     -> project packs[] -> project skills[]
+    # Discovery sits below the project manifest: explicit beats discovered.
     layers = []
     if args.scope == "global":
         preflight_base = Path(os.path.expanduser("~"))
         print(f"Loading global manifest from {global_manifest_path}")
         layers.append(manifest_layer(global_manifest_path))
     else:
-        preflight_base = Path(os.getcwd())
+        preflight_base = project_root
         print(f"Loading project manifest from {project_manifest_path}")
         project_layer = manifest_layer(project_manifest_path)
+        inherited_names = set()
         if project_layer["manifest"].get("inherit_global", False):
-            print("Inheriting global skills...")
-            layers.append(manifest_layer(global_manifest_path))
+            report_global_inheritance(global_manifest_path)
+            inherited_names = {
+                manifest_skill_name(skill)
+                for skill in load_manifest(global_manifest_path).get("skills", [])
+            }
+        discovered = repo_local_skill_layer(project_root, inherited_names)
+        if discovered is not None:
+            layers.append(discovered)
         layers.append(project_layer)
 
     preflight_names = []
@@ -1719,6 +2171,9 @@ def main():
         skills_to_sync,
         active_cli_dirs=active_cli_dirs,
         scope=args.scope,
+        managed_roots=managed_roots,
+        reconcile=not args.no_reconcile,
+        reconcile_apply=not args.reconcile_dry_run,
     )
 
     handle_retired_dirs(preflight_base, managed_roots, prune=args.prune_retired)