@event4u/agent-config 1.33.0 → 1.35.0

package/scripts/_emit_domain_table.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Emit the per-domain skill list as Markdown for skill-domains.md § 4."""
+from __future__ import annotations
+
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _backfill_skill_domains import SKILL_DOMAIN_MAP  # noqa: E402
+
+ORDER = ["engineering", "product", "quality", "devops", "process", "discovery"]
+
+
+def main() -> int:
+    by_domain: dict[str, list[str]] = defaultdict(list)
+    for slug, dom in SKILL_DOMAIN_MAP.items():
+        by_domain[dom].append(slug)
+
+    lines: list[str] = []
+    total = 0
+    for dom in ORDER:
+        skills = sorted(by_domain[dom])
+        total += len(skills)
+        lines.append(f"### {dom} ({len(skills)})")
+        lines.append("")
+        lines.append(", ".join(f"`{s}`" for s in skills))
+        lines.append("")
+    lines.append(f"**Total: {total} skills.**")
+    print("\n".join(lines))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install-hooks.sh

@@ -13,14 +13,31 @@ mkdir -p "$HOOKS_DIR"
 cat > "$HOOKS_DIR/pre-push" << 'EOF'
 #!/usr/bin/env bash
 # Pre-push hook: verify .agent-src/ is in sync with .agent-src.uncompressed/
+# and that the canonical command count matches README + getting-started docs.
+#
+# The command-count gate exists because three consecutive PRs landed
+# post-CI count-drift fixes (e.g. f2fb0026 "bump command count
+# 101→103"). Catching the drift pre-push stops it from flooding remote
+# CI. Runtime ~0.1s.
+
+fail=0
 
 echo "🔍 Checking .agent-src/ sync..."
-python3 scripts/compress.py --check
+if ! python3 scripts/compress.py --check; then
+    echo "❌  .agent-src/ is out of sync. Run 'task sync' and compress changed .md files, then commit."
+    fail=1
+fi
+
+echo "🔍 Checking command count messaging..."
+if ! python3 scripts/check_command_count_messaging.py; then
+    echo "❌  Command-count drift in README / AGENTS.md / getting-started. Run 'task counts-update', stage the changes, then re-commit."
+    fail=1
+fi
 
-if [ $? -ne 0 ]; then
+if [ $fail -ne 0 ]; then
     echo ""
-    echo "❌  Push blocked — .agent-src/ is out of sync."
-    echo "   Run 'task sync' and compress changed .md files, then commit."
+    echo "   Push blocked — fix the failures above and re-push."
+    echo "   Bypass for a WIP push:  git push --no-verify"
     exit 1
 fi
 EOF

package/scripts/lint_context_spine_usage.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Context-spine usage linter.
+
+Closes the lint gap left after `scripts/schemas/skill.schema.json`
+gained the `context_spine` enum: a skill can declare
+`context_spine: [product]` in frontmatter without ever citing the
+slot in its body, and the schema check will not catch it.
+
+This linter enforces the author checklist in
+`docs/contracts/context-spine.md` § 6: for every slot declared in
+frontmatter, the skill body MUST cite the slot at least once.
+A citation is any of these tokens:
+
+  - the literal path `agents/context-spine/<slot>.md`
+  - the slot name in bold: ``**<slot>**``
+  - the slot name in inline code: `` `<slot>` ``
+
+Cap: ≤ 150 LOC, stdlib only. Hooked into `task ci` via
+`task lint-context-spine-usage`.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILL_GLOBS = (
+    ".agent-src.uncompressed/skills/**/SKILL.md",
+    ".agent-src/skills/**/SKILL.md",
+)
+VALID_SLOTS = ("product", "team", "repo")
+
+CONTEXT_SPINE_PAT = re.compile(
+    r"^context_spine:\s*\[([^\]]*)\]\s*$", re.MULTILINE
+)
+
+
+def _frontmatter_and_body(text: str) -> tuple[str, str]:
+    if not text.startswith("---\n"):
+        return "", text
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return "", text
+    return text[4:end], text[end + 5 :]
+
+
+def _read_spine(fm: str) -> list[str] | None:
+    m = CONTEXT_SPINE_PAT.search(fm)
+    if m is None:
+        return None
+    raw = m.group(1).strip()
+    if not raw:
+        return []
+    return [s.strip().strip("'\"") for s in raw.split(",") if s.strip()]
+
+
+def _slot_cited(body: str, slot: str) -> bool:
+    """A slot is cited if any of three forms appears in the body."""
+    forms = (
+        f"agents/context-spine/{slot}.md",
+        f"**{slot}**",
+        f"`{slot}`",
+    )
+    return any(form in body for form in forms)
+
+
+def lint_skill(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    fm, body = _frontmatter_and_body(text)
+    if not fm:
+        return []
+    slots = _read_spine(fm)
+    if slots is None:
+        return []
+    problems: list[str] = []
+    for slot in slots:
+        if slot not in VALID_SLOTS:
+            problems.append(
+                f"unknown_context_spine_slot: '{slot}' "
+                f"(valid: {', '.join(VALID_SLOTS)})"
+            )
+            continue
+        if not _slot_cited(body, slot):
+            problems.append(
+                f"declared context_spine slot '{slot}' is never cited "
+                f"in the skill body — add `**{slot}**`, `` `{slot}` ``, "
+                f"or a link to `agents/context-spine/{slot}.md` "
+                f"(see docs/contracts/context-spine.md § 6)"
+            )
+    return problems
+
+
+def main() -> int:
+    skills: list[Path] = []
+    for pattern in SKILL_GLOBS:
+        skills.extend(sorted(REPO_ROOT.glob(pattern)))
+    if not skills:
+        print("❌  no SKILL.md files matched", file=sys.stderr)
+        return 1
+    failed = 0
+    declared = 0
+    for skill in skills:
+        rel = skill.relative_to(REPO_ROOT)
+        problems = lint_skill(skill)
+        text = skill.read_text(encoding="utf-8")
+        fm, _ = _frontmatter_and_body(text)
+        if fm and CONTEXT_SPINE_PAT.search(fm):
+            declared += 1
+        if problems:
+            failed += 1
+            print(f"❌  {rel}", file=sys.stderr)
+            for p in problems:
+                print(f"    - {p}", file=sys.stderr)
+    if failed:
+        print(
+            f"\n❌  {failed} skill(s) failed context-spine usage lint "
+            f"({declared} skill(s) declare a spine)",
+            file=sys.stderr,
+        )
+        return 1
+    if not QUIET:
+        print(
+            f"✅  {declared} skill(s) declare context_spine; "
+            f"all declared slots are cited in the body"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_roadmap_complexity.py

@@ -35,6 +35,29 @@ COMPLEXITY_PAT = re.compile(
     r"^complexity:\s*(lightweight|structural)\s*$", re.MULTILINE
 )
 
+# Plate / horizon detection — template rule 16 forbids time-boxed plates
+# in roadmaps. Patterns match the authoring devices we are retiring.
+PLATE_PATS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"^##\s+Horizon\b", re.MULTILINE | re.IGNORECASE),
+     "'## Horizon' section header"),
+    (re.compile(r"\b\d+-week\s+(visible\s+)?plate\b", re.IGNORECASE),
+     "'N-week (visible) plate' phrasing"),
+    (re.compile(r"\bvisible\s+plate\b", re.IGNORECASE),
+     "'visible plate' phrasing"),
+    (re.compile(r"\b(in|out)-of-plate\b", re.IGNORECASE),
+     "'in-of-plate' / 'out-of-plate' marker"),
+    (re.compile(r"\bout-of-horizon\b", re.IGNORECASE),
+     "'out-of-horizon' marker"),
+    (re.compile(r"\bIn-plate\??\b"),
+     "'In-plate' / 'In-plate?' label"),
+    (re.compile(r"\bOut-of-plate\b"),
+     "'Out-of-plate' label"),
+    (re.compile(r"inside\s+(the\s+|\d+-week\s+)?plate", re.IGNORECASE),
+     "'inside the plate' phrasing"),
+    (re.compile(r"outside\s+(the\s+|\d+-week\s+)?plate", re.IGNORECASE),
+     "'outside the plate' phrasing"),
+)
+
 
 def _frontmatter(text: str) -> str:
     if not text.startswith("---\n"):
@@ -73,6 +96,19 @@ def _check_lightweight(text: str, line_count: int, problems: list[str]) -> None:
         )
 
 
+def _check_no_plate(text: str, problems: list[str]) -> None:
+    """Detect time-boxed plate / horizon framing forbidden by template rule 16."""
+    for pat, label in PLATE_PATS:
+        m = pat.search(text)
+        if m is None:
+            continue
+        line = text.count("\n", 0, m.start()) + 1
+        problems.append(
+            f"plate/horizon convention detected ({label}) at line {line} — "
+            f"forbidden by templates/roadmaps.md rule 16"
+        )
+
+
 def lint_roadmap(path: Path) -> list[str]:
     text = path.read_text(encoding="utf-8")
     line_count = text.count("\n") + (1 if text and not text.endswith("\n") else 0)
@@ -87,6 +123,7 @@ def lint_roadmap(path: Path) -> list[str]:
         return problems
     if complexity == "lightweight":
         _check_lightweight(text, line_count, problems)
+    _check_no_plate(text, problems)
     return problems
 
 

package/scripts/lint_skill_tools.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Block D · D1 — meta-linter for ``scripts/skill_tools/*.py``.
+
+Enforces the four pilot-tool invariants locked by the Block D council
+verdict (`agents/council-responses/block-d-python-tools-pilot-verdict.md`):
+
+  1. **stdlib-only** — no third-party imports. Internal package imports
+     (``scripts.*``) are allowed.
+  2. **--help and --json flags** — every tool must register both via
+     ``argparse`` so callers can introspect and machine-read.
+  3. **naming** — ``snake_case_verb_noun.py`` (≥ 1 underscore, lowercase).
+  4. **embedded sample data** — module must define a ``_SAMPLE`` constant
+     OR contain ``if __name__ == "__main__"`` with sample-mode handling
+     (so the tool can run without external fixtures).
+  5. **size cap** — file ≤ 200 LOC (per roadmap D1, applies to D1 itself
+     and to D2/D3/D4 with their own caps validated externally).
+
+Tool discovery is glob-based (``scripts/skill_tools/*.py`` excluding
+``__init__.py``) per anthropic round-2 critique — never a hardcoded list.
+
+Run:
+  python3 scripts/lint_skill_tools.py            # human-readable
+  python3 scripts/lint_skill_tools.py --json     # machine-readable
+
+Exit codes: 0 clean · 1 violations found · 2 usage error.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+ROOT = Path(__file__).resolve().parents[1]
+TOOLS_DIR = ROOT / "scripts" / "skill_tools"
+NAME_RE = re.compile(r"^[a-z][a-z0-9]*(?:_[a-z0-9]+)+\.py$")
+SIZE_CAP = 200
+
+# Python 3.9-compatible stdlib list. Kept conservative — additions are cheap,
+# false negatives are not. Mirrors `sys.stdlib_module_names` from 3.10+.
+STDLIB = frozenset({
+    "__future__", "abc", "argparse", "ast", "base64", "collections", "configparser",
+    "contextlib", "copy", "csv", "dataclasses", "datetime", "decimal", "difflib",
+    "enum", "errno", "fnmatch", "functools", "glob", "gzip", "hashlib", "heapq",
+    "html", "http", "importlib", "inspect", "io", "ipaddress", "itertools", "json",
+    "logging", "math", "mimetypes", "os", "pathlib", "pickle", "platform", "posixpath",
+    "pprint", "queue", "random", "re", "shlex", "shutil", "signal", "socket",
+    "sqlite3", "ssl", "stat", "string", "struct", "subprocess", "sys", "tempfile",
+    "textwrap", "threading", "time", "tomllib", "traceback", "types", "typing",
+    "unicodedata", "unittest", "urllib", "uuid", "venv", "warnings", "weakref",
+    "xml", "zipfile", "zlib",
+})
+PROJECT_PACKAGES = frozenset({"scripts", "skill_tools"})  # internal imports are fine.
+
+
+def _violations_for(path: Path) -> List[str]:
+    """Return a list of violation strings for one tool (empty = clean)."""
+    out: List[str] = []
+    name = path.name
+    if not NAME_RE.match(name):
+        out.append(f"naming: `{name}` is not snake_case_verb_noun.py")
+
+    text = path.read_text(encoding="utf-8")
+    loc = sum(1 for ln in text.splitlines() if ln.strip() and not ln.lstrip().startswith("#"))
+    if loc > SIZE_CAP:
+        out.append(f"size: {loc} LOC > {SIZE_CAP} cap")
+
+    try:
+        tree = ast.parse(text, filename=str(path))
+    except SyntaxError as exc:
+        out.append(f"syntax: {exc.msg} at line {exc.lineno}")
+        return out
+
+    # Imports — flag any non-stdlib, non-project top-level module + record argparse use.
+    imported: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                root = alias.name.split(".")[0]
+                imported.add(root)
+                if root not in STDLIB and root not in PROJECT_PACKAGES:
+                    out.append(f"stdlib-only: imports `{alias.name}` (third-party)")
+        elif isinstance(node, ast.ImportFrom):
+            if node.module is None or node.level > 0:
+                continue  # relative imports — package-internal
+            root = node.module.split(".")[0]
+            imported.add(root)
+            if root not in STDLIB and root not in PROJECT_PACKAGES:
+                out.append(f"stdlib-only: imports from `{node.module}` (third-party)")
+
+    # CLI flags — confirm argparse is imported and `--json` is registered.
+    has_argparse = "argparse" in imported
+    has_json_flag = re.search(r"['\"]--json['\"]", text) is not None
+    if not has_argparse:
+        out.append("cli: no `argparse` import detected")
+    if not has_json_flag:
+        out.append("cli: missing `--json` flag")
+    # `--help` is auto-registered by argparse; we sanity-check that
+    # add_help isn't disabled.
+    if re.search(r"add_help\s*=\s*False", text):
+        out.append("cli: `add_help=False` disables --help")
+
+    # Embedded sample data — accept either a module-level _SAMPLE constant
+    # or a __main__ block (the tool can self-demo).
+    has_sample = bool(re.search(r"^_SAMPLE\s*[:=]", text, re.MULTILINE))
+    has_main = '__name__ == "__main__"' in text or "__name__ == '__main__'" in text
+    if not (has_sample or has_main):
+        out.append("sample: no `_SAMPLE` constant or `__main__` block")
+
+    return out
+
+
+def lint(tools_dir: Path) -> Tuple[int, Dict[str, List[str]]]:
+    tools_dir = tools_dir.resolve()
+    if not tools_dir.is_dir():
+        return 2, {"_error": [f"tools dir missing: {tools_dir}"]}
+    findings: Dict[str, List[str]] = {}
+    for path in sorted(tools_dir.glob("*.py")):
+        if path.name == "__init__.py":
+            continue
+        viols = _violations_for(path)
+        if viols:
+            try:
+                key = str(path.relative_to(ROOT))
+            except ValueError:
+                key = str(path)
+            findings[key] = viols
+    return (1 if findings else 0), findings
+
+
+def _print_human(findings: Dict[str, List[str]]) -> None:
+    if not findings:
+        print(f"✅  scripts/skill_tools/ — all tools clean.")
+        return
+    print(f"❌  scripts/skill_tools/ — {len(findings)} tool(s) with violations:")
+    for fp, viols in findings.items():
+        print(f"  {fp}:")
+        for v in viols:
+            print(f"    - {v}")
+
+
+def main(argv: List[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Lint scripts/skill_tools/*.py against Block D pilot invariants.",
+    )
+    parser.add_argument("--json", action="store_true", help="emit JSON instead of text")
+    parser.add_argument("--quiet", action="store_true",
+                        help="suppress the clean-pass success line (errors still print)")
+    parser.add_argument("--tools-dir", default=str(TOOLS_DIR),
+                        help="directory to lint (default: scripts/skill_tools)")
+    args = parser.parse_args(argv)
+
+    code, findings = lint(Path(args.tools_dir))
+    if args.json:
+        json.dump({"exit_code": code, "findings": findings}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    elif findings or not args.quiet:
+        _print_human(findings)
+    return code
+
+
+_SAMPLE = {"violations": ["stdlib-only: imports `requests` (third-party)"]}
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/schemas/skill.schema.json

@@ -5,7 +5,7 @@
   "$comment": "Source: agents/docs/frontmatter-contract.md#skills. Keep in sync with inventory_frontmatter.py and the linter's lint_skill().",
   "type": "object",
   "additionalProperties": false,
-  "required": ["name", "description", "source"],
+  "required": ["name", "description", "source", "domain"],
   "properties": {
     "name": {
       "type": "string",
@@ -22,6 +22,11 @@
       "type": "string",
       "enum": ["package", "project"]
     },
+    "domain": {
+      "type": "string",
+      "enum": ["engineering", "product", "quality", "devops", "process", "discovery"],
+      "description": "Skill classification axis; see docs/contracts/skill-domains.md. Required for every skill — exactly one of: engineering, product, quality, devops, process, discovery."
+    },
     "status": {
       "type": "string",
       "enum": ["active", "deprecated", "superseded"]
@@ -62,6 +67,15 @@
       "enum": ["deep"],
       "description": "Optional reasoning-depth marker for AI Council invocations triggered by this skill. The only accepted value is 'deep'; omit the key for default depth (setting 'standard' is rejected — every frontmatter byte counts against the context window, and 'standard' is the implicit default). 'deep' instructs the host agent to pass --depth deep to council_cli, which floors rounds at max(ai_council.deep_min_rounds, ai_council.min_rounds). Use for architecture, refactoring, or bug-diagnosis skills. See .agent-src.uncompressed/skills/ai-council/SKILL.md."
     },
+    "context_spine": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["product", "team", "repo"]
+      },
+      "description": "Senior-skill opt-in for the tri-slot context spine. Declares which slots under agents/context-spine/ the skill expects to read (product, team, repo). Council Q1 (KEEP-3) locks the slot count at 3; additions require ≥ 2 citing skills + ADR per docs/contracts/context-spine.md § 5."
+    },
     "execution": {
       "type": "object",
       "additionalProperties": false,

package/scripts/skill_linter.py

@@ -41,15 +41,22 @@ from validate_frontmatter import (  # noqa: E402
 Severity = Literal["error", "warning", "info"]
 ArtifactType = Literal["skill", "rule", "command", "guideline", "persona", "unknown"]
 
-REQUIRED_PERSONA_SECTIONS = [
+REQUIRED_PERSONA_SECTIONS_CORE = [
     "Focus",
     "Mindset",
     "Unique Questions",
     "Output Expectations",
     "Anti-Patterns",
 ]
+REQUIRED_PERSONA_SECTIONS_SPECIALIST = REQUIRED_PERSONA_SECTIONS_CORE + [
+    "Critical Rules",
+    "Workflows",
+]
+# Back-compat alias — used by tier-agnostic callers; defaults to the core spine.
+REQUIRED_PERSONA_SECTIONS = REQUIRED_PERSONA_SECTIONS_CORE
 VALID_PERSONA_TIERS = {"core", "specialist"}
-PERSONA_LINE_BUDGETS = {"core": 120, "specialist": 80}
+# Locked in docs/contracts/persona-schema.md § 4: core ≤ 120, specialist ≤ 100.
+PERSONA_LINE_BUDGETS = {"core": 120, "specialist": 100}
 
 
 REQUIRED_SKILL_SECTIONS = [
@@ -1437,9 +1444,17 @@ def lint_persona(path: Path, text: str) -> LintResult:
             f"Persona description is {len(parsed['description'])} chars (target ≤ 160)",
         ))
 
-    # Required sections
+    # Required sections — tier-aware (per docs/contracts/persona-schema.md § 3).
+    # Core: 5 sections. Specialist: Core-5 + Critical Rules + Workflows.
     sections = extract_sections(text)
-    for required_section in REQUIRED_PERSONA_SECTIONS:
+    tier = parsed.get("tier")
+    if tier == "specialist":
+        required_sections = REQUIRED_PERSONA_SECTIONS_SPECIALIST
+    else:
+        # Default to core sections when tier is missing or invalid; the
+        # tier-enum check above already raised an error in that case.
+        required_sections = REQUIRED_PERSONA_SECTIONS_CORE
+    for required_section in required_sections:
         if required_section not in sections:
             issues.append(Issue(
                 "error",

package/scripts/skill_tools/__init__.py

@@ -0,0 +1,22 @@
+"""Block D pilot tools for skill discovery and persona auditing.
+
+These four tools (D1 meta-linter + D2/D3/D4 functional pilots) ship under
+this subdirectory per Block D council verdict (D-OQ2 → b). Each tool is:
+
+  - stdlib-only (no third-party imports)
+  - exposes ``--help`` and ``--json`` flags
+  - named ``snake_case_verb_noun.py``
+  - embeds sample data so it runs without external fixtures
+
+Layout chosen to make the pilot reversible. If the D5 eval gate fails
+(< 2 of 3 functional tools pass), the directory and its CI hook can be
+removed in a single commit without touching the wider ``scripts/`` tree.
+
+Public entry points:
+
+  - ``scripts/lint_skill_tools.py`` — D1 meta-linter (lives at scripts/ root
+    so ``task ci`` picks it up like other linters).
+  - ``score_skill_relevance`` — D2 (this dir).
+  - ``audit_persona_coverage`` — D3 (this dir).
+  - ``suggest_skill_for_task`` — D4 (this dir).
+"""