@event4u/agent-config 5.6.1 → 5.8.0

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",
@@ -770,6 +781,17 @@ def _parse_frontmatter(content: str) -> tuple[dict, str]:
     return meta if isinstance(meta, dict) else {}, body
 
 
+def _yaml_scalar(value: str) -> str:
+    """Return a YAML-safe single-line scalar for a frontmatter value.
+
+    Descriptions can contain ``:``, ``#``, or quotes — characters that break
+    an unquoted YAML scalar (e.g. ``description: Hard Floor: ...`` is invalid
+    YAML). A JSON string is itself a valid YAML double-quoted scalar, so
+    ``json.dumps`` gives correct escaping for free.
+    """
+    return json.dumps(value, ensure_ascii=False)
+
+
 def _emit_cursor_mdc(source: Path, target: Path) -> None:
     """Write a Cursor `.mdc` file with Cursor-shaped frontmatter."""
     meta, body = _parse_frontmatter(source.read_text())
@@ -777,7 +799,7 @@ def _emit_cursor_mdc(source: Path, target: Path) -> None:
     always_apply = bool(meta.get("alwaysApply") or meta.get("type") == "always")
     lines = [
         "---",
-        f"description: {description}",
+        f"description: {_yaml_scalar(description)}",
         "globs: ",
         f"alwaysApply: {'true' if always_apply else 'false'}",
         "---",
@@ -797,7 +819,7 @@ def _emit_windsurf_rule(source: Path, target: Path) -> None:
     lines = [
         "---",
         f"trigger: {trigger}",
-        f"description: {description}",
+        f"description: {_yaml_scalar(description)}",
         "globs: ",
         "---",
         "",
@@ -1145,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/).
 
@@ -1298,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()
@@ -1307,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} "