@event4u/agent-config 1.39.0 → 1.40.0

package/scripts/install.py

@@ -1217,6 +1217,189 @@ def _smoke_test_hooks(project_root: Path, package_root: Path) -> int:
     return 1 if failed else 0
 
 
+# --- Global user-level install (Phase 3 — road-to-simplicity-and-everywhere) ---
+#
+# `scripts/install --global` ships kernel rules + a curated top-N of skills
+# into per-tool user-scope directories so the agent has them in every
+# project on the machine. Curation lives in templates/global-install-manifest.yml.
+#
+# Files are written under an `event4u/` namespace so `--global --uninstall`
+# can wipe the namespace dir without touching user-added files.
+
+GLOBAL_NAMESPACE = "event4u"
+GLOBAL_MANIFEST_REL = Path("templates") / "global-install-manifest.yml"
+
+# Per-tool global directories. Each surface gets a `rules/` and `skills/`
+# bucket under the event4u/ namespace. claude-desktop reuses claude-code's
+# ~/.claude/ (the two surfaces share the dir per Anthropic's docs).
+GLOBAL_TOOL_DIRS: dict[str, dict[str, Path]] = {
+    "claude-code": {
+        "rules":  Path.home() / ".claude" / "rules"  / GLOBAL_NAMESPACE,
+        "skills": Path.home() / ".claude" / "skills" / GLOBAL_NAMESPACE,
+    },
+    "cursor": {
+        "rules":  Path.home() / ".cursor" / "rules"  / "imported" / GLOBAL_NAMESPACE / "rules",
+        "skills": Path.home() / ".cursor" / "rules"  / "imported" / GLOBAL_NAMESPACE / "skills",
+    },
+    "windsurf": {
+        "rules":  Path.home() / ".codeium" / "windsurf" / "global_workflows" / GLOBAL_NAMESPACE / "rules",
+        "skills": Path.home() / ".codeium" / "windsurf" / "global_workflows" / GLOBAL_NAMESPACE / "skills",
+    },
+    "fallback": {
+        "rules":  Path.home() / ".config" / "agent-config" / "rules"  / GLOBAL_NAMESPACE,
+        "skills": Path.home() / ".config" / "agent-config" / "skills" / GLOBAL_NAMESPACE,
+    },
+}
+
+
+def _load_global_manifest(package_root: Path) -> dict:
+    """Parse templates/global-install-manifest.yml without a YAML dep.
+
+    Tiny hand-rolled parser — only handles the manifest's flat shape:
+    `key: value`, `- item`, and `- key: value` indented under a parent
+    list. We avoid pulling in PyYAML so install.py stays zero-dep.
+    """
+    path = package_root / GLOBAL_MANIFEST_REL
+    if not path.is_file():
+        fail(f"global manifest missing: {path}")
+    out: dict = {"kernel_rules": [], "top_skills": []}
+    section: str | None = None
+    pending: dict | None = None
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.split("#", 1)[0].rstrip()
+        if not line.strip():
+            continue
+        if line.startswith("kernel_rules:"):
+            section = "kernel_rules"; pending = None; continue
+        if line.startswith("top_skills:"):
+            section = "top_skills"; pending = None; continue
+        stripped = line.lstrip()
+        indent = len(line) - len(stripped)
+        if section == "kernel_rules" and stripped.startswith("- "):
+            out["kernel_rules"].append(stripped[2:].strip())
+        elif section == "top_skills":
+            if stripped.startswith("- id:"):
+                if pending is not None:
+                    out["top_skills"].append(pending)
+                pending = {"id": stripped.split(":", 1)[1].strip(), "surfaces": []}
+            elif pending is not None and stripped.startswith("surfaces:"):
+                raw_list = stripped.split(":", 1)[1].strip()
+                if raw_list.startswith("[") and raw_list.endswith("]"):
+                    pending["surfaces"] = [s.strip() for s in raw_list[1:-1].split(",") if s.strip()]
+            elif indent == 0 and not stripped.startswith("-"):
+                section = None
+    if pending is not None:
+        out["top_skills"].append(pending)
+    return out
+
+
+def _resolve_skill_source(package_root: Path, skill_id: str) -> Path | None:
+    """Locate a skill's SKILL.md in the package. Prefers .claude/skills/."""
+    for base in (package_root / ".claude" / "skills",
+                 package_root / ".agent-src" / "skills"):
+        candidate = base / skill_id / "SKILL.md"
+        if candidate.is_file():
+            return candidate.parent
+    return None
+
+
+def _resolve_rule_source(package_root: Path, rule_id: str) -> Path | None:
+    """Locate a rule's .md in the package. Prefers .agent-src/rules/."""
+    for base in (package_root / ".agent-src" / "rules",
+                 package_root / ".augment" / "rules"):
+        candidate = base / f"{rule_id}.md"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _global_targets(tools: set[str]) -> dict[str, dict[str, Path]]:
+    """Return the subset of GLOBAL_TOOL_DIRS to write to. Fallback always on."""
+    targets: dict[str, dict[str, Path]] = {"fallback": GLOBAL_TOOL_DIRS["fallback"]}
+    for tool_id, dirs in GLOBAL_TOOL_DIRS.items():
+        if tool_id == "fallback":
+            continue
+        # claude-desktop shares claude-code's dir — both flip the same target.
+        if tool_id == "claude-code" and ("claude-code" in tools or "claude-desktop" in tools):
+            targets[tool_id] = dirs
+        elif tool_id in tools:
+            targets[tool_id] = dirs
+    return targets
+
+
+def install_global(package_root: Path, tools: set[str], force: bool) -> int:
+    """S13/S14: ship kernel rules + curated skills to user-scope dirs."""
+    import shutil
+    manifest = _load_global_manifest(package_root)
+    targets = _global_targets(tools)
+
+    if not QUIET:
+        info(f"Global install — surfaces: {', '.join(sorted(targets))}")
+        info(f"  rules:  {len(manifest['kernel_rules'])}")
+        info(f"  skills: {len(manifest['top_skills'])}")
+
+    for surface, dirs in targets.items():
+        for kind in ("rules", "skills"):
+            dirs[kind].mkdir(parents=True, exist_ok=True)
+        # Rules: copy each kernel rule (file).
+        for rule_id in manifest["kernel_rules"]:
+            src = _resolve_rule_source(package_root, rule_id)
+            if src is None:
+                warn(f"global: rule '{rule_id}' missing in package — skipped")
+                continue
+            dst = dirs["rules"] / f"{rule_id}.md"
+            if dst.exists() and not force and dst.read_bytes() == src.read_bytes():
+                continue
+            dst.write_bytes(src.read_bytes())
+        # Skills: copy each curated skill (directory).
+        for entry in manifest["top_skills"]:
+            if surface != "fallback" and surface not in entry.get("surfaces", []):
+                continue
+            src_dir = _resolve_skill_source(package_root, entry["id"])
+            if src_dir is None:
+                warn(f"global: skill '{entry['id']}' missing in package — skipped")
+                continue
+            dst_dir = dirs["skills"] / entry["id"]
+            if dst_dir.exists() and not force:
+                shutil.rmtree(dst_dir)
+            shutil.copytree(src_dir, dst_dir)
+        if not QUIET:
+            success(f"  {surface}: {dirs['rules']}, {dirs['skills']}")
+    return 0
+
+
+def uninstall_global(tools: set[str]) -> int:
+    """S15: remove the event4u/ namespace dir from each enabled surface."""
+    import shutil
+    targets = _global_targets(tools)
+    removed: list[str] = []
+    # Collect ancestor dirs named GLOBAL_NAMESPACE so we can drop the
+    # shared parent (e.g. cursor/windsurf put rules + skills as siblings
+    # under one event4u/ dir; removing both leaves a stranded namespace
+    # dir). We never delete anything not literally named event4u/.
+    namespace_parents: set[Path] = set()
+    for surface, dirs in targets.items():
+        for kind in ("rules", "skills"):
+            d = dirs[kind]
+            if d.exists():
+                shutil.rmtree(d)
+                removed.append(str(d))
+            for ancestor in d.parents:
+                if ancestor.name == GLOBAL_NAMESPACE:
+                    namespace_parents.add(ancestor)
+    for parent in namespace_parents:
+        if parent.is_dir() and not any(parent.iterdir()):
+            parent.rmdir()
+            removed.append(str(parent))
+    if not QUIET:
+        if removed:
+            for r in removed:
+                success(f"removed {r}")
+        else:
+            skip("global uninstall: nothing to remove")
+    return 0
+
+
 # --- Argument parsing ---
 
 def parse_options(argv: list[str]) -> argparse.Namespace:
@@ -1260,14 +1443,70 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
     parser.add_argument("--project", default=None, help="project root (default: cwd or PROJECT_ROOT env)")
     parser.add_argument("--package", default=None, help="package root (default: auto-detect under project)")
     parser.add_argument("--quiet", action="store_true", help="suppress info/success output (warnings/errors still shown)")
+    parser.add_argument(
+        "--tools",
+        default="all",
+        help=(
+            "comma-separated tool IDs to install bridges for "
+            "(claude-code,cursor,windsurf,cline,gemini-cli,copilot,augment,aider,codex,all). "
+            "Default: all (backward-compatible)."
+        ),
+    )
     parser.add_argument(
         "--no-smoke",
         action="store_true",
         help="skip the post-install hook smoke test (default: dry-fire dispatch:hook against every installed bridge)",
     )
+    parser.add_argument(
+        "--global",
+        dest="global_install",
+        action="store_true",
+        help=(
+            "Phase-3 mode: ship kernel rules + curated top-N skills to user-scope "
+            "dirs (~/.claude/, ~/.cursor/, ~/.codeium/windsurf/, ~/.config/agent-config/) "
+            "so the agent has them in every project. Curation: templates/global-install-manifest.yml."
+        ),
+    )
+    parser.add_argument(
+        "--uninstall",
+        action="store_true",
+        help="With --global: remove the event4u/ namespace dir from each enabled surface.",
+    )
     return parser.parse_args(argv)
 
 
+# Mapping of --tools IDs accepted by install.py. Mirrors VALID_TOOLS in
+# scripts/install. Bridges keyed off these IDs are gated; substrate
+# bridges (vscode, augment) always run.
+_VALID_TOOLS = {
+    "claude-code", "claude-desktop", "cursor", "windsurf", "cline",
+    "gemini-cli", "copilot", "augment", "aider", "codex", "all",
+}
+
+
+def _parse_tools(raw: str) -> set[str]:
+    """Parse and validate --tools value. Returns set of normalized IDs.
+
+    "all" expands to every concrete ID. Empty input is rejected.
+    Unknown IDs raise SystemExit so the caller's message reaches stderr.
+    """
+    if not raw or not raw.strip():
+        fail("--tools requires a non-empty value")
+    items = [s.strip() for s in raw.split(",") if s.strip()]
+    if not items:
+        fail("--tools requires at least one ID")
+    unknown = [s for s in items if s not in _VALID_TOOLS]
+    if unknown:
+        fail(f"--tools: unknown ID(s): {', '.join(unknown)} (valid: {', '.join(sorted(_VALID_TOOLS))})")
+    if "all" in items:
+        return {t for t in _VALID_TOOLS if t != "all"}
+    return set(items)
+
+
+def _is_tool_enabled(tools: set[str], tool_id: str) -> bool:
+    return tool_id in tools
+
+
 # --- Main ---
 
 def main(argv: list[str]) -> int:
@@ -1300,31 +1539,52 @@ def main(argv: list[str]) -> int:
         info(f"Profile:  {opts.profile}")
         print()
 
+    # --global: short-circuits the project-bridge path. Ships kernel rules
+    # + curated skills to user-scope dirs and exits. --uninstall pairs
+    # with --global to remove the namespace dir.
+    if opts.global_install:
+        tools = _parse_tools(opts.tools)
+        if opts.uninstall:
+            return uninstall_global(tools)
+        return install_global(package_root, tools, opts.force)
+    if opts.uninstall:
+        fail("--uninstall is only valid combined with --global")
+
     ensure_agent_settings(project_root, package_root, opts.profile, opts.force)
 
+    tools = _parse_tools(opts.tools)
+
     if not opts.skip_bridges:
+        # Substrate bridges (always written; other tools symlink/depend on them).
         ensure_vscode_bridge(project_root, package_type, opts.force)
         ensure_augment_bridge(project_root, opts.force)
-        ensure_claude_bridge(project_root, opts.force)
-        ensure_cursor_bridge(project_root, opts.force)
-        ensure_cline_bridge(project_root, opts.force)
-        ensure_windsurf_bridge(project_root, opts.force)
-        ensure_gemini_bridge(project_root, opts.force)
-        ensure_copilot_bridge(project_root, opts.force)
+        # Tool-specific bridges (gated by --tools selection).
+        if _is_tool_enabled(tools, "claude-code"):
+            ensure_claude_bridge(project_root, opts.force)
+        if _is_tool_enabled(tools, "cursor"):
+            ensure_cursor_bridge(project_root, opts.force)
+        if _is_tool_enabled(tools, "cline"):
+            ensure_cline_bridge(project_root, opts.force)
+        if _is_tool_enabled(tools, "windsurf"):
+            ensure_windsurf_bridge(project_root, opts.force)
+        if _is_tool_enabled(tools, "gemini-cli"):
+            ensure_gemini_bridge(project_root, opts.force)
+        if _is_tool_enabled(tools, "copilot"):
+            ensure_copilot_bridge(project_root, opts.force)
 
     if opts.augment_user_hooks:
         ensure_augment_user_hooks(package_root, opts.force)
 
-    if opts.cursor_user_hooks:
+    if opts.cursor_user_hooks and _is_tool_enabled(tools, "cursor"):
         ensure_cursor_user_hooks(package_root, opts.force)
 
-    if opts.cline_user_hooks:
+    if opts.cline_user_hooks and _is_tool_enabled(tools, "cline"):
         ensure_cline_user_hooks(package_root, opts.force)
 
-    if opts.windsurf_user_hooks:
+    if opts.windsurf_user_hooks and _is_tool_enabled(tools, "windsurf"):
         ensure_windsurf_user_hooks(package_root, opts.force)
 
-    if opts.gemini_user_hooks:
+    if opts.gemini_user_hooks and _is_tool_enabled(tools, "gemini-cli"):
         ensure_gemini_user_hooks(package_root, opts.force)
 
     if not opts.skip_bridges and not opts.no_smoke:

package/scripts/install.sh

@@ -37,10 +37,26 @@ DRY_RUN=false
 VERBOSE=false
 QUIET=false
 SKIP_GITIGNORE=false
+# Comma-separated tool IDs (default: all). Set by --tools or the
+# orchestrator (scripts/install). The .augment/ substrate is always
+# synced because every other tool symlinks back into it.
+TOOLS="all"
 # Resolved from <TARGET>/.agent-settings.yml in resolve_settings(); when
 # true, .augment/rules/ files are symlinked instead of copied.
 USE_RULES_SYMLINKS=false
 
+# Return 0 if a tool ID is enabled by the current --tools selection.
+# "all" matches everything; otherwise match the comma list exactly.
+is_tool_enabled() {
+    local id="$1"
+    [[ "$TOOLS" == "all" ]] && return 0
+    case ",$TOOLS," in
+        *,"$id",*) return 0 ;;
+        *,all,*)   return 0 ;;
+    esac
+    return 1
+}
+
 # --- Logging ---
 log_info()    { $QUIET || echo "  ✅  $*"; }
 log_warn()    { $QUIET || echo "  ⚠️  $*" >&2; }
@@ -57,11 +73,15 @@ parse_args() {
             --verbose) VERBOSE=true; shift ;;
             --quiet)   QUIET=true; shift ;;
             --skip-gitignore) SKIP_GITIGNORE=true; shift ;;
+            --tools)   TOOLS="$2"; shift 2 ;;
+            --tools=*) TOOLS="${1#*=}"; shift ;;
             --help|-h) show_help; exit 0 ;;
             *) log_error "Unknown argument: $1"; show_help; exit 1 ;;
         esac
     done
 
+    [[ -z "$TOOLS" ]] && TOOLS="all"
+
     # Auto-detect source: directory where this script lives (../  = package root)
     if [[ -z "$SOURCE_DIR" ]]; then
         SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -106,6 +126,10 @@ Syncs agent-config to target project. Copies rules, symlinks everything else.
 Options:
   --source <dir>   Package source directory (default: auto-detect from script location)
   --target <dir>   Target project root (default: $PROJECT_ROOT or cwd)
+  --tools <list>   Comma-separated tool IDs (default: all). Filters tool-specific
+                   payload (.claude/, .cursor/, .clinerules/, .windsurfrules,
+                   GEMINI.md, copilot-instructions.md). The .augment/ substrate
+                   and AGENTS.md are always written.
   --dry-run        Show what would happen without making changes
   --verbose        Show detailed output
   --quiet          Suppress all output except errors
@@ -409,15 +433,25 @@ clean_stale() {
 }
 
 
-# Create tool-specific rule symlinks
+# Create tool-specific rule symlinks (filtered by --tools selection).
+# Map: tool ID → (target dir, relative prefix from target → .augment/rules).
 create_tool_symlinks() {
     local project_root="$1"
     local rules_dir="$project_root/.augment/rules"
 
     [[ -d "$rules_dir" ]] || return
 
-    local -a tool_dirs=(".claude/rules" ".cursor/rules" ".clinerules")
-    local -a rel_prefixes=("../../.augment/rules" "../../.augment/rules" "../.augment/rules")
+    local -a tool_ids=()
+    local -a tool_dirs=()
+    local -a rel_prefixes=()
+    is_tool_enabled "claude-code" && { tool_ids+=("claude-code"); tool_dirs+=(".claude/rules");  rel_prefixes+=("../../.augment/rules"); }
+    is_tool_enabled "cursor"      && { tool_ids+=("cursor");      tool_dirs+=(".cursor/rules");  rel_prefixes+=("../../.augment/rules"); }
+    is_tool_enabled "cline"       && { tool_ids+=("cline");       tool_dirs+=(".clinerules");    rel_prefixes+=("../.augment/rules"); }
+
+    if [[ ${#tool_dirs[@]} -eq 0 ]]; then
+        log_verbose "no tool rule directories selected (--tools=$TOOLS)"
+        return 0
+    fi
 
     local count=0
     for i in "${!tool_dirs[@]}"; do
@@ -467,15 +501,16 @@ create_tool_symlinks() {
         done
     done
 
-    log_info "Created $count rule symlinks across ${#tool_dirs[@]} tool directories"
+    log_info "Created $count rule symlinks across ${#tool_dirs[@]} tool directories (${tool_ids[*]})"
 }
 
-# Create .claude/skills/ directory symlinks
+# Create .claude/skills/ directory symlinks (claude-code only).
 create_skill_symlinks() {
     local project_root="$1"
     local skills_dir="$project_root/.augment/skills"
 
     [[ -d "$skills_dir" ]] || return
+    is_tool_enabled "claude-code" || { log_verbose "skip .claude/skills/ (claude-code not selected)"; return 0; }
 
     local target_dir="$project_root/.claude/skills"
     mkdir -p "$target_dir"
@@ -528,6 +563,7 @@ generate_windsurfrules() {
     local rules_dir="$project_root/.augment/rules"
 
     [[ -d "$rules_dir" ]] || return
+    is_tool_enabled "windsurf" || { log_verbose "skip .windsurfrules (windsurf not selected)"; return 0; }
 
     local output="$project_root/.windsurfrules"
     local count=0
@@ -561,11 +597,13 @@ generate_windsurfrules() {
 }
 
 
-# Create GEMINI.md symlink
+# Create GEMINI.md symlink (gemini-cli only).
 create_gemini_md() {
     local project_root="$1"
     local link="$project_root/GEMINI.md"
 
+    is_tool_enabled "gemini-cli" || { log_verbose "skip GEMINI.md (gemini-cli not selected)"; return 0; }
+
     if [[ -L "$link" ]] || [[ -f "$link" ]]; then
         return  # Don't overwrite
     fi
@@ -726,8 +764,15 @@ main() {
     #    own root AGENTS.md / copilot-instructions.md — those are meta docs
     #    about the package itself and would leak package-specific content
     #    into consumer projects.
+    #    AGENTS.md is the universal cross-tool contract (aider, codex, claude,
+    #    etc.) and is always written. copilot-instructions.md is gated on the
+    #    copilot tool selection.
     copy_if_missing "$SOURCE_PAYLOAD/templates/AGENTS.md" "$TARGET_DIR/AGENTS.md"
-    copy_if_missing "$SOURCE_PAYLOAD/templates/copilot-instructions.md" "$TARGET_DIR/.github/copilot-instructions.md"
+    if is_tool_enabled "copilot"; then
+        copy_if_missing "$SOURCE_PAYLOAD/templates/copilot-instructions.md" "$TARGET_DIR/.github/copilot-instructions.md"
+    else
+        log_verbose "skip .github/copilot-instructions.md (copilot not selected)"
+    fi
 
     # 3. Create tool-specific symlinks
     create_tool_symlinks "$TARGET_DIR"

package/scripts/lint_orchestration_dsl.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Lint `.agent-config/orchestrations/*.yaml` pipeline files.
+
+CI gate for the orchestration DSL contract
+(`docs/contracts/orchestration-dsl-v1.md`). Hard-fails on:
+
+- missing or malformed top-level keys
+  (`schema_version`, `name`, `description`, `steps`)
+- `schema_version != 1`
+- `name` not matching `[a-z][a-z0-9-]*` or not matching the filename
+- duplicate `steps[].id`
+- `steps[].kind` outside the enum (`skill` / `command` / `persona` /
+  `subagent`)
+- `steps[].ref` pointing at a non-existent target on disk
+- `${{ ... }}` reference to an unknown input or step id
+- `steps[]` length outside [1, 32]
+- `outputs` referencing an unknown step
+
+Exit codes mirror `lint_hook_manifest.py`:
+  0 — clean
+  1 — at least one hard failure
+  2 — file or schema-load error
+
+Invocation:
+
+    python3 scripts/lint_orchestration_dsl.py [--dir PATH] [--file PATH]
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_DIR = REPO_ROOT / ".agent-config" / "orchestrations"
+
+NAME_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+STEP_ID_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+INTERP_RE = re.compile(r"\$\{\{\s*(inputs|steps)\.([a-z0-9_-]+)(?:\.output)?\s*\}\}")
+
+VALID_KINDS = {"skill", "command", "persona", "subagent"}
+MAX_STEPS = 32
+MIN_STEPS = 1
+
+# Subagent-orchestration modes — kept in lock-step with
+# .agent-src.uncompressed/skills/subagent-orchestration/SKILL.md.
+SUBAGENT_MODES = {
+    "do-and-judge", "do-and-judge-two-stage",
+    "do-in-steps", "do-in-parallel", "do-in-worktrees",
+    "do-competitively", "judge-with-debate",
+}
+
+
+def _load_yaml(path: Path) -> object:
+    """Reuse the dispatcher's loader so the linter sees what the
+    runtime sees — fallback parser when PyYAML is not installed."""
+    sys.path.insert(0, str(REPO_ROOT / "scripts"))
+    from hooks.dispatch_hook import _load_yaml as _load  # noqa: E402
+    return _load(path)
+
+
+def _ref_exists(kind: str, ref: str) -> bool:
+    if kind == "skill":
+        return (REPO_ROOT / ".agent-src.uncompressed" / "skills" / ref / "SKILL.md").is_file()
+    if kind == "command":
+        return (REPO_ROOT / ".agent-src.uncompressed" / "commands" / f"{ref}.md").is_file()
+    if kind == "persona":
+        return (REPO_ROOT / ".agent-src.uncompressed" / "personas" / f"{ref}.md").is_file()
+    if kind == "subagent":
+        return ref in SUBAGENT_MODES
+    return False
+
+
+def _walk_interpolations(value: object):
+    """Yield (namespace, ident) tuples for every ${{ ns.ident }} in the
+    nested value (dict / list / str)."""
+    if isinstance(value, str):
+        for match in INTERP_RE.finditer(value):
+            yield match.group(1), match.group(2)
+    elif isinstance(value, dict):
+        for v in value.values():
+            yield from _walk_interpolations(v)
+    elif isinstance(value, list):
+        for v in value:
+            yield from _walk_interpolations(v)
+
+
+def _check_unknown_namespaces(value: object, path: str, errors: list[str]) -> None:
+    if isinstance(value, str):
+        for match in re.finditer(r"\$\{\{\s*([a-z]+)\.", value):
+            if match.group(1) not in ("inputs", "steps"):
+                errors.append(f"{path}: unknown interpolation namespace '{match.group(1)}'")
+    elif isinstance(value, dict):
+        for k, v in value.items():
+            _check_unknown_namespaces(v, f"{path}.{k}", errors)
+    elif isinstance(value, list):
+        for i, v in enumerate(value):
+            _check_unknown_namespaces(v, f"{path}[{i}]", errors)
+
+
+def _check_steps(doc: dict, input_ids: set[str], errors: list[str]) -> set[str]:
+    steps = doc.get("steps")
+    if not isinstance(steps, list) or not (MIN_STEPS <= len(steps) <= MAX_STEPS):
+        errors.append(f"steps: must be a list of {MIN_STEPS}–{MAX_STEPS} entries")
+        return set()
+    step_ids: set[str] = set()
+    for i, step in enumerate(steps):
+        if not isinstance(step, dict):
+            errors.append(f"steps[{i}]: must be a mapping")
+            continue
+        sid = step.get("id")
+        if not isinstance(sid, str) or not STEP_ID_RE.match(sid):
+            errors.append(f"steps[{i}].id: must be snake-case identifier")
+            continue
+        if sid in step_ids:
+            errors.append(f"steps[{i}].id: duplicate id '{sid}'")
+            continue
+        step_ids.add(sid)
+        kind = step.get("kind")
+        ref = step.get("ref")
+        if kind not in VALID_KINDS:
+            errors.append(f"steps.{sid}.kind: must be one of {sorted(VALID_KINDS)}")
+            continue
+        if not isinstance(ref, str) or not _ref_exists(kind, ref):
+            errors.append(f"steps.{sid}.ref: {kind} '{ref}' not found on disk")
+        _check_unknown_namespaces(step.get("with"), f"steps.{sid}.with", errors)
+        for ns, ident in _walk_interpolations(step.get("with") or {}):
+            if ns == "inputs" and ident not in input_ids:
+                errors.append(f"steps.{sid}.with: unknown input '{ident}'")
+            if ns == "steps" and ident not in step_ids - {sid}:
+                errors.append(f"steps.{sid}.with: unknown step '{ident}' (forward ref or self)")
+    return step_ids
+
+
+
+def _check_outputs(doc: dict, step_ids: set[str], input_ids: set[str], errors: list[str]) -> None:
+    outputs = doc.get("outputs")
+    if outputs is None:
+        return
+    if not isinstance(outputs, dict):
+        errors.append("outputs: must be a mapping")
+        return
+    for name, value in outputs.items():
+        for ns, ident in _walk_interpolations(value):
+            if ns == "steps" and ident not in step_ids:
+                errors.append(f"outputs.{name}: unknown step '{ident}'")
+            if ns == "inputs" and ident not in input_ids:
+                errors.append(f"outputs.{name}: unknown input '{ident}'")
+
+
+def _check_inputs(doc: dict, errors: list[str]) -> set[str]:
+    inputs = doc.get("inputs") or []
+    if not isinstance(inputs, list):
+        errors.append("inputs: must be a list")
+        return set()
+    ids: set[str] = set()
+    for i, inp in enumerate(inputs):
+        if not isinstance(inp, dict) or not isinstance(inp.get("id"), str):
+            errors.append(f"inputs[{i}]: must be a mapping with string 'id'")
+            continue
+        if inp["id"] in ids:
+            errors.append(f"inputs[{i}].id: duplicate id '{inp['id']}'")
+        ids.add(inp["id"])
+    return ids
+
+
+def lint(path: Path) -> int:
+    try:
+        doc = _load_yaml(path)
+    except Exception as exc:
+        sys.stderr.write(f"lint_orchestration_dsl: load error: {exc}\n")
+        return 2
+    if not isinstance(doc, dict):
+        sys.stderr.write(f"{path}: top-level must be a mapping\n")
+        return 1
+
+    errors: list[str] = []
+    if doc.get("schema_version") != 1:
+        errors.append("schema_version: must be 1")
+    name = doc.get("name")
+    if not isinstance(name, str) or not NAME_RE.match(name):
+        errors.append("name: must be kebab-case starting with a letter")
+    elif name != path.stem:
+        errors.append(f"name: '{name}' must match filename stem '{path.stem}'")
+    if not isinstance(doc.get("description"), str) or not doc["description"].strip():
+        errors.append("description: must be a non-empty string")
+
+    input_ids = _check_inputs(doc, errors)
+    step_ids = _check_steps(doc, input_ids, errors)
+    _check_outputs(doc, step_ids, input_ids, errors)
+
+    for e in errors:
+        sys.stderr.write(f"error: {path}: {e}\n")
+    return 1 if errors else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--dir", type=Path, default=DEFAULT_DIR)
+    parser.add_argument("--file", type=Path, default=None)
+    args = parser.parse_args(argv)
+    if args.file is not None:
+        return lint(args.file)
+    if not args.dir.is_dir():
+        return 0  # opt-in directory; absence is not a failure
+    rc = 0
+    for path in sorted(args.dir.glob("*.yaml")):
+        rc = max(rc, lint(path))
+    return rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())