@event4u/agent-config 2.17.0 → 2.19.0

package/scripts/schemas/user-type-axis.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/user-type-axis.schema.json",
+  "title": "User-type axis (install filter)",
+  "$comment": "Source: user-types/README.md § Schema. One file per user-type under user-types/<id>.yml. `id` MUST equal the filename stem. Owning roadmap: agents/roadmaps/step-9-user-types-axis.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "description"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 2,
+      "maxLength": 40,
+      "description": "Stable slug. MUST equal the filename stem and the value used in skills' `recommended_for_user_types` frontmatter."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240,
+      "description": "One-line audience description shown in install.sh --help and the user-types/README.md index."
+    },
+    "primary_workflows": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_]*$",
+        "minLength": 2,
+        "maxLength": 60
+      },
+      "description": "Snake-case verb-phrases describing what this user-type does most days. Informs which skills surface first."
+    },
+    "default_skill_priority": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "minLength": 2,
+        "maxLength": 60
+      },
+      "description": "Hand-curated short-list of 3–6 skill stems that should auto-load on `install.sh --user-type=<id>`."
+    },
+    "notes": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 480,
+      "description": "Optional one-line caveat (overlap with sibling user-types, legacy semantics, etc.)."
+    }
+  }
+}

package/scripts/schemas/user-type.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/user-type.schema.json",
+  "title": "User-type frontmatter",
+  "$comment": "Source: docs/contracts/user-type-schema.md. The runtime review-lens axis seeded under .agent-src.uncompressed/user-types/. Distinct from the install-time user-type-axis YAMLs in user-types/ (root) which carry their own user-type-axis.schema.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "kind", "description", "version", "source"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Must match the user-type filename stem."
+    },
+    "kind": {
+      "type": "string",
+      "const": "user-type",
+      "description": "Discriminator — locks this file as a review-lens user-type, distinct from the install-time user-type-axis YAMLs."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+(\\.[0-9]+){0,2}$"
+    },
+    "source": {
+      "type": "string",
+      "enum": ["package", "project"],
+      "description": "Project-specific the typical case — most end-user simulations are consumer-domain, not package-defaults."
+    }
+  }
+}

package/scripts/skill_linter.py

@@ -39,7 +39,7 @@ from validate_frontmatter import (  # noqa: E402
 )
 
 Severity = Literal["error", "warning", "info"]
-ArtifactType = Literal["skill", "rule", "command", "guideline", "persona", "unknown"]
+ArtifactType = Literal["skill", "rule", "command", "guideline", "persona", "user-type", "unknown"]
 
 REQUIRED_PERSONA_SECTIONS_CORE = [
     "Focus",
@@ -57,6 +57,20 @@ REQUIRED_PERSONA_SECTIONS = REQUIRED_PERSONA_SECTIONS_CORE
 VALID_PERSONA_TIERS = {"core", "specialist"}
 # Locked in docs/contracts/persona-schema.md § 4: core ≤ 120, specialist ≤ 100.
 PERSONA_LINE_BUDGETS = {"core": 120, "specialist": 100}
+
+# User-type spine — locked in docs/contracts/user-type-schema.md § 3.
+# Runtime end-user simulation lens (sister axis to personas — methodology vs
+# end-user). Single tier in v1 (no core/specialist split).
+REQUIRED_USERTYPE_SECTIONS = [
+    "Focus",
+    "Daily Workflow",
+    "Vocabulary",
+    "Operational Constraints",
+    "Unique Questions",
+    "Ticket Red Flags",
+    "Anti-Patterns",
+]
+USERTYPE_LINE_BUDGET = 120
 # Wing-scoped overrides — Wing-3 (GTM) and Wing-4 (Money/Strategy/Ops) carry
 # denser cognition (funnel × channel × lifecycle, or finance × org × strategy)
 # than Wing-1/2 specialists, so the line cap rises to keep the seven-section
@@ -514,6 +528,8 @@ def detect_artifact_type(path: Path, text: str) -> ArtifactType:
         return "guideline"
     if "/personas/" in path_str:
         return "persona"
+    if "/user-types/" in path_str:
+        return "user-type"
     if has_skill_heading:
         return "skill"
     return "unknown"
@@ -1849,6 +1865,106 @@ def lint_persona(path: Path, text: str) -> LintResult:
     )
 
 
+def lint_usertype(path: Path, text: str) -> LintResult:
+    """Lint a user-type .md file (frontmatter schema + required sections + size).
+
+    User-types are the runtime end-user simulation lens (sister axis to
+    personas — methodology vs end-user). Contract:
+    docs/contracts/user-type-schema.md.
+    """
+    issues: List[Issue] = []
+
+    frontmatter = extract_frontmatter(text)
+    if not frontmatter:
+        issues.append(Issue("error", "missing_frontmatter", "User-type requires YAML frontmatter"))
+        return LintResult(
+            file=str(path),
+            artifact_type="user-type",
+            status="fail",
+            issues=issues,
+            suggestions=[".agent-src.uncompressed/user-types/_template/user-type.md"],
+        )
+
+    # Required keys per docs/contracts/user-type-schema.md § 1.
+    required = {
+        "id": re.compile(r'^id:\s*"?([\w-]+)"?\s*$', re.MULTILINE),
+        "kind": re.compile(r'^kind:\s*"?([\w-]+)"?\s*$', re.MULTILINE),
+        "description": re.compile(r'^description:\s*"?([^"\n]+?)"?\s*$', re.MULTILINE),
+        "version": re.compile(r'^version:\s*"?([\d.]+)"?\s*$', re.MULTILINE),
+        "source": re.compile(r'^source:\s*"?(package|project)"?\s*$', re.MULTILINE),
+    }
+    parsed: dict = {}
+    for field, pattern in required.items():
+        value = extract_frontmatter_field(frontmatter, pattern)
+        if not value:
+            issues.append(Issue("error", f"missing_{field}", f"User-type frontmatter must declare `{field}`"))
+        else:
+            parsed[field] = value
+
+    if "id" in parsed and parsed["id"] != path.stem:
+        issues.append(Issue(
+            "error",
+            "id_filename_mismatch",
+            f"User-type id `{parsed['id']}` must match filename stem `{path.stem}`",
+        ))
+
+    if "kind" in parsed and parsed["kind"] != "user-type":
+        issues.append(Issue(
+            "error",
+            "invalid_kind",
+            f"User-type kind must be `user-type` (got `{parsed['kind']}`)",
+        ))
+
+    if "description" in parsed and len(parsed["description"]) > 160:
+        issues.append(Issue(
+            "warning",
+            "long_description",
+            f"User-type description is {len(parsed['description'])} chars (target ≤ 160)",
+        ))
+
+    sections = extract_sections(text)
+    for required_section in REQUIRED_USERTYPE_SECTIONS:
+        if required_section not in sections:
+            issues.append(Issue(
+                "error",
+                "missing_section",
+                f"User-type is missing required section `## {required_section}`",
+            ))
+
+    # Anti-Generic Quality Bar: ≥ 3 Unique Questions
+    uq_block = extract_section_block(text, "Unique Questions")
+    if uq_block:
+        bullet_count = len(re.findall(r"^\s*[-*]\s+", uq_block, re.MULTILINE))
+        if bullet_count < 3:
+            issues.append(Issue(
+                "warning",
+                "too_few_unique_questions",
+                f"User-type has {bullet_count} unique questions (target ≥ 3)",
+            ))
+
+    line_count = len(text.splitlines())
+    if line_count > USERTYPE_LINE_BUDGET:
+        issues.append(Issue(
+            "warning",
+            "size_budget",
+            f"User-type has {line_count} lines (budget ≤ {USERTYPE_LINE_BUDGET})",
+        ))
+
+    if not H1_PATTERN.search(text):
+        issues.append(Issue("warning", "missing_h1", "User-type is missing an H1 heading"))
+
+    if not text.endswith("\n"):
+        issues.append(Issue("warning", "no_trailing_newline", "File must end with exactly one newline"))
+
+    return LintResult(
+        file=str(path),
+        artifact_type="user-type",
+        status=classify_status(issues),
+        issues=issues,
+        suggestions=[],
+    )
+
+
 def gather_all_candidate_files(root: Path) -> list[Path]:
     """Gather all lintable files. Prefers .agent-src.uncompressed/ (source of truth).
     Falls back to .agent-src/ only if uncompressed doesn't exist.
@@ -1906,6 +2022,18 @@ def gather_all_candidate_files(root: Path) -> list[Path]:
             if not f.is_symlink():
                 candidates.append(f)
 
+    # User-types (sister axis to personas — methodology vs end-user).
+    # Top-level .md only; README and _template/ subtree excluded.
+    uncompressed_usertypes = root / ".agent-src.uncompressed" / "user-types"
+    augment_usertypes = root / ".agent-src" / "user-types"
+    usertypes_base = uncompressed_usertypes if uncompressed_usertypes.exists() else augment_usertypes
+    if usertypes_base.exists():
+        for f in usertypes_base.glob("*.md"):
+            if f.name.lower() == "readme.md":
+                continue
+            if not f.is_symlink():
+                candidates.append(f)
+
     # Frugality charter (Phase 0.4 Layer 2). Lives in contexts/, not
     # walked by the artifact-type loops above, but still needs the
     # index-integrity check.
@@ -2093,8 +2221,13 @@ def _is_execution_artifact(path: Path, text: str) -> bool:
     path_lower = str(path).lower()
     text_lower = text.lower()
 
-    # Exclude commands, guidelines, and personas — they are not execution-oriented
-    if "/commands/" in path_lower or "/guidelines/" in path_lower or "/personas/" in path_lower:
+    # Exclude commands, guidelines, personas, user-types — not execution-oriented
+    if (
+        "/commands/" in path_lower
+        or "/guidelines/" in path_lower
+        or "/personas/" in path_lower
+        or "/user-types/" in path_lower
+    ):
         return False
 
     # File name match — strong signal
@@ -2779,7 +2912,7 @@ def lint_output_schema(path: Path, text: str) -> List[Issue]:
 
 
 # Artefact types that carry a JSON-Schema contract for their frontmatter.
-_SCHEMA_ARTEFACT_TYPES = {"skill", "rule", "command", "persona"}
+_SCHEMA_ARTEFACT_TYPES = {"skill", "rule", "command", "persona", "user-type"}
 
 
 def lint_frontmatter_schema(path: Path, text: str, artifact_type: str) -> List[Issue]:
@@ -2840,6 +2973,8 @@ def lint_file(path: Path, repo_root: Path | None = None) -> LintResult:
         result = lint_guideline(display_path, text)
     elif artifact_type == "persona":
         result = lint_persona(display_path, text)
+    elif artifact_type == "user-type":
+        result = lint_usertype(display_path, text)
     else:
         # Frugality charter lives in contexts/ (artifact_type == unknown)
         # but still needs Layer 2 index-integrity validation.

package/scripts/skill_tools/audit_user_type_coverage.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Block D · D3 — audit_user_type_coverage.
+
+Coverage audit for the user-type axis. User-types are **CLI-only** in v1
+(see `docs/contracts/adr-user-types-axis.md` and Phase 4 step 3 of
+`agents/roadmaps/step-6-user-types-axis.md`) — skills do NOT declare a
+`user-types:` frontmatter key, so persona-style citation counting does
+not apply. Instead this script:
+
+  - Inventories every user-type file in the source directory.
+  - Scans skills, commands, and `docs/` for `--user-type=<id>` mentions.
+  - Flags **orphan references** (CLI mention to a non-existent id) and
+    **never-referenced** user-types (file exists but nobody cites it).
+
+Inputs:
+  --user-types-dir DIR — directory holding user-type Markdown files
+  --search-root DIR    — root to recurse for `--user-type=<id>` mentions
+  --json               — machine-readable output
+
+Output: per-user-type reference count + status (ok / never-referenced /
+orphan). Exit code: 0 always (advisory, not a CI gate).
+
+Stdlib-only. ≤ 130 LOC. Sibling of `audit_persona_coverage.py`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Set
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_USER_TYPES = ROOT / ".agent-src.uncompressed" / "user-types"
+DEFAULT_SEARCH_ROOT = ROOT / ".agent-src.uncompressed"
+REFERENCE_THRESHOLD = 1  # user-type with 0 references → flagged.
+
+# Matches `--user-type=<id>` in command markdown, skill prose, docs.
+_REFERENCE_RE = re.compile(r"--user-type=([\w-]+)")
+
+
+def _read_block(path: Path) -> str:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if not text.startswith("---"):
+        return ""
+    end = text.find("\n---", 3)
+    return text[3:end] if end != -1 else ""
+
+
+def _frontmatter_value(block: str, key: str) -> str | None:
+    m = re.search(rf"^{re.escape(key)}\s*:\s*(.+)$", block, re.MULTILINE)
+    if not m:
+        return None
+    val = m.group(1).strip()
+    if val.startswith('"') and val.endswith('"'):
+        val = val[1:-1]
+    return val
+
+
+def _load_user_types(user_types_dir: Path) -> Set[str]:
+    ids: Set[str] = set()
+    if not user_types_dir.is_dir():
+        return ids
+    for md in sorted(user_types_dir.glob("*.md")):
+        if md.name.lower() == "readme.md":
+            continue
+        block = _read_block(md)
+        slug = _frontmatter_value(block, "id") or md.stem
+        ids.add(slug)
+    # Walk one level deeper to skip `_template/` etc.
+    for md in sorted(user_types_dir.glob("*/*.md")):
+        if "_template" in md.parts:
+            continue
+        block = _read_block(md)
+        slug = _frontmatter_value(block, "id") or md.parent.name
+        ids.add(slug)
+    return ids
+
+
+def _count_references(search_root: Path, skip_dir: Path) -> Dict[str, int]:
+    counts: Dict[str, int] = {}
+    if not search_root.is_dir():
+        return counts
+    skip_resolved = skip_dir.resolve() if skip_dir.is_dir() else None
+    for md in search_root.rglob("*.md"):
+        # Don't count references inside the user-types dir itself
+        # (the README documents the flag in example form).
+        if skip_resolved and skip_resolved in md.resolve().parents:
+            continue
+        text = md.read_text(encoding="utf-8", errors="replace")
+        for slug in _REFERENCE_RE.findall(text):
+            counts[slug] = counts.get(slug, 0) + 1
+    return counts
+
+
+def audit(user_types_dir: Path, search_root: Path) -> List[Dict[str, object]]:
+    ids = _load_user_types(user_types_dir)
+    references = _count_references(search_root, user_types_dir)
+    rows: List[Dict[str, object]] = []
+    for slug in sorted(ids):
+        count = references.get(slug, 0)
+        status = "ok" if count >= REFERENCE_THRESHOLD else "never-referenced"
+        rows.append({"user_type": slug, "references": count,
+                     "threshold": REFERENCE_THRESHOLD, "status": status})
+    for slug in sorted(references.keys()):
+        if slug not in ids:
+            rows.append({"user_type": slug, "references": references[slug],
+                         "threshold": REFERENCE_THRESHOLD, "status": "orphan"})
+    return rows
+
+
+def _print_human(rows: List[Dict[str, object]]) -> None:
+    if not rows:
+        print("(no user-types found)")
+        return
+    width = max(len(str(r["user_type"])) for r in rows)
+    print(f"  {'user-type':<{width}}  refs   status")
+    print(f"  {'-' * width}  -----  ----------------")
+    for r in rows:
+        print(f"  {str(r['user_type']):<{width}}  "
+              f"{int(r['references']):>5}  {r['status']}")
+    flagged = [r for r in rows if r["status"] != "ok"]
+    if flagged:
+        print(f"\n  {len(flagged)} user-type(s) flagged "
+              f"(never-referenced or orphan).")
+
+
+def main(argv: List[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0])
+    parser.add_argument("--user-types-dir", default=str(DEFAULT_USER_TYPES))
+    parser.add_argument("--search-root", default=str(DEFAULT_SEARCH_ROOT))
+    parser.add_argument("--json", action="store_true",
+                        help="emit JSON instead of text")
+    args = parser.parse_args(argv)
+    rows = audit(Path(args.user_types_dir), Path(args.search_root))
+    if args.json:
+        json.dump({"rows": rows}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        _print_human(rows)
+    return 0
+
+
+_SAMPLE = {"threshold": REFERENCE_THRESHOLD}
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/sync_agent_settings.py

@@ -113,6 +113,12 @@ def main(argv: list[str] | None = None) -> int:
             print(f"error: unsupported profile {profile!r}", file=sys.stderr)
             return 2
         profile_values = load_profile(profile_dir, profile)
+        # Preserve existing user_type (step-9 axis) so the template's
+        # __USER_TYPE__ placeholder renders without forcing the user to
+        # re-pass --user-type on every sync. Empty string = no filter.
+        personal = user_data.get("personal") if isinstance(user_data.get("personal"), dict) else {}
+        existing_user_type = str(personal.get("user_type") or "") if personal else ""
+        profile_values["user_type"] = existing_user_type
         template_body = load_template(template_path, profile_values)
     except FileNotFoundError as exc:
         print(f"error: {exc}", file=sys.stderr)