@event4u/agent-config 5.7.0 → 5.9.0

package/scripts/check_gate_paths.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Gate path-integrity check (R2 of road-to-test-and-gate-integrity).
+
+Asserts that every security/quality gate which enforces something against
+a fixed ``packages/core/`` target still resolves that target on disk. A
+``packages/core/`` move that desyncs a gate's hard-coded path fails CI here
+instead of silently no-opping (the ``aab5755`` class: the Iron-Law SHA gate
+pointed at a stale path and enforced nothing while CI stayed green).
+
+Design (AI council, claude-sonnet-4-5 + gpt-4o, 2026-06-02):
+
+- The check reads each gate's ACTUAL enforced paths via its module-level
+  ``GATE_CORE_PATHS`` attribute — it does NOT re-declare a copy of the path
+  strings. A hand-maintained path registry would reintroduce the very
+  desync risk this guards against, one layer down.
+- Scope is strictly the single-root hard-coders. Multi-root gates that
+  resolve via ``artefact_roots()`` (e.g. ``iron_law_sha``) are excluded:
+  asserting a single ``packages/core/`` path for them would false-pass on a
+  legacy layout or false-fail on a pack-only layout.
+
+The input set is this gate list (no separate config file).
+
+Usage:
+    python3 scripts/check_gate_paths.py
+Exit codes: 0 = all enforced targets resolve under packages/core/ ·
+1 = at least one missing / out-of-tree target · 2 = a gate failed to import.
+"""
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_package_core_path  # noqa: E402
+
+PACKAGE_CORE = resolve_package_core_path("")
+
+# Single-root gates that enforce against a fixed packages/core/ target and
+# expose it via a module-level GATE_CORE_PATHS tuple. Adding a gate here is
+# the only manual step; its paths are read from the gate, never copied.
+GATES: tuple[str, ...] = (
+    "inventory_abstraction_budget",
+    "audit_command_surface",
+    "lint_agents_md",
+    "audit_initial_context",
+)
+
+
+def _is_under_core(p: Path) -> bool:
+    try:
+        p.resolve().relative_to(PACKAGE_CORE.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def collect_gate_paths(gate_modules: tuple[str, ...]) -> dict[str, list[Path]]:
+    """Import each gate and read its declared ``GATE_CORE_PATHS``.
+
+    Raises ``ImportError`` (surfaced as exit 2 by ``main``) if a gate cannot
+    be imported — a gate whose path logic broke at import time is itself a
+    failure this check should not swallow.
+    """
+    out: dict[str, list[Path]] = {}
+    for name in gate_modules:
+        mod = importlib.import_module(name)
+        paths = getattr(mod, "GATE_CORE_PATHS", None)
+        if not paths:
+            raise AttributeError(
+                f"{name} has no non-empty GATE_CORE_PATHS — gate cannot be "
+                f"checked. Declare the packages/core targets it enforces."
+            )
+        out[name] = [Path(p) for p in paths]
+    return out
+
+
+def check_paths(named: dict[str, list[Path]]) -> list[tuple[str, str, Path]]:
+    """Return ``(gate, reason, path)`` for every target that fails.
+
+    Pure (no import side effects) so tests can drive it with fixtures.
+    A target fails when it does not resolve under ``packages/core/`` or
+    does not exist on disk.
+    """
+    failures: list[tuple[str, str, Path]] = []
+    for gate, paths in named.items():
+        for p in paths:
+            if not _is_under_core(p):
+                failures.append((gate, "not under packages/core/", p))
+            elif not p.exists():
+                failures.append((gate, "target does not exist", p))
+    return failures
+
+
+def main() -> int:
+    try:
+        named = collect_gate_paths(GATES)
+    except (ImportError, AttributeError) as exc:
+        print(f"❌  check-gate-paths: {exc}", file=sys.stderr)
+        return 2
+    failures = check_paths(named)
+    if failures:
+        print("❌  check-gate-paths: gate target(s) do not resolve under packages/core/:")
+        for gate, reason, path in failures:
+            print(f"    {gate}: {reason} → {path}")
+        print("\n  A packages/core/ move likely desynced a gate. Fix the gate's")
+        print("  GATE_CORE_PATHS (built via resolve_package_core_path) or the move.")
+        return 1
+    total = sum(len(v) for v in named.values())
+    print(f"✅  check-gate-paths: {total} enforced target(s) across "
+          f"{len(named)} gate(s) resolve under packages/core/.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/check_references.py

@@ -133,6 +133,53 @@ EXAMPLE_PATH_PATTERNS = [
 ]
 
 
+@dataclass(frozen=True)
+class AllowlistPattern:
+    """A token-class allowlist entry. `reason` is mandatory and auditable."""
+    pattern: "re.Pattern[str]"
+    reason: str
+
+
+# Content-class allowlist for known NON-reference token shapes.
+#
+# The skill/rule prose patterns (`X` skill / `X` rule) occasionally match
+# a backtick token that is not an artifact id — an execution-type enum
+# value, a pack identifier, or a bare meta-qualifier keyword. Historically
+# each such false positive was dodged by *rewording the prose per file*
+# (e.g. dc84ed01 "reword execution-type mentions to dodge check-refs
+# false positive", bd02ef0b "avoid check-refs false-positive on pack
+# name"), a treadmill that distorts natural wording release after release.
+# This layer matches the token *class* centrally instead, so the natural
+# wording passes without per-file edits. It is distinct from:
+#   - SKIP_DIRS          (path-level, whole-directory)
+#   - FILE_SKIP_MARKER   (file-level opt-out)
+#   - LINE_IGNORE_MARKER (per-line opt-out)
+# Every entry carries a mandatory `reason` so the allowlist stays
+# auditable and a future reader can tell why a class is exempt.
+ALLOWLIST_PATTERNS: List[AllowlistPattern] = [
+    AllowlistPattern(
+        re.compile(r"^(?:manual|assisted|automated)$"),
+        "execution-type enum value (runtime-safety frontmatter), e.g. a "
+        "`manual` skill — not a skill/rule id (dc84ed01)",
+    ),
+    AllowlistPattern(
+        re.compile(r"^pack-[\w-]+$"),
+        "pack / workspace identifier, e.g. `pack-ai-video` skills — not a "
+        "skill/rule id (bd02ef0b)",
+    ),
+    AllowlistPattern(
+        re.compile(r"^(?:skill|rule|command|guideline|persona|context|pack|workspace)$"),
+        "bare meta-qualifier keyword used in prose (the `command` vs "
+        "`skill` distinction, etc.) — not an artifact id",
+    ),
+]
+
+
+def _is_allowlisted(name: str) -> bool:
+    """True when `name` matches a known non-reference token class."""
+    return any(entry.pattern.match(name) for entry in ALLOWLIST_PATTERNS)
+
+
 def collect_artifacts(root: Path) -> dict[str, set[str]]:
     """Build lookup sets for skills, rules, commands, guidelines, personas."""
     arts: dict[str, set[str]] = {
@@ -345,7 +392,8 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
         # Skill name references
         for m in SKILL_REF_PATTERN.finditer(line):
             name = m.group(1)
-            if name not in artifacts["skills"] and name not in _SKIP_NAMES:
+            if name not in artifacts["skills"] and name not in _SKIP_NAMES \
+                    and not _is_allowlisted(name):
                 broken.append(BrokenRef(
                     file=str(filepath), line=i, ref=name,
                     ref_type="skill", severity="warning",
@@ -355,7 +403,8 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
         # Rule name references
         for m in RULE_REF_PATTERN.finditer(line):
             name = m.group(1)
-            if name not in artifacts["rules"] and name not in _SKIP_NAMES:
+            if name not in artifacts["rules"] and name not in _SKIP_NAMES \
+                    and not _is_allowlisted(name):
                 broken.append(BrokenRef(
                     file=str(filepath), line=i, ref=name,
                     ref_type="rule", severity="warning",

package/scripts/check_release_published.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+Release-published drift gate.
+
+Catches the "release merged to main but never tagged/published" failure
+mode — where ``main``'s ``package.json`` claims a version that has no
+matching git tag, and npm's ``latest`` therefore lags behind main. This
+is the backstop that would have surfaced the 5.8.0-stuck-on-5.7.0 state
+the moment it happened, instead of weeks later.
+
+Two independent invariants:
+
+  1. **Tag invariant** (always checkable, no network): the version in
+     ``package.json`` MUST have a matching git tag (local or remote).
+  2. **npm invariant** (``--check-npm``, network): ``npm view <pkg>
+     dist-tags.latest`` MUST equal the ``package.json`` version.
+
+Scope guard: this only makes sense on the release trunk. Off ``main``
+(e.g. a feature branch, or a ``release/X.Y.Z`` branch mid-flight where
+the bump legitimately precedes the tag) the gate **no-ops** unless
+``--strict`` is combined with an explicit on-main signal. The daily
+scheduled workflow runs ``--strict --check-npm`` on ``main``; the local
+``task check-release-published`` runs the tag invariant only.
+
+Exit codes: 0 = pass / no-op · 1 = drift detected · 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$")
+REPO_ROOT = Path(__file__).resolve().parent.parent
+PACKAGE_JSON = REPO_ROOT / "package.json"
+MAIN_BRANCH = "main"
+
+
+def _git(*args: str) -> tuple[int, str]:
+    proc = subprocess.run(["git", *args], capture_output=True, text=True, check=False)
+    return proc.returncode, (proc.stdout or "").strip()
+
+
+def _package_version() -> str:
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    return str(data["version"])
+
+
+def _package_name() -> str:
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    return str(data["name"])
+
+
+def _tag_exists(tag: str) -> bool:
+    rc, out = _git("tag", "-l", tag)
+    if rc == 0 and tag in out.splitlines():
+        return True
+    rc, _ = _git("ls-remote", "--exit-code", "--tags", "origin", tag)
+    return rc == 0
+
+
+def _on_main() -> bool:
+    # Local checkout, CI push ref, or CI scheduled ref all map to main.
+    ref = os.environ.get("GITHUB_REF", "")
+    if ref in ("refs/heads/main", "refs/heads/master"):
+        return True
+    rc, head = _git("rev-parse", "--abbrev-ref", "HEAD")
+    return rc == 0 and head == MAIN_BRANCH
+
+
+def _npm_latest(pkg: str) -> str | None:
+    proc = subprocess.run(
+        ["npm", "view", pkg, "dist-tags.latest"],
+        capture_output=True, text=True, check=False,
+    )
+    if proc.returncode != 0:
+        return None
+    return (proc.stdout or "").strip() or None
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Release-published drift gate.")
+    ap.add_argument("--strict", action="store_true",
+                    help="Fail on drift (default: informational, exit 0).")
+    ap.add_argument("--check-npm", action="store_true",
+                    help="Also assert npm dist-tags.latest == package.json version (network).")
+    ap.add_argument("--require-main", action="store_true",
+                    help="Only enforce when on main; no-op elsewhere (default for scheduled).")
+    args = ap.parse_args(argv)
+
+    try:
+        version = _package_version()
+    except (OSError, KeyError, json.JSONDecodeError) as exc:
+        print(f"❌  cannot read package.json version: {exc}", file=sys.stderr)
+        return 3
+    if not SEMVER_RE.match(version):
+        print(f"❌  package.json version is not semver: {version!r}", file=sys.stderr)
+        return 3
+
+    if args.require_main and not _on_main():
+        print(f"ℹ️  not on {MAIN_BRANCH} — release-published gate skipped.")
+        return 0
+
+    problems: list[str] = []
+
+    if not _tag_exists(version):
+        problems.append(
+            f"package.json is {version} but no git tag {version} exists "
+            f"(local or origin) — the release was bumped/merged but never "
+            f"tagged. Complete it: tag the release-merge commit and push "
+            f"(triggers publish-npm.yml), e.g. `git tag {version} && git "
+            f"push origin {version}`."
+        )
+
+    if args.check_npm:
+        pkg = _package_name()
+        latest = _npm_latest(pkg)
+        if latest is None:
+            print(f"⚠️  could not read npm dist-tags.latest for {pkg} "
+                  f"(network/registry) — npm invariant not checked.", file=sys.stderr)
+        elif latest != version:
+            problems.append(
+                f"npm {pkg}@latest is {latest} but package.json is {version} "
+                f"— the published release lags main. Check publish-npm.yml "
+                f"for tag {version}, or re-dispatch it."
+            )
+
+    if not problems:
+        suffix = " + npm" if args.check_npm else ""
+        print(f"✅  release-published: {version} is tagged{suffix} and in sync.")
+        return 0
+
+    header = "❌  Release-published drift:" if args.strict else "⚠️  Release-published drift (warn-only):"
+    print(header, file=sys.stderr)
+    for p in problems:
+        print(f"  - {p}", file=sys.stderr)
+    return 1 if args.strict else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/check_test_coverage_diff.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Coverage forcing-function — WARN-only (R3 of road-to-test-and-gate-integrity).
+
+A lightweight coverage-governance nudge: warn (never block) when a PR adds a
+new gate script without a matching test, so the +0-tests pattern (three
+releases shipped behaviour with no coverage) becomes visible at PR time. This
+is partly a *social* problem — R3 is a nudge, not a cure.
+
+Honest framing (per the roadmap critique): R3 IS a lightweight coverage-
+governance layer, NOT pure hardening. It ships WARN-only, is calibrated from
+the REAL Phase 2 backfill experience (not guessed up front), and carries a
+sunset clause. The hard-fail flip is a SEPARATE, later decision gated on
+warn-phase data.
+
+----------------------------------------------------------------------------
+TRIGGER SURFACE — calibrated from Phase 2 evidence + AI council
+(claude-sonnet-4-5 + gpt-4o, analysis, 2026-06-02):
+
+  WARN when a NEW `scripts/check_*.py` or `scripts/lint_*.py` gate is added
+  with no matching new/changed test in the same diff (`tests/**/test_*.py`
+  or `tests/**/*_test.py` whose stem matches the gate's stem).
+
+What is DELIBERATELY excluded (the council killed these to avoid
+pragma-spam / signal-to-noise collapse — "over-broad triggers train people
+to bypass it"):
+  - Edits to EXISTING gate scripts. Phase 2 migrated 4 gates with one-line
+    path-constant swaps that legitimately needed NO test; a trigger that
+    fired on edits would be pure noise. KNOWN RECALL LIMIT: a behaviour
+    change to an existing gate ships untracked in this warn-only phase —
+    accepted on purpose; revisit only if the warn-phase data justifies it.
+  - New skills with `requires_skills`. Skills are markdown capability docs,
+    usually test-less by design → would fire constantly. Dropped for Phase 1
+    (council: "no Phase 2 evidence; immediate pragma-spam").
+  - Taskfile wiring, docs/`*.md`, `agents/**`, `config/**`, logging/path-
+    constant edits.
+
+PRAGMA — `# coverage-diff-ignore: <reason>` (reason mandatory) in the new
+gate file suppresses its warning. Because the trigger is NEW files only, the
+pragma lives in the added lines (it IS the diff), so it is naturally
+commit-scoped — it cannot silently silence FUTURE edits to the file (those
+do not trigger). Mirrors the `check-refs` `<!-- ref-ignore -->` allowlist.
+
+SUCCESS METRIC + SUNSET (the fail-mode flip is a separate later decision):
+  - Track warn-rate and pragma-rate over the next release cycle (this script
+    emits `coverage-diff: warned=N suppressed=M` so the data is in CI logs —
+    no new telemetry surface).
+  - Consider fail-mode only at >= 3 legitimate catches per cycle AND
+    pragma-rate < 10%.
+  - If precision is poor after one cycle, REMOVE the check rather than
+    escalate it. A noisy nudge people route around is worse than none.
+----------------------------------------------------------------------------
+
+Usage:
+  python3 scripts/check_test_coverage_diff.py [--base-ref REF] [--files-status "A\tpath" ...]
+Exit code: always 0 (warn-only by contract this phase).
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+GATE_RE = re.compile(r"^scripts/(?:check_|lint_)[A-Za-z0-9_]+\.py$")
+PRAGMA_RE = re.compile(r"#\s*coverage-diff-ignore:\s*(\S.*?)\s*$")
+_PRAGMA_SCAN_LINES = 60
+
+
+def _is_test_file(path: str) -> bool:
+    if not (path.startswith("tests/") and path.endswith(".py")):
+        return False
+    stem = Path(path).stem
+    return stem.startswith("test_") or stem.endswith("_test")
+
+
+def _test_matches_gate(gate_path: str, test_paths: list[str]) -> bool:
+    """A test covers a gate when its stem shares the gate's stem.
+
+    Accepts naming variance: `tests/test_check_foo.py`, `tests/foo_test.py`,
+    `tests/sub/test_foo.py` all match gate `scripts/check_foo.py`.
+    """
+    gate_stem = Path(gate_path).stem  # e.g. check_foo
+    short = gate_stem.removeprefix("check_").removeprefix("lint_")  # foo
+    for t in test_paths:
+        tstem = Path(t).stem.removeprefix("test_").removesuffix("_test")
+        if gate_stem in Path(t).stem or short and short in tstem:
+            return True
+    return False
+
+
+def evaluate(changed, pragma_reason):
+    """Pure core (no git, no I/O): classify the changed-file set.
+
+    `changed` is a list of (status, path) where status is the git
+    name-status code ('A' added, 'M' modified, …). `pragma_reason(path)`
+    returns the in-file opt-out reason or None. Returns
+    `(warnings, suppressed)` where warnings is a list of new gate paths
+    with no matching test and no pragma, suppressed is [(path, reason)].
+    """
+    new_gates = [p for (s, p) in changed if s == "A" and GATE_RE.match(p)]
+    test_changes = [p for (_s, p) in changed if _is_test_file(p)]
+    warnings: list[str] = []
+    suppressed: list[tuple[str, str]] = []
+    for gate in new_gates:
+        if _test_matches_gate(gate, test_changes):
+            continue
+        reason = pragma_reason(gate)
+        if reason:
+            suppressed.append((gate, reason))
+        else:
+            warnings.append(gate)
+    return warnings, suppressed
+
+
+def _pragma_reason_from_tree(path: str) -> str | None:
+    f = REPO_ROOT / path
+    try:
+        head = f.read_text(encoding="utf-8", errors="ignore").splitlines()[:_PRAGMA_SCAN_LINES]
+    except OSError:
+        return None
+    for line in head:
+        m = PRAGMA_RE.search(line)
+        if m:
+            return m.group(1)
+    return None
+
+
+def _resolve_base_ref(explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    for candidate in ("origin/main", "origin/master", "main", "master"):
+        try:
+            subprocess.check_output(
+                ["git", "rev-parse", "--verify", candidate], stderr=subprocess.DEVNULL,
+            )
+            return candidate
+        except subprocess.CalledProcessError:
+            continue
+    return "HEAD~1"
+
+
+def _git_name_status(base_ref: str) -> list[tuple[str, str]]:
+    try:
+        out = subprocess.check_output(
+            ["git", "diff", "--name-status", f"{base_ref}...HEAD"],
+            stderr=subprocess.STDOUT, text=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        print(f"⚠️  coverage-diff: git diff failed ({exc.output.strip()}); skipping.", file=sys.stderr)
+        return []
+    rows: list[tuple[str, str]] = []
+    for line in out.splitlines():
+        parts = line.split("\t")
+        if len(parts) >= 2:
+            rows.append((parts[0][:1], parts[-1]))
+    return rows
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--base-ref", default=None)
+    opts = ap.parse_args(argv)
+    changed = _git_name_status(_resolve_base_ref(opts.base_ref))
+    warnings, suppressed = evaluate(changed, _pragma_reason_from_tree)
+    if warnings:
+        print("⚠️  coverage-diff: new gate(s) added with no matching test (warn-only):")
+        for g in warnings:
+            print(f"    {g} — add tests/test_{Path(g).stem}.py, or a "
+                  f"`# coverage-diff-ignore: <reason>` line if no test is warranted.")
+    for g, reason in suppressed:
+        print(f"    (suppressed: {g} — {reason})")
+    print(f"coverage-diff: warned={len(warnings)} suppressed={len(suppressed)}")
+    return 0  # warn-only by contract this phase
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/compile_router.py

@@ -13,6 +13,10 @@ from __future__ import annotations
 import json
 import sys
 from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
 
 ROOT = Path(__file__).resolve().parent.parent
 # ADR-017: rules now live across multiple source roots. Legacy
@@ -20,7 +24,7 @@ ROOT = Path(__file__).resolve().parent.parent
 # pure-condensed consumer projection.
 RULES_DIR = ROOT / ".agent-src.uncondensed" / "rules"
 OUT_PATH = ROOT / "dist" / "router.json"
-SETTINGS_PATH = ROOT / ".agent-settings.yml"
+SETTINGS_PATH = project_settings_path(ROOT)
 SCHEMA_VERSION = 1
 
 # Compile-time rule toggles. Maps rule-id → settings predicate.

package/scripts/condense.py

@@ -27,6 +27,10 @@ import re
 import shutil
 import sys
 from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
 
 import yaml
 
@@ -46,7 +50,7 @@ SOURCE_DIR = PROJECT_ROOT / ".agent-src.uncondensed"
 TARGET_DIR = PROJECT_ROOT / ".agent-src"
 AUGMENT_DIR = PROJECT_ROOT / ".augment"
 HASH_FILE = PROJECT_ROOT / "internal" / ".condensation-hashes.json"
-SETTINGS_FILE = PROJECT_ROOT / ".agent-settings.yml"
+SETTINGS_FILE = project_settings_path(PROJECT_ROOT)
 
 
 def _iter_sources():
@@ -415,6 +419,13 @@ COMMANDS_SOURCE = PROJECT_ROOT / ".agent-src" / "commands"
 PERSONAS_SOURCE = PROJECT_ROOT / ".agent-src" / "personas"
 USER_TYPES_SOURCE = PROJECT_ROOT / ".agent-src" / "user-types"
 CLAUDE_SKILLS_DIR = PROJECT_ROOT / ".claude" / "skills"
+# Committed plugin-marketplace projection for command-as-skill entries.
+# The marketplace is consumed as a git repo, so every skills[] path must be
+# committed. Real skills resolve to .agent-src/skills/<name> (already
+# committed); commands have no <slug>/SKILL.md shape in source, so their
+# committed projection lives here. .claude/skills/ stays a gitignored,
+# generate-tools-rebuilt local auto-discovery channel.
+PLUGIN_SKILLS_DIR = PROJECT_ROOT / ".claude-plugin" / "skills"
 
 PERSONA_TOOL_DIRS = {
     ".claude/personas": "../../.agent-src/personas",
@@ -1156,6 +1167,70 @@ def generate_claude_commands() -> int:
     return count
 
 
+def generate_plugin_command_skills() -> int:
+    """Mirror command-as-skill entries into the committed .claude-plugin/skills/.
+
+    The plugin marketplace references each command entry as a <slug>/SKILL.md
+    path that must be committed (git-consumed marketplace). Commands have no
+    such shape in source, so this projects them as symlinks:
+    .claude-plugin/skills/<slug>/SKILL.md → ../../../.agent-src/commands/<rel>.
+
+    Symlink-only by design: the committed .claude/skills/ shape was always
+    symlinks (ADR-034 model-rendered copies are local-only, never committed),
+    so the distributed marketplace behaviour is preserved exactly. The local
+    auto-discovery channel (.claude/skills/, gitignored) keeps model rendering
+    for the dev loop.
+    """
+    if not COMMANDS_SOURCE.exists():
+        return 0
+
+    PLUGIN_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+
+    skill_names: set[str] = set()
+    if SKILLS_SOURCE.exists():
+        skill_names = {d.name for d in SKILLS_SOURCE.iterdir() if d.is_dir()}
+
+    current_slugs: set[str] = set()
+    count = 0
+    for source_file, slug in _iter_commands():
+        # A real skill of the same name takes priority — skip the command.
+        if slug in skill_names:
+            continue
+        current_slugs.add(slug)
+
+        skill_dir = PLUGIN_SKILLS_DIR / slug
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        skill_file = skill_dir / "SKILL.md"
+        if skill_file.exists() or skill_file.is_symlink():
+            skill_file.unlink()
+
+        rel_path = source_file.relative_to(COMMANDS_SOURCE)
+        rel_target = Path("../../../.agent-src/commands") / rel_path
+        skill_file.symlink_to(rel_target)
+        count += 1
+
+    # Reap stale command dirs from removed commands (exactly one SKILL.md).
+    removed_dirs = 0
+    for item in PLUGIN_SKILLS_DIR.iterdir():
+        if not item.is_dir() or item.is_symlink():
+            continue
+        if item.name in current_slugs:
+            continue
+        skill_md = item / "SKILL.md"
+        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 entries in .claude-plugin/skills/"
+    if removed_dirs:
+        msg += f" ({removed_dirs} stale dirs removed)"
+    info(msg)
+    return count
+
+
 def generate_persona_symlinks() -> int:
     """Create symlink directories for personas (.claude/personas/, .cursor/personas/).
 
@@ -1309,6 +1384,7 @@ def generate_tools() -> None:
         generate_gemini_md()
     skills = generate_claude_skills() if _tool_active("claude-code") else 0
     commands = generate_claude_commands() if _tool_active("claude-code") else 0
+    plugin_cmd_skills = generate_plugin_command_skills() if _tool_active("claude-code") else 0
     plugin_hooks = generate_plugin_hooks() if _tool_active("claude-code") else 0
     personas = generate_persona_symlinks()
     user_types = generate_user_type_symlinks()
@@ -1318,7 +1394,8 @@ def generate_tools() -> None:
     windsurf_wf = generate_windsurf_workflows() if _tool_active("windsurf") else 0
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
-        f"commands={commands} plugin_hooks={plugin_hooks} "
+        f"commands={commands} plugin_cmd_skills={plugin_cmd_skills} "
+        f"plugin_hooks={plugin_hooks} "
         f"personas={personas} user_types={user_types} "
         f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
         f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf} "