@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/lint_agent_skill_names.py

@@ -1,150 +0,0 @@
-#!/usr/bin/env python3
-"""Agent-Skills name-compliance linter (2026-06 Zed fix).
-
-Strict Agent-Skills consumers (Zed, Anthropic skill validators) require a
-skill `name:` to (a) match ``^[a-z0-9]+(-[a-z0-9]+)*$`` (lowercase letters,
-digits, single hyphens; no leading/trailing/double hyphen), (b) be at most
-64 characters, and (c) equal the directory name the SKILL.md lives in.
-Colon-namespaced command names (``council:default``) used to leak into every
-skill-shaped projection (``.claude/skills/``, global ``<anchor>/skills/``
-deploys) and made Zed reject the entries with *"Skill name must contain only
-lowercase letters, numbers, and hyphens"*.
-
-Two checks, both blocking:
-
-1. **Commands** — every ``src/domains/<pack>/<subpath>/command.md`` carries
-   ``name:`` equal to the canonical path-derived hyphen slug
-   (``_lib.agent_src.command_slug``). The slug is what condense.py uses as
-   the ``.claude/skills/<slug>/`` directory, so name==slug guarantees the
-   projected SKILL.md satisfies (c) by construction.
-2. **Skills** — every ``src/skills/<dir>/SKILL.md`` carries ``name:`` equal
-   to ``<dir>`` and matching the Agent-Skills pattern.
-
-Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
-
-Usage:
-    python3 src/scripts/lint_agent_skill_names.py
-    python3 src/scripts/lint_agent_skill_names.py --quiet
-"""
-
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from pathlib import Path
-
-SCRIPTS_DIR = Path(__file__).resolve().parent
-sys.path.insert(0, str(SCRIPTS_DIR))
-
-from _lib.agent_src import command_slug  # noqa: E402
-
-ROOT = SCRIPTS_DIR.parent.parent
-SRC_DOMAINS = ROOT / "src" / "domains"
-SRC_SKILLS = ROOT / "src" / "skills"
-
-# Agent-Skills spec name shape (Zed enforces this verbatim; Claude Code is
-# lenient today but the spec is the contract): lowercase letters, digits,
-# single hyphens, no leading/trailing hyphen, 1-64 chars.
-NAME_PATTERN = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
-MAX_NAME_LEN = 64
-
-NAME_RE = re.compile(r"^name:\s*(.*)$", re.MULTILINE)
-
-
-def _frontmatter_name(path: Path) -> str | None:
-    text = path.read_text(encoding="utf-8")
-    if not text.startswith("---"):
-        return None
-    end = text.find("\n---", 3)
-    block = text[3:end] if end != -1 else text
-    m = NAME_RE.search(block)
-    return m.group(1).strip().strip('"').strip("'") if m else None
-
-
-def _spec_violation(name: str) -> str | None:
-    if len(name) > MAX_NAME_LEN:
-        return f"longer than {MAX_NAME_LEN} chars"
-    if not NAME_PATTERN.match(name):
-        return ("must contain only lowercase letters, numbers, and single "
-                "hyphens (no leading/trailing/double hyphen, no `:`)")
-    return None
-
-
-def check_commands() -> list[str]:
-    violations: list[str] = []
-    if not SRC_DOMAINS.is_dir():
-        return violations
-    for md in sorted(SRC_DOMAINS.rglob("command.md")):
-        slug = command_slug(md)
-        if slug is None:
-            continue
-        rel = md.relative_to(ROOT)
-        name = _frontmatter_name(md)
-        if not name:
-            violations.append(f"{rel}: missing `name:` frontmatter")
-            continue
-        spec = _spec_violation(name)
-        if spec:
-            violations.append(f"{rel}: name `{name}` {spec}")
-        if name != slug:
-            violations.append(
-                f"{rel}: name `{name}` != path-derived slug `{slug}` — "
-                f"the slug is the `.claude/skills/` directory name; they "
-                f"must match so strict Agent-Skills consumers (Zed) accept "
-                f"the projected SKILL.md"
-            )
-    return violations
-
-
-def check_skills() -> list[str]:
-    violations: list[str] = []
-    if not SRC_SKILLS.is_dir():
-        return violations
-    for skill_dir in sorted(p for p in SRC_SKILLS.iterdir() if p.is_dir()):
-        md = skill_dir / "SKILL.md"
-        if not md.is_file():
-            continue
-        rel = md.relative_to(ROOT)
-        dirname = skill_dir.name
-        spec = _spec_violation(dirname)
-        if spec:
-            violations.append(f"{rel}: directory `{dirname}` {spec}")
-        name = _frontmatter_name(md)
-        if not name:
-            violations.append(f"{rel}: missing `name:` frontmatter")
-            continue
-        if name != dirname:
-            violations.append(
-                f"{rel}: name `{name}` != directory `{dirname}` — Zed "
-                f"requires the folder name to match the `name:` field"
-            )
-    return violations
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("--quiet", action="store_true")
-    args = ap.parse_args()
-
-    try:
-        violations = check_commands() + check_skills()
-    except OSError as exc:
-        print(f"❌  lint-skill-names internal error: {exc}", file=sys.stderr)
-        return 3
-
-    if violations:
-        print(f"❌  {len(violations)} Agent-Skills name violation(s):")
-        for v in violations:
-            print(f"  • {v}")
-        print("\nNames must be the path-derived hyphen slug "
-              "(command.schema.json `name` pattern; 2026-06 Zed fix).")
-        return 1
-    if not args.quiet:
-        print("✅  All command + skill names are Agent-Skills-spec compliant "
-              "(hyphen slugs, name == directory/slug).")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/lint_agents_layout.py

@@ -1,197 +0,0 @@
-#!/usr/bin/env python3
-"""CI guard for the `agents/` top-level layout.
-
-The `agents/` tree is the project boundary for memory, roadmaps,
-runtime artefacts, settings, audits, and policies. Flat files at the
-`agents/` root are restricted to a small, intentional whitelist —
-everything else lives in a typed subdirectory (`runtime/`, `settings/`,
-`audits/`, `roadmaps/`, `policies/`, `contexts/`, etc.).
-
-Two layout tiers:
-
-  MAINTAINER (this source repo, identified by ``.agent-src.uncondensed/``)
-      Full `agents/` tree allowed — only the flat-file whitelist is
-      enforced. Phase 4 of road-to-global-only-install keeps the
-      maintainer surface unchanged.
-
-  CONSUMER (any repo without ``.agent-src.uncondensed/``)
-      Global-only target shape: `agents/overrides/` + the bridge
-      marker `agents/.event4u-bridge.yml` are the **only** expected
-      artefacts. Anything else surfaces as a WARNING with a pointer
-      to ``agent-config settings migrate`` (exit code 0). Hard
-      violations (unknown flat files at the root) still fail.
-
-Exit codes:
-  0 — layout is clean (warnings ok in consumer mode).
-  1 — at least one UNKNOWN flat-file violation.
-
-Invocation (from project root):
-  python3 scripts/lint_agents_layout.py
-  python3 scripts/lint_agents_layout.py --quiet
-  python3 scripts/lint_agents_layout.py --strict   # warnings → errors
-"""
-
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-AGENTS_ROOT = Path("agents")
-
-# Intentional flat files at agents/ root. Anything not in this set is
-# UNKNOWN (linter failure). Durable records live under typed subdirs:
-# decisions/ (low-impact corpus, ADR-style records), evidence/ (durable
-# reports / metrics / council artefacts), runtime/ (volatile, gitignored).
-ALLOWED_FLAT_FILES: frozenset[str] = frozenset(
-    {
-        # Entry document — narrative pointer to the agents/ tree.
-        "index.md",
-        # D1 anchor / progress dashboard — kept at root by the
-        # roadmap-progress-sync rule so consumers see it first.
-        "roadmaps-progress.md",
-        # Empty-tree sentinel so agents/ survives a fresh checkout
-        # before any runtime artefact lands.
-        ".gitkeep",
-        # Consumer bridge marker (Phase 4 of road-to-global-only-install).
-        # Spec: docs/contracts/consumer-bridge.md (event4u-bridge/v1).
-        ".event4u-bridge.yml",
-        # Per-tool projection toggle — which generated trees
-        # `task generate-tools` writes (`.claude/`, `.cursor/`,
-        # `.clinerules/`, `.windsurfrules`). Lives at agents/ root
-        # because both the package and the consumer generators read
-        # it before any subdirectory is touched (ADR-028 § Root layout
-        # toggle).
-        ".agent-tools.yml",
-        # Dual-role marker (ADR-053). Names, at the directory itself, that
-        # this agents/ tree is BOTH the maintainer workspace AND a dogfooded
-        # instance of the consumer convention. Intentionally a root-level
-        # flat file — it marks the directory, so a typed subdirectory would
-        # defeat its purpose. Spec: agents/.maintainer-workspace.md.
-        ".maintainer-workspace.md",
-    }
-)
-
-# Consumer-target layout: only these top-level entries are expected in
-# the global-only world. Anything else is a WARNING in consumer mode.
-CONSUMER_EXPECTED_ENTRIES: frozenset[str] = frozenset(
-    {"overrides", ".event4u-bridge.yml", ".gitkeep"},
-)
-
-MIGRATE_HINT = (
-    "Run `npx @event4u/agent-config migrate` to sweep legacy project-scope "
-    "artefacts in one pass. The unified `migrate` command (see "
-    "`docs/contracts/migrate-command.md`) leaves `agents/overrides/` + "
-    "`agents/.event4u-bridge.yml` as the only consumer-side files; the "
-    "wizard recreates fresh config on `agent-config setup`."
-)
-
-
-def is_source_repo(project_root: Path) -> bool:
-    """True when running inside the agent-config source repo.
-
-    The maintainer surface is identified by **any** of:
-      - ``.agent-src.uncondensed/`` at the workspace root (legacy / single-pack layout),
-      - ``packages/<pack>/.agent-src.uncondensed/`` (current monorepo layout — see ``AGENTS.md``),
-      - ``dist/agent-src/`` at the workspace root (condensed authoring tree).
-
-    Consumer repos ship none of these — they only carry the deployed
-    `.augment/`, `.claude/`, etc. plus `agents/overrides/`.
-    """
-    if (project_root / ".agent-src.uncondensed").is_dir():
-        return True
-    if (project_root / "dist/agent-src").is_dir():
-        return True
-    packages = project_root / "packages"
-    if packages.is_dir():
-        for sub in packages.iterdir():
-            if (sub / ".agent-src.uncondensed").is_dir():
-                return True
-    return False
-
-
-def find_violations(root: Path) -> list[str]:
-    """Return UNKNOWN flat-file violations at the agents/ root."""
-    unknown: list[str] = []
-    if not root.is_dir():
-        return unknown
-
-    for path in sorted(root.iterdir()):
-        if not path.is_file():
-            continue
-        name = path.name
-        if name in ALLOWED_FLAT_FILES:
-            continue
-        unknown.append(
-            f"{path}: flat file not in agents/ whitelist — move to a typed "
-            f"subdirectory (runtime/, evidence/, decisions/, settings/, "
-            f"audits/, roadmaps/, policies/, contexts/, …) or add to "
-            f"ALLOWED_FLAT_FILES in scripts/lint_agents_layout.py with "
-            f"rationale."
-        )
-
-    return unknown
-
-
-def find_consumer_warnings(root: Path) -> list[str]:
-    """Return WARNINGs for consumer repos that hold legacy artefacts.
-
-    Consumer-target shape (Phase 4 of road-to-global-only-install):
-    `agents/overrides/` + `agents/.event4u-bridge.yml` are the only
-    expected entries. Anything else is a soft warning — the linter
-    still exits 0, but the message points the user at the migration
-    subcommand so the legacy directory can be reclaimed.
-    """
-    warnings: list[str] = []
-    if not root.is_dir():
-        return warnings
-
-    for path in sorted(root.iterdir()):
-        if path.name in CONSUMER_EXPECTED_ENTRIES:
-            continue
-        # Flat-file UNKNOWNs are already an error — don't double-count.
-        if path.is_file() and path.name not in ALLOWED_FLAT_FILES:
-            continue
-        kind = "dir" if path.is_dir() else "file"
-        warnings.append(f"{path} ({kind}): legacy artefact outside the consumer-target shape.")
-
-    return warnings
-
-
-def main() -> int:
-    args = sys.argv[1:]
-    strict = "--strict" in args
-    quiet = "--quiet" in args
-
-    project_root = Path.cwd()
-    unknown = find_violations(AGENTS_ROOT)
-    consumer_mode = not is_source_repo(project_root)
-    warnings = find_consumer_warnings(AGENTS_ROOT) if consumer_mode else []
-
-    if unknown:
-        print("❌  agents/ layout violations (unknown flat files):\n")
-        for f in unknown:
-            print(f"  - {f}")
-        print(
-            "\nRule: scripts/lint_agents_layout.py — flat files at agents/ "
-            "root must be whitelisted. Typed subdirectories: runtime/, "
-            "evidence/, decisions/, settings/, audits/, roadmaps/, "
-            "policies/, contexts/, … ."
-        )
-        return 1
-
-    if warnings:
-        if not quiet:
-            print("⚠️  agents/ consumer-shape warnings:\n")
-            for w in warnings:
-                print(f"  - {w}")
-            print(f"\n{MIGRATE_HINT}")
-        if strict:
-            return 1
-
-    if not unknown and not warnings and not quiet:
-        print("✅  agents/ layout clean.")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/lint_agents_md.py

@@ -1,210 +0,0 @@
-#!/usr/bin/env python3
-"""Thin-Root contract linter for AGENTS.md files (Phase 7).
-
-Enforces caps + pointer-ratio + pointer-anatomy + emergency-triage
-contract from `.agent-src.uncondensed/skills/agents-md-thin-root/SKILL.md`:
-
-  (a) total char-count under FAIL/WARN budgets per file class
-  (b) substantive-pointer ratio >= 0.40
-  (c) every pointer's *why* clause >= 60 chars
-  (d) every pointer target resolves on disk (anchor validity)
-  (e) emergency-triage section present with the five canonical questions
-  (f) path-enumeration WARN — bare `path/` bullets without a *why*
-      clause and without a markdown link signal Capability-over-Structure
-      drift; >= 3 such lines emits a WARN (not FAIL).
-
-Exit non-zero on any (a) FAIL, (b)–(e) error. WARN is informational.
-"""
-from __future__ import annotations
-
-import re
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent.parent
-sys.path.insert(0, str(ROOT / "src" / "scripts"))
-from _lib.agent_src import SRC_AGENT  # noqa: E402
-
-QUIET = "--quiet" in sys.argv
-
-# 6.0.x: the uncondensed source container moved from
-# packages/core/.agent-src.uncondensed/ to src/agent-src/ (ADR-051).
-_CONSUMER_TEMPLATE = SRC_AGENT / "templates" / "AGENTS.md"
-# Enforced source target — read by scripts/check_gate_paths.py so a future move
-# that desyncs this path fails CI instead of silently no-opping. Only the
-# consumer-template lives under the source container; the package-root AGENTS.md
-# sits at the repo root and is intentionally excluded.
-GATE_CORE_PATHS = (_CONSUMER_TEMPLATE,)
-
-LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
-PATH_BACKTICK_RE = re.compile(r"`[^`]*/[^`]*`")
-BULLET_RE = re.compile(r"^\s*[-*+]\s+")
-PATH_ENUM_THRESHOLD = 3
-TRIAGE_KEYWORDS = (
-    "what is this repo",
-    "what language",
-    "where do i edit",
-    "lint / test / sync",
-    "where do the always",
-)
-
-
-def _is_path_enumeration(line: str) -> bool:
-    """A bullet line with a backticked path-like token and no link.
-
-    These lines describe **where** a file lives without explaining
-    **why** the agent should care — the Capabilities-over-Structure
-    Iron Law forbids them in AGENTS.md. We accept up to two such
-    lines (illustration / contrast); >= 3 = warn.
-    """
-    if not BULLET_RE.match(line):
-        return False
-    if LINK_RE.search(line):
-        return False
-    return bool(PATH_BACKTICK_RE.search(line))
-
-
-@dataclass
-class Target:
-    path: Path
-    label: str
-    fail_at: int
-    warn_at: int
-    template: bool  # consumer template — relax pointer-target resolution
-
-
-TARGETS = [
-    Target(ROOT / "AGENTS.md", "package-root", 3000, 2800, template=False),
-    Target(_CONSUMER_TEMPLATE, "consumer-template", 2500, 2300, template=True),
-]
-
-
-def _strip_links(line: str) -> str:
-    return LINK_RE.sub(lambda m: m.group(1), line)
-
-
-def _resolve(target_str: str, template: bool) -> bool:
-    raw = target_str.split("#", 1)[0].strip()
-    if raw.startswith("http://") or raw.startswith("https://"):
-        return True
-    candidates = [ROOT / raw]
-    if template and raw.startswith(".augment/"):
-        candidates.append(ROOT / raw.replace(".augment/", ".agent-src.uncondensed/", 1))
-        candidates.append(ROOT / raw.replace(".augment/", "dist/agent-src/", 1))
-    if raw.startswith("dist/agent-src/"):
-        candidates.append(ROOT / raw.replace("dist/agent-src/", ".agent-src.uncondensed/", 1))
-    return any(c.exists() for c in candidates)
-
-
-def lint_file(t: Target) -> tuple[bool, list[str], list[str]]:
-    """Return (ok, errors, warnings)."""
-    errors: list[str] = []
-    warnings: list[str] = []
-    if not t.path.exists():
-        return False, [f"{t.label}: {t.path} not found"], []
-
-    text = t.path.read_text(encoding="utf-8")
-    size = len(text.encode("utf-8"))
-
-    # (a) size
-    if size > t.fail_at:
-        errors.append(f"{t.label}: {size} chars > FAIL cap {t.fail_at}")
-    elif size > t.warn_at:
-        warnings.append(f"{t.label}: {size} chars > WARN cap {t.warn_at}")
-
-    # Filter out structural lines that are not "prose" the contract
-    # asks us to replace with pointers: headings, code fences + content,
-    # HTML comments, and Markdown table rows.
-    lines = text.splitlines()
-    in_fence = False
-    in_comment = False
-    prose: list[str] = []
-    for ln in lines:
-        s = ln.strip()
-        if not s:
-            continue
-        if s.startswith("```"):
-            in_fence = not in_fence
-            continue
-        if in_fence:
-            continue
-        if "<!--" in s:
-            in_comment = True
-        if in_comment:
-            if "-->" in s:
-                in_comment = False
-            continue
-        if s.startswith("#"):  # heading
-            continue
-        if s.startswith("|"):  # markdown table row / separator
-            continue
-        prose.append(ln)
-
-    non_blank = prose
-    pointer_lines = 0
-    path_enum_lines: list[str] = []
-
-    for ln in non_blank:
-        if _is_path_enumeration(ln):
-            path_enum_lines.append(ln.strip())
-        m = LINK_RE.search(ln)
-        if not m:
-            continue
-        target = m.group(2)
-        # (d) target resolves
-        if not _resolve(target, t.template):
-            errors.append(f"{t.label}: broken pointer target `{target}` in line: {ln.strip()[:100]}")
-        # (c) why-clause length: line minus link syntax
-        why = _strip_links(ln).strip()
-        if len(why) >= 60:
-            pointer_lines += 1
-        # else line has a link but no real why-clause — does not count
-
-    # (b) ratio
-    ratio = pointer_lines / max(len(non_blank), 1)
-    if ratio < 0.40:
-        errors.append(
-            f"{t.label}: substantive-pointer ratio {ratio:.2f} < 0.40 "
-            f"({pointer_lines}/{len(non_blank)} non-blank lines)"
-        )
-
-    # (f) path-enumeration WARN
-    if len(path_enum_lines) >= PATH_ENUM_THRESHOLD:
-        sample = path_enum_lines[0][:80]
-        warnings.append(
-            f"{t.label}: {len(path_enum_lines)} path-enumeration lines "
-            f"(>= {PATH_ENUM_THRESHOLD}) — Capabilities-over-Structure drift; "
-            f"first: {sample!r}"
-        )
-
-    # (e) emergency-triage block
-    lower = text.lower()
-    missing = [k for k in TRIAGE_KEYWORDS if k not in lower]
-    if missing:
-        errors.append(f"{t.label}: emergency-triage block missing keywords: {missing}")
-    if "emergency triage" not in lower:
-        errors.append(f"{t.label}: missing 'Emergency triage' section heading")
-
-    return not errors, errors, warnings
-
-
-def main() -> int:
-    rc = 0
-    for t in TARGETS:
-        ok, errors, warnings = lint_file(t)
-        if not QUIET or errors or warnings:
-            print(f"== {t.label} ({t.path.relative_to(ROOT)}) ==")
-        for w in warnings:
-            print(f"  ⚠️  {w}")
-        for e in errors:
-            print(f"  ❌  {e}")
-        if ok and not warnings and not QUIET:
-            print(f"  ✅  ok ({t.path.stat().st_size} bytes)")
-        if not ok:
-            rc = 1
-    return rc
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())