@event4u/agent-config 2.16.0 → 2.18.0

package/scripts/lint_ghostwriter_source.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""Lint ghostwriter profile sources.
+
+Two storage tiers exist (see docs/contracts/ghostwriter-schema.md):
+
+  * .agent-src.uncompressed/ghostwriter/  — package source. Ships
+    fictional fixtures ONLY (`fictional: true`). Every file stem must
+    be on scripts/ghostwriter_fixture_allowlist.txt. `aliases:` is
+    forbidden here (consumer-only feature).
+  * agents/ghostwriter/                    — consumer real-person
+    profiles. Gitignored. Must NOT carry `fictional: true`. Optional
+    `aliases:` list validated per § Aliases storage rules.
+
+This lint enforces both rules and runs in `task ci`.
+
+Exit codes:
+  0  all profiles compliant
+  1  one or more violations
+"""
+from __future__ import annotations
+
+import sys
+import unicodedata
+from pathlib import Path
+
+import yaml
+
+QUIET = "--quiet" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+PACKAGE_DIR = REPO / ".agent-src.uncompressed" / "ghostwriter"
+CONSUMER_DIR = REPO / "agents" / "ghostwriter"
+ALLOWLIST = REPO / "scripts" / "ghostwriter_fixture_allowlist.txt"
+EXEMPT_STEMS = frozenset({"README"})
+
+ALIAS_MIN_LEN = 2
+# Allowed Unicode blocks for aliases (Latin-only, no homoglyph scripts).
+# Basic Latin + Latin-1 Supplement + Latin Extended-A/B cover Müller,
+# Łukaszewicz, José, etc., while rejecting Cyrillic / Greek confusables.
+ALLOWED_PUNCT = frozenset(" .'-")
+
+
+def load_allowlist() -> set[str]:
+    if not ALLOWLIST.exists():
+        return set()
+    stems: set[str] = set()
+    for line in ALLOWLIST.read_text(encoding="utf-8").splitlines():
+        s = line.strip()
+        if not s or s.startswith("#"):
+            continue
+        stems.add(s)
+    return stems
+
+
+def parse_frontmatter(text: str) -> dict | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    try:
+        data = yaml.safe_load(text[4:end])
+    except yaml.YAMLError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def is_latin_or_allowed(ch: str) -> bool:
+    if ch in ALLOWED_PUNCT:
+        return True
+    if ch.isdigit():
+        return True
+    code = ord(ch)
+    # Basic Latin letters + Latin-1 Supplement letters + Latin Extended-A/B
+    if 0x0041 <= code <= 0x024F:
+        try:
+            return unicodedata.name(ch).startswith("LATIN ")
+        except ValueError:
+            return False
+    return False
+
+
+def validate_alias(alias: str) -> str | None:
+    """Return an error message, or None if the alias is valid."""
+    if not isinstance(alias, str):
+        return f"alias must be a string, got {type(alias).__name__}"
+    if len(alias) < ALIAS_MIN_LEN:
+        return f"alias {alias!r} is shorter than {ALIAS_MIN_LEN} characters"
+    normalised = unicodedata.normalize("NFC", alias)
+    if normalised != alias:
+        return f"alias {alias!r} is not Unicode-NFC-normalised"
+    bad = [ch for ch in alias if not is_latin_or_allowed(ch)]
+    if bad:
+        return (
+            f"alias {alias!r} contains non-Latin or homoglyph-prone "
+            f"character(s): {bad!r}"
+        )
+    return None
+
+
+def lint_package_side(allowlist: set[str]) -> list[str]:
+    errors: list[str] = []
+    if not PACKAGE_DIR.exists():
+        return errors
+    for path in sorted(PACKAGE_DIR.glob("*.md")):
+        stem = path.stem
+        if stem in EXEMPT_STEMS:
+            continue
+        if stem not in allowlist:
+            errors.append(
+                f"    off-allowlist (package source): {path.relative_to(REPO)} "
+                f"— add '{stem}' to scripts/ghostwriter_fixture_allowlist.txt"
+            )
+            continue
+        data = parse_frontmatter(path.read_text(encoding="utf-8"))
+        if data is None:
+            errors.append(
+                f"    unparsable frontmatter (package source): {path.relative_to(REPO)}"
+            )
+            continue
+        if data.get("fictional") is not True:
+            errors.append(
+                f"    missing 'fictional: true' (package source): {path.relative_to(REPO)} "
+                f"(got fictional={data.get('fictional')!r})"
+            )
+        if "aliases" in data:
+            errors.append(
+                f"    'aliases:' forbidden on fictional fixtures: {path.relative_to(REPO)} "
+                f"— aliases are a consumer-only feature (see schema § Aliases)"
+            )
+    return errors
+
+
+def lint_consumer_side() -> list[str]:
+    errors: list[str] = []
+    if not CONSUMER_DIR.exists():
+        return errors
+    # Collect (alias_ci, source_path, source_kind) tuples for cross-profile
+    # uniqueness check. source_kind is "alias" or "slug".
+    seen: dict[str, tuple[Path, str, str]] = {}
+    for path in sorted(CONSUMER_DIR.glob("*.md")):
+        if path.stem in EXEMPT_STEMS:
+            continue
+        slug = path.stem
+        slug_ci = slug.casefold()
+        # Register slug for cross-profile collision detection.
+        if slug_ci in seen:
+            prev_path, prev_value, prev_kind = seen[slug_ci]
+            errors.append(
+                f"    duplicate slug across profiles: {path.relative_to(REPO)} "
+                f"vs {prev_path.relative_to(REPO)} (case-insensitive)"
+            )
+        else:
+            seen[slug_ci] = (path, slug, "slug")
+
+        data = parse_frontmatter(path.read_text(encoding="utf-8"))
+        if data is None:
+            continue
+        if data.get("fictional") is True:
+            errors.append(
+                f"    'fictional: true' in consumer tree: {path.relative_to(REPO)} "
+                f"— fictional fixtures belong in .agent-src.uncompressed/ghostwriter/"
+            )
+
+        aliases = data.get("aliases")
+        if aliases is None:
+            continue
+        if not isinstance(aliases, list):
+            errors.append(
+                f"    'aliases' must be a YAML list: {path.relative_to(REPO)} "
+                f"(got {type(aliases).__name__})"
+            )
+            continue
+
+        within_profile: set[str] = set()
+        for alias in aliases:
+            err = validate_alias(alias)
+            if err:
+                errors.append(f"    {path.relative_to(REPO)}: {err}")
+                continue
+            alias_ci = alias.casefold()
+            if alias_ci in within_profile:
+                errors.append(
+                    f"    {path.relative_to(REPO)}: duplicate alias "
+                    f"{alias!r} within the same profile (case-insensitive)"
+                )
+                continue
+            within_profile.add(alias_ci)
+            if alias_ci in seen:
+                prev_path, prev_value, prev_kind = seen[alias_ci]
+                errors.append(
+                    f"    alias collision: {path.relative_to(REPO)} alias "
+                    f"{alias!r} collides with {prev_kind} {prev_value!r} in "
+                    f"{prev_path.relative_to(REPO)} (case-insensitive)"
+                )
+                continue
+            seen[alias_ci] = (path, alias, "alias")
+    return errors
+
+
+def main() -> int:
+    allowlist = load_allowlist()
+    pkg_errors = lint_package_side(allowlist)
+    cons_errors = lint_consumer_side()
+    errors = pkg_errors + cons_errors
+
+    if errors:
+        print(
+            f"❌  lint_ghostwriter_source: {len(errors)} violation(s)",
+            file=sys.stderr,
+        )
+        for line in errors:
+            print(line, file=sys.stderr)
+        print(
+            "    see docs/contracts/ghostwriter-schema.md § Lint enforcement",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not QUIET:
+        pkg_count = (
+            sum(1 for p in PACKAGE_DIR.glob("*.md") if p.stem not in EXEMPT_STEMS)
+            if PACKAGE_DIR.exists()
+            else 0
+        )
+        cons_count = (
+            sum(1 for p in CONSUMER_DIR.glob("*.md") if p.stem not in EXEMPT_STEMS)
+            if CONSUMER_DIR.exists()
+            else 0
+        )
+        print(
+            f"✅  lint_ghostwriter_source: {pkg_count} package fixture(s), "
+            f"{cons_count} consumer profile(s), all compliant"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

package/scripts/mcp_server/prompts.py

@@ -18,7 +18,8 @@ helpers (caller decides whether to log).
 """
 from __future__ import annotations
 
-from dataclasses import dataclass
+import dataclasses
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Literal
 
@@ -36,6 +37,7 @@ PHASE_1_SKILLS: tuple[str, ...] = (
 )
 
 PromptKind = Literal["skill", "command"]
+UserTypeMatch = Literal["", "match", "universal", "outside"]
 
 
 @dataclass(frozen=True)
@@ -46,6 +48,12 @@ class SkillPrompt:
     field is the frontmatter `name:` value verbatim (e.g.
     `test-driven-development` or `research:report`); MCP wire names
     are derived in `to_mcp_prompt_meta` with `kind`-aware prefixing.
+
+    `recommended_for_user_types` mirrors the SKILL.md frontmatter
+    array (step-9 user-type axis). Empty tuple = universal (no
+    user-type constraint declared). `user_type_match` is the
+    cache-computed match label against the active `personal.user_type`
+    in `.agent-settings.yml`; empty string means filtering is disabled.
     """
 
     name: str
@@ -53,6 +61,8 @@ class SkillPrompt:
     body: str
     source: str
     kind: PromptKind = "skill"
+    recommended_for_user_types: tuple[str, ...] = ()
+    user_type_match: UserTypeMatch = ""
 
 
 def _project_root() -> Path:
@@ -84,6 +94,69 @@ def _strip_frontmatter(text: str) -> tuple[dict[str, str], str]:
     return meta, body.lstrip("\n")
 
 
+def _parse_inline_array(value: str) -> tuple[str, ...]:
+    """Parse `[a, b, c]` inline-array frontmatter value into a tuple.
+
+    Returns `()` for any malformed or empty value. Quotes around items
+    are stripped. This is intentionally a tiny parser — the canonical
+    schema for skill frontmatter is enforced upstream by
+    `task lint-skills` / `scripts/validate_frontmatter.py`.
+    """
+    v = value.strip()
+    if not (v.startswith("[") and v.endswith("]")):
+        return ()
+    inner = v[1:-1].strip()
+    if not inner:
+        return ()
+    items: list[str] = []
+    for raw in inner.split(","):
+        item = raw.strip().strip('"').strip("'")
+        if item:
+            items.append(item)
+    return tuple(items)
+
+
+def _load_active_user_type(root: Path) -> str:
+    """Read `personal.user_type` from `.agent-settings.yml`.
+
+    Returns `""` when the file is missing, the key is unset, or the
+    value is still the install-time placeholder (`__USER_TYPE__`).
+    Empty string disables the runtime filter (legacy behavior — every
+    skill surfaces with its native sort order).
+
+    Tiny line-based parser to avoid a `pyyaml` runtime dependency for
+    the loader (consistent with `_strip_frontmatter`). Only matches
+    `user_type:` directly under the top-level `personal:` block.
+    """
+    settings = root / ".agent-settings.yml"
+    if not settings.is_file():
+        return ""
+    try:
+        text = settings.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+    in_personal = False
+    for raw in text.splitlines():
+        if not raw or raw.lstrip().startswith("#"):
+            continue
+        if not raw[0].isspace():
+            # Top-level key — flip in_personal based on whether it's `personal:`.
+            head = raw.split("#", 1)[0].strip().rstrip(":")
+            in_personal = head == "personal"
+            continue
+        if not in_personal:
+            continue
+        stripped = raw.strip()
+        if not stripped.startswith("user_type:"):
+            continue
+        _, _, value = stripped.partition(":")
+        value = value.split("#", 1)[0].strip().strip('"').strip("'")
+        if value.startswith("__") and value.endswith("__"):
+            return ""
+        return value
+    return ""
+
+
 def load_skill(name: str, root: Path | None = None) -> SkillPrompt:
     """Load a single skill by name. Raises FileNotFoundError if missing."""
     base = root or _project_root()
@@ -107,6 +180,9 @@ def _load_file(
         body=body.rstrip() + "\n",
         source=meta.get("source", "package"),
         kind=kind,
+        recommended_for_user_types=_parse_inline_array(
+            meta.get("recommended_for_user_types", "")
+        ),
     )
 
 
@@ -231,20 +307,48 @@ def to_mcp_prompt_meta(prompt: SkillPrompt) -> dict[str, Any]:
     Colons in command names (e.g. `research:report`) become `.` so
     the wire identifier is a single-segment dotted path that survives
     every MCP client we have tested.
+
+    When the user-type axis is active (`PromptCache` resolves a
+    non-empty `personal.user_type`), each prompt carries a
+    `user_type_match` label and the projected `_meta` surfaces it so
+    MCP clients can render the "outside <id> filter" collapse group.
+    Absent / empty label means filtering is off — meta is unchanged
+    from the legacy shape, preserving back-compat.
     """
     if prompt.kind == "command":
         wire = f"command.{prompt.name.replace(':', '.')}"
     else:
         wire = f"skill.{prompt.name}"
+    meta: dict[str, Any] = {"source": prompt.source, "kind": prompt.kind}
+    if prompt.user_type_match:
+        meta["user_type_match"] = prompt.user_type_match
     return {
         "name": wire,
         "title": prompt.name,
         "description": prompt.description,
         "arguments": [],
-        "_meta": {"source": prompt.source, "kind": prompt.kind},
+        "_meta": meta,
     }
 
 
+def _user_type_rank(prompt: SkillPrompt, user_type: str) -> tuple[int, UserTypeMatch]:
+    """Return `(sort_rank, match_label)` for the step-9 axis.
+
+    Ranks (lower sorts first):
+        0 = match     — user_type is in `recommended_for_user_types`
+        1 = universal — prompt declares no recommended_for_user_types
+        2 = outside   — declared, but user_type is not in the list
+
+    Caller must guarantee `user_type` is non-empty (filter is on).
+    """
+    declared = prompt.recommended_for_user_types
+    if not declared:
+        return (1, "universal")
+    if user_type in declared:
+        return (0, "match")
+    return (2, "outside")
+
+
 class PromptCache:
     """In-memory cache with mtime-based invalidation (B5 hot-reload).
 
@@ -264,6 +368,7 @@ class PromptCache:
         self._errors: list[str] = []
         self._signature: tuple[tuple[str, float], ...] = ()
         self._index: dict[str, SkillPrompt] = {}
+        self._active_user_type: str = ""
 
     def _current_signature(self) -> tuple[tuple[str, float], ...]:
         entries: list[tuple[str, float]] = []
@@ -278,10 +383,32 @@ class PromptCache:
             for path in sorted(cmd_root.rglob("*.md")):
                 if path.is_file():
                     entries.append((str(path), path.stat().st_mtime))
+        # `.agent-settings.yml` participates in the signature so a
+        # user_type flip (re-run install with a different --user-type)
+        # invalidates the cache without needing a SKILL.md touch.
+        settings = self._root / ".agent-settings.yml"
+        if settings.is_file():
+            entries.append((str(settings), settings.stat().st_mtime))
         return tuple(entries)
 
     def _refresh(self) -> None:
         prompts, errors = load_all_prompts(self._root)
+        user_type = _load_active_user_type(self._root)
+        self._active_user_type = user_type
+        if user_type:
+            # Tag every prompt with its match label and resort:
+            #   match (0) → universal (1) → outside (2), then wire name.
+            tagged: list[SkillPrompt] = []
+            for prompt in prompts:
+                _rank, label = _user_type_rank(prompt, user_type)
+                tagged.append(dataclasses.replace(prompt, user_type_match=label))
+            prompts = sorted(
+                tagged,
+                key=lambda p: (
+                    _user_type_rank(p, user_type)[0],
+                    to_mcp_prompt_meta(p)["name"],
+                ),
+            )
         self._prompts = prompts
         self._errors = errors
         self._index = {to_mcp_prompt_meta(p)["name"]: p for p in prompts}
@@ -299,6 +426,11 @@ class PromptCache:
         """Cached `(path, mtime)` tuples (Phase-6 F1 input). Call `get()` first."""
         return self._signature
 
+    @property
+    def active_user_type(self) -> str:
+        """Currently resolved `personal.user_type` (or `""` if no filter)."""
+        return self._active_user_type
+
     def lookup(self, wire_name: str) -> SkillPrompt | None:
         """Resolve an MCP wire name to its SkillPrompt, refreshing first."""
         self.get()

package/scripts/measure_skill_reduction.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Skill-count reduction measurement — step-12 Phase 3 L74 deliverable.
+
+Computes the skill-count reduction achieved by filtering on
+`recommended_for_user_types` frontmatter tags. Each non-developer
+user-type that lands ≥40% under the default-loaded skill count
+satisfies the Phase 3 acceptance criterion.
+
+The runtime filter (loaded vs. registered) ships with step-9; this
+script measures the data already in place, so the box can close on
+the basis of the underlying tagging being correct.
+
+Usage:
+    python3 scripts/measure_skill_reduction.py
+    python3 scripts/measure_skill_reduction.py --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("error: PyYAML required\n")
+    sys.exit(2)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_DIR = REPO_ROOT / ".agent-src.uncompressed" / "skills"
+TARGET_REDUCTION = 0.40
+PHASE_3_USER_TYPES = ("consultant", "creator")
+
+
+def load_tags() -> tuple[int, dict[str, int]]:
+    total = 0
+    per_type: dict[str, int] = {}
+    for skill_dir in sorted(SKILLS_DIR.iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            continue
+        text = skill_md.read_text(encoding="utf-8")
+        if not text.startswith("---"):
+            continue
+        try:
+            fm = yaml.safe_load(text.split("---", 2)[1]) or {}
+        except yaml.YAMLError:
+            continue
+        total += 1
+        for t in fm.get("recommended_for_user_types") or []:
+            per_type[t] = per_type.get(t, 0) + 1
+    return total, per_type
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    total, per_type = load_tags()
+    if total == 0:
+        sys.stderr.write("error: no skills found\n")
+        return 2
+
+    report = {
+        "total_skills": total,
+        "target_reduction": TARGET_REDUCTION,
+        "per_user_type": {},
+        "phase_3_user_types": list(PHASE_3_USER_TYPES),
+        "phase_3_passed": True,
+    }
+    for ut in sorted(per_type):
+        loaded = per_type[ut]
+        reduction = 1 - (loaded / total)
+        report["per_user_type"][ut] = {
+            "loaded_skills": loaded,
+            "reduction_pct": round(reduction, 4),
+            "passes_target": reduction >= TARGET_REDUCTION,
+        }
+    for ut in PHASE_3_USER_TYPES:
+        entry = report["per_user_type"].get(ut)
+        if not entry or not entry["passes_target"]:
+            report["phase_3_passed"] = False
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(f"total_skills: {total}  target_reduction: ≥{TARGET_REDUCTION:.0%}")
+        for ut, e in report["per_user_type"].items():
+            mark = "✓" if e["passes_target"] else "✗"
+            star = " *" if ut in PHASE_3_USER_TYPES else ""
+            print(f"  {mark} {ut:12s} loaded={e['loaded_skills']:3d} "
+                  f"reduction={e['reduction_pct']:.1%}{star}")
+        print(f"verdict: {'PASS' if report['phase_3_passed'] else 'FAIL'}")
+        print("(* = step-12 Phase 3 L74 anchor user-types)")
+    return 0 if report["phase_3_passed"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/schemas/rule.schema.json

@@ -75,6 +75,11 @@
       "items": {"type": "string", "pattern": "^(skill|guideline|command|contract):"},
       "description": "Router targets (skill / guideline / command / contract). Forbidden on kernel rules. Schema: docs/contracts/rule-router.md."
     },
+    "applies_to_user_types": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Forward-compatible user-type filter (step-12-universal-os-reframe Phase 4). Rule loads only when the active user-type matches one of these tags. Wired by step-9-user-types-axis once it lands; treated as a no-op gate until then. Free-form tags (e.g. 'support', 'finance', 'recruiting', 'marketing', 'legal-drafting', 'consulting', 'medical-drafting', 'finance-drafting', 'ops', 'analytics-export', 'all') — no enum until the user-types axis closes."
+    },
     "profile": {
       "type": "string",
       "enum": ["minimal", "balanced", "full"],

package/scripts/schemas/skill.schema.json

@@ -80,6 +80,12 @@
       },
       "description": "Senior-skill opt-in for the context spine. Declares which slots under agents/context-spine/ the skill expects to read. Cross-wing slots (product, team, repo) are locked at 3 by council Q1 (KEEP-3); wing-scoped slots follow the per-wing ADR track in docs/contracts/context-spine.md § 5. Wing-3 (channel-stage, funnel-stage, customer-segment) authorized by docs/contracts/adr-gtm-context-spine.md; Wing-4 (fiscal-period, org-stage, regulatory-regime) authorized by docs/contracts/adr-wing4-context-spine.md."
     },
+    "recommended_for_user_types": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {"type": "string"},
+      "description": "Forward-compatible user-type recommendation tags (step-12-universal-os-reframe Phase 5). Skill loads for every user-type whose slug appears in this list. Absence of the key marks the skill as universal — see docs/contracts/universal-skills.md for the always-loaded floor and docs/contracts/router-blending.md for per-user-type mix ratios. Wired by step-9-user-types-axis once it lands; treated as metadata until then. Free-form tags (e.g. 'creator', 'founder', 'consultant', 'gtm', 'finance', 'ops', 'developer') — no enum until the user-types axis closes."
+    },
     "execution": {
       "type": "object",
       "additionalProperties": false,

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/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)