@event4u/agent-config 2.16.0 → 2.18.0

package/scripts/check_role_doc_links.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Verify every skill link in role-based docs resolves to a real file.
+
+Part of step-12 Phase 2. Runs in `task ci` to catch link rot when a
+skill is renamed or removed but the role docs still reference it.
+
+Scans `docs/getting-started-by-role.md` and `docs/getting-started-laravel.md`
+for markdown links of the form `../.agent-src/skills/<name>/SKILL.md`
+(relative to docs/) and checks that the target file exists on disk.
+
+Exit codes:
+  0 — every link resolves
+  1 — at least one broken link; prints the offending file:line:url tuples
+  2 — usage error (one of the role doc files missing)
+
+Usage:
+  python3 scripts/check_role_doc_links.py
+  python3 scripts/check_role_doc_links.py --quiet
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+DOCS_DIR = ROOT / "docs"
+
+# (display-path, on-disk path, link-anchor) — anchor is the relative
+# prefix that identifies a skill link from inside docs/.
+ROLE_DOCS = [
+    DOCS_DIR / "getting-started-by-role.md",
+    DOCS_DIR / "getting-started-laravel.md",
+]
+
+# Markdown link: [label](path). We only check the (path) part. The
+# regex tolerates trailing #anchor fragments and ignores absolute URLs.
+LINK_RE = re.compile(r"\]\(([^)\s]+)\)")
+
+# Anchors we know how to resolve. Each tuple is (prefix, base_dir).
+ANCHORS: list[tuple[str, Path]] = [
+    ("../.agent-src/skills/", ROOT / ".agent-src" / "skills"),
+    ("../.agent-src/commands/", ROOT / ".agent-src" / "commands"),
+    ("../.agent-src/rules/", ROOT / ".agent-src" / "rules"),
+    ("../agents/", ROOT / "agents"),
+    ("contracts/", DOCS_DIR / "contracts"),
+    ("guidelines/", DOCS_DIR / "guidelines"),
+]
+
+
+def resolve(url: str, doc_path: Path) -> Path | None:
+    """Return the on-disk target path for a relative link, or None if external."""
+    if url.startswith(("http://", "https://", "mailto:")):
+        return None
+    bare = url.split("#", 1)[0]
+    if not bare:
+        return None
+    # Relative to the doc's own directory.
+    target = (doc_path.parent / bare).resolve()
+    return target
+
+
+def scan(doc_path: Path) -> list[tuple[int, str]]:
+    """Return list of (line_no, url) tuples for every non-external link."""
+    if not doc_path.is_file():
+        print(f"error: missing role doc: {doc_path}", file=sys.stderr)
+        sys.exit(2)
+    links: list[tuple[int, str]] = []
+    for i, line in enumerate(doc_path.read_text(encoding="utf-8").splitlines(), 1):
+        for m in LINK_RE.finditer(line):
+            url = m.group(1)
+            if url.startswith(("http://", "https://", "mailto:")):
+                continue
+            links.append((i, url))
+    return links
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--quiet", action="store_true", help="Suppress success summary.")
+    args = p.parse_args()
+
+    failures: list[tuple[Path, int, str]] = []
+    checked = 0
+
+    for doc in ROLE_DOCS:
+        for line_no, url in scan(doc):
+            target = resolve(url, doc)
+            if target is None:
+                continue
+            checked += 1
+            if not target.exists():
+                failures.append((doc, line_no, url))
+
+    if failures:
+        print("Broken links in role docs:", file=sys.stderr)
+        for doc, line_no, url in failures:
+            rel = doc.relative_to(ROOT)
+            print(f"  {rel}:{line_no}  -> {url}", file=sys.stderr)
+        print(f"\n{len(failures)} broken / {checked} checked", file=sys.stderr)
+        return 1
+
+    if not args.quiet:
+        print(f"check_role_doc_links: {checked} links OK across {len(ROLE_DOCS)} files")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/compress.py

@@ -77,6 +77,11 @@ def _tool_active(tool_id: str) -> bool:
 # Files to copy as-is even if .md (not compressed by agent)
 COPY_AS_IS = {"README.md"}
 
+# Directories (relative to SOURCE_DIR) whose .md content is data, not prose,
+# and must be copied verbatim. Ghostwriter fixtures carry voice_samples that
+# would be destroyed by caveman compression.
+COPY_AS_IS_DIRS = frozenset({"ghostwriter"})
+
 
 def _read_augment_rules_use_symlinks() -> bool:
     """Read augment.rules_use_symlinks from .agent-settings.yml.
@@ -235,6 +240,12 @@ def should_compress(filepath: Path) -> bool:
         return False
     if filepath.name in COPY_AS_IS:
         return False
+    try:
+        rel_parts = filepath.relative_to(SOURCE_DIR).parts
+    except ValueError:
+        rel_parts = filepath.parts
+    if rel_parts and rel_parts[0] in COPY_AS_IS_DIRS:
+        return False
     return True
 
 

package/scripts/ghostwriter_fixture_allowlist.txt

@@ -0,0 +1,16 @@
+# Ghostwriter fixture allowlist
+#
+# One file stem per line (without the .md extension).
+# Every file under .agent-src.uncompressed/ghostwriter/ whose stem is
+# NOT on this list will fail `task lint-ghostwriter-source`.
+#
+# Adding a new fixture requires:
+#   1. Adding the stem here.
+#   2. Setting `fictional: true` in the file's frontmatter.
+#   3. Reviewer sign-off on the allowlist change.
+#
+# README.md is exempt (the lint skips it).
+#
+# See docs/contracts/ghostwriter-schema.md § Lint enforcement.
+
+fictional-fixture-v1

package/scripts/install

@@ -15,6 +15,10 @@
 #   --source <dir>    Package source directory (default: auto-detect)
 #   --target <dir>    Target project root (default: cwd)
 #   --profile <name>  Cost profile for bridges (minimal|balanced|full)
+#   --user-type <id>  Primary user-type for skill filtering (step-9 axis).
+#                     Valid ids: consultant | creator | developer | finance
+#                     | founder | gtm | ops. Default: empty (no filter).
+#                     Written to personal.user_type in .agent-settings.yml.
 #   --tools <list>    Comma-separated tool IDs to install (default: all).
 #                     Valid: claude-code,claude-desktop,cursor,windsurf,
 #                            cline,gemini-cli,copilot,augment,aider,codex,
@@ -82,12 +86,13 @@ SCOPE=""
 CUSTOM_PATH=""
 OFFLINE=false
 MINIMAL=false
+USER_TYPE=""
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro all"
 
 show_help() {
-    sed -n '3,54p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,58p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -146,6 +151,8 @@ while [[ $# -gt 0 ]]; do
         --target=*)      TARGET_DIR="${1#*=}"; shift ;;
         --profile)       PROFILE="$2"; shift 2 ;;
         --profile=*)     PROFILE="${1#*=}"; shift ;;
+        --user-type)     USER_TYPE="$2"; shift 2 ;;
+        --user-type=*)   USER_TYPE="${1#*=}"; shift ;;
         --tools)         TOOLS="${TOOLS:+$TOOLS,}$2"; TOOLS_EXPLICIT=true; shift 2 ;;
         --tools=*)       TOOLS="${TOOLS:+$TOOLS,}${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
         --ai)            TOOLS="${TOOLS:+$TOOLS,}$2"; TOOLS_EXPLICIT=true; shift 2 ;;
@@ -309,6 +316,7 @@ run_bridges() {
 
     local args=(--project "$TARGET_DIR" --package "$SOURCE_DIR")
     [[ -n "$PROFILE" ]] && args+=(--profile="$PROFILE")
+    [[ -n "$USER_TYPE" ]] && args+=(--user-type="$USER_TYPE")
     $FORCE && args+=(--force)
     $QUIET && args+=(--quiet)
     $GLOBAL && args+=(--global)

package/scripts/install.py

@@ -45,6 +45,8 @@ except ImportError:  # pragma: no cover — alt sys.path layout
 DEFAULT_PROFILE = "balanced"
 SUPPORTED_PROFILES = ("minimal", "balanced", "full")
 COST_PROFILE_PLACEHOLDER = "__COST_PROFILE__"
+USER_TYPE_PLACEHOLDER = "__USER_TYPE__"
+USER_TYPES_DIR = "user-types"
 
 # Env-var equivalent of --force for CI / scripted installs (P3.4).
 # When set to "1" the install run treats every conflict as
@@ -781,7 +783,44 @@ def _render_template(template: str, profile_values: "dict[str, str]") -> str:
     return body
 
 
-def ensure_agent_settings(project_root: Path, package_root: Path, profile: str, force: bool) -> None:
+def _load_valid_user_types(package_root: Path) -> list[str]:
+    """Return the sorted user-type slugs shipped under ``user-types/``.
+
+    Maps `user-types/<id>.yml` → `<id>`. The ``README.md`` is skipped.
+    Empty list when the directory is absent (older package payloads).
+    """
+    directory = package_root / USER_TYPES_DIR
+    if not directory.is_dir():
+        return []
+    return sorted(p.stem for p in directory.glob("*.yml"))
+
+
+def _validate_user_type(package_root: Path, value: str) -> str:
+    """Return the validated user-type slug (empty string allowed → no filter)."""
+    cleaned = (value or "").strip()
+    if not cleaned:
+        return ""
+    valid = _load_valid_user_types(package_root)
+    if not valid:
+        fail(
+            f"--user-type={cleaned} requested but no user-types/*.yml present "
+            f"under {package_root}"
+        )
+    if cleaned not in valid:
+        fail(
+            f"Unknown --user-type={cleaned}. Valid: {', '.join(valid)} "
+            "(empty string disables the filter)."
+        )
+    return cleaned
+
+
+def ensure_agent_settings(
+    project_root: Path,
+    package_root: Path,
+    profile: str,
+    force: bool,
+    user_type: str = "",
+) -> None:
     target = project_root / SETTINGS_FILE
     profile_source = package_root / "config" / "profiles" / f"{profile}.ini"
     template_source = package_root / "config" / "agent-settings.template.yml"
@@ -794,12 +833,16 @@ def ensure_agent_settings(project_root: Path, package_root: Path, profile: str,
     template = template_source.read_text(encoding="utf-8")
     if COST_PROFILE_PLACEHOLDER not in template:
         fail(f"Template is missing placeholder {COST_PROFILE_PLACEHOLDER}")
+    if USER_TYPE_PLACEHOLDER not in template:
+        fail(f"Template is missing placeholder {USER_TYPE_PLACEHOLDER}")
     profile_values = _parse_profile_ini(profile_source)
     if profile_values.get("cost_profile") != profile:
         fail(
             f"Profile preset {profile_source.name} has cost_profile="
             f"{profile_values.get('cost_profile')!r} but --profile={profile}"
         )
+    # Inject runtime-only values (not part of the .ini profile presets).
+    profile_values["user_type"] = _validate_user_type(package_root, user_type)
     template_body = _render_template(template, profile_values)
 
     legacy_target = project_root / LEGACY_SETTINGS_FILE
@@ -822,7 +865,9 @@ def ensure_agent_settings(project_root: Path, package_root: Path, profile: str,
         return
 
     write_file(target, template_body)
-    success(f"{SETTINGS_FILE} created (cost_profile={profile})")
+    user_type_value = profile_values.get("user_type", "")
+    suffix = f", user_type={user_type_value}" if user_type_value else ""
+    success(f"{SETTINGS_FILE} created (cost_profile={profile}{suffix})")
 
 
 def ensure_vscode_bridge(project_root: Path, package_type: str, force: bool) -> None:
@@ -3130,6 +3175,17 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
         default=DEFAULT_PROFILE,
         help=f"cost_profile value ({'|'.join(SUPPORTED_PROFILES)}, default: {DEFAULT_PROFILE})",
     )
+    parser.add_argument(
+        "--user-type",
+        dest="user_type",
+        default="",
+        help=(
+            "primary user-type for skill filtering (step-9 axis). "
+            "Valid ids: consultant | creator | developer | finance | "
+            "founder | gtm | ops. Default: empty (no filter, every skill "
+            "surfaces). Written to personal.user_type in .agent-settings.yml."
+        ),
+    )
     parser.add_argument("--force", action="store_true", help="overwrite existing files")
     parser.add_argument("--skip-bridges", action="store_true", help="only create .agent-settings.yml")
     parser.add_argument(
@@ -3236,6 +3292,18 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
             "guard). See docs/installation.md → Minimal init."
         ),
     )
+    parser.add_argument(
+        "--interactive",
+        action="store_true",
+        help=(
+            "after the install completes, run a short prompt to capture "
+            "user-type / stack / verbosity and write `.agent-config.local.json` "
+            "(forward-compatible stub for step-9 user-types axis — runtime "
+            "skill filtering activates once that axis ships). TTY-only; "
+            "no-op without an interactive stdin. See "
+            "docs/contracts/universal-skills.md for the always-loaded set."
+        ),
+    )
     opts = parser.parse_args(argv)
     opts.tools = _merge_tools_aliases(opts.tools, opts.ai)
     if opts.scope == "global" and opts.custom_path:
@@ -3342,7 +3410,7 @@ def _write_install_mode_marker(project_root: Path, mode: str) -> None:
         pass
 
 
-def install_minimal(target_root: Path, force: bool) -> int:
+def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
     """Bootstrap the project-local override layer only (D2-compliant).
 
     Writes:
@@ -3409,8 +3477,16 @@ def install_minimal(target_root: Path, force: bool) -> int:
     if settings_dst.exists() and not force:
         skip(f"{SETTINGS_FILE} already exists (use --force to overwrite)")
     else:
-        settings_dst.write_text(settings_src.read_text(encoding="utf-8"), encoding="utf-8")
-        success(f"Wrote {SETTINGS_FILE}")
+        body = settings_src.read_text(encoding="utf-8")
+        if user_type:
+            body = body.rstrip() + (
+                "\n\n# --- Personal (step-9 user-type axis) ---\n"
+                "personal:\n"
+                f"  user_type: {user_type}\n"
+            )
+        settings_dst.write_text(body, encoding="utf-8")
+        suffix = f" (user_type={user_type})" if user_type else ""
+        success(f"Wrote {SETTINGS_FILE}{suffix}")
 
     # 3. install-mode marker (Step 8 A5) — authoritative state for
     # doctor --context and future install-aware tooling. Written even
@@ -3437,6 +3513,120 @@ def install_minimal(target_root: Path, force: bool) -> int:
     return 0
 
 
+# --- Interactive init (step-12 Phase 3, forward-compatible stub) ---
+
+_INTERACTIVE_USER_TYPES: tuple[tuple[str, str], ...] = (
+    ("creator", "Content / writing / publishing"),
+    ("founder", "Early-stage company building"),
+    ("consultant", "Advisory / strategy / discovery"),
+    ("gtm", "Sales / marketing / revenue ops"),
+    ("finance", "Finance / FP&A / unit economics"),
+    ("ops", "Operations / incident / compliance"),
+    ("developer", "Engineering / code-heavy work"),
+)
+
+_INTERACTIVE_STACKS: tuple[tuple[str, str], ...] = (
+    ("none", "No code project / pure content"),
+    ("laravel", "PHP / Laravel"),
+    ("nextjs", "TypeScript / Next.js / React"),
+    ("python", "Python / FastAPI / Django"),
+    ("symfony", "PHP / Symfony"),
+    ("generic", "Other / mixed stack"),
+)
+
+_INTERACTIVE_VERBOSITIES: tuple[tuple[str, str], ...] = (
+    ("quiet", "Caveman / minimal output"),
+    ("normal", "Default verbosity"),
+    ("verbose", "Full intent announcements + play-by-play"),
+)
+
+_LOCAL_CONFIG_FILE = ".agent-config.local.json"
+
+
+def _interactive_prompt_choice(label: str, options: tuple[tuple[str, str], ...]) -> str:
+    """Render a numbered list and return the chosen id. Defaults to option 1 on empty input."""
+    print()
+    print(f"  {label}")
+    for idx, (key, blurb) in enumerate(options, start=1):
+        print(f"    {idx}. {key}  — {blurb}")
+    print()
+    while True:
+        try:
+            raw = input(f"  Choice [1-{len(options)}, default 1]: ").strip()
+        except EOFError:
+            return options[0][0]
+        if not raw:
+            return options[0][0]
+        if raw.isdigit():
+            i = int(raw)
+            if 1 <= i <= len(options):
+                return options[i - 1][0]
+        # Allow typing the slug directly.
+        for key, _ in options:
+            if raw.lower() == key:
+                return key
+        print(f"  ⚠️  Pick a number 1-{len(options)} or one of: {', '.join(k for k, _ in options)}.")
+
+
+def run_interactive_init(project_root: Path, force: bool) -> int:
+    """Write ``.agent-config.local.json`` based on three TTY prompts.
+
+    Forward-compatible stub for [`step-9-user-types-axis`](../agents/roadmaps/step-9-user-types-axis.md):
+    runtime skill filtering activates once that axis ships its
+    ``user-types/`` directory and ``--user-type`` flag. Until then,
+    this file is metadata-only — read by ``doctor --context`` and the
+    upcoming ``agent-config skills`` listing command.
+
+    Universal-skills allowlist (see
+    ``docs/contracts/universal-skills.md``) loads regardless of the
+    captured ``user_type`` — the contract guarantees these 15 skills
+    are never filtered out.
+
+    Returns 0 on success, 1 on collision without ``--force``. No-op
+    (returns 0) when stdin is not a TTY.
+    """
+    if not sys.stdin.isatty():
+        warn(
+            "--interactive requested but stdin is not a TTY; skipping the "
+            f"prompt. Re-run interactively or hand-edit {_LOCAL_CONFIG_FILE}."
+        )
+        return 0
+
+    target = project_root / _LOCAL_CONFIG_FILE
+    if target.exists() and not force:
+        warn(
+            f"{_LOCAL_CONFIG_FILE} already exists; re-run with --force to "
+            "overwrite. Skipping interactive init."
+        )
+        return 0
+
+    print()
+    info("Interactive init — captures user-type / stack / verbosity")
+    info("(forward-compatible stub; runtime filtering activates with step-9)")
+
+    user_type = _interactive_prompt_choice("Primary user type:", _INTERACTIVE_USER_TYPES)
+    stack = _interactive_prompt_choice("Project stack:", _INTERACTIVE_STACKS)
+    verbosity = _interactive_prompt_choice("Verbosity profile:", _INTERACTIVE_VERBOSITIES)
+
+    payload: dict[str, Any] = {
+        "$schema": "https://github.com/event4u-app/agent-config/scripts/schemas/local-config.schema.json",
+        "version": 1,
+        "user_type": user_type,
+        "stack": stack,
+        "verbosity": verbosity,
+        "universal_skills_contract": "docs/contracts/universal-skills.md",
+    }
+
+    try:
+        target.write_text(json.dumps(payload, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+    except OSError as exc:
+        warn(f"Could not write {target}: {exc}")
+        return 1
+
+    success(f"Wrote {target.relative_to(project_root)} ({user_type} / {stack} / {verbosity})")
+    return 0
+
+
 # --- Main ---
 
 def main(argv: list[str]) -> int:
@@ -3466,7 +3656,13 @@ def main(argv: list[str]) -> int:
         target_root = Path(
             opts.custom_path or opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
         ).resolve()
-        return install_minimal(target_root, opts.force)
+        # Validate --user-type early so the minimal short-circuit fails
+        # fast on a bogus slug instead of writing a half-formed stub.
+        # _minimal_templates_root() returns <package_root>/templates/minimal;
+        # walk two parents up to reach the package root where user-types/ lives.
+        minimal_package_root = _minimal_templates_root().parent.parent
+        validated_user_type = _validate_user_type(minimal_package_root, opts.user_type)
+        return install_minimal(target_root, opts.force, validated_user_type)
 
     # Multi-signal scope detection (Phase 1.3) + scope resolution
     # (Phase 1.4). Order of precedence (highest first):
@@ -3503,7 +3699,13 @@ def main(argv: list[str]) -> int:
 
         project_root = custom_path or Path(opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()).resolve()
         is_first_run = not (project_root / SETTINGS_FILE).exists()
-        return _main_project_install(opts, project_root, parsed_tools, is_first_run)
+        rc = _main_project_install(opts, project_root, parsed_tools, is_first_run)
+        # Interactive post-install prompt (step-12 Phase 3, forward-compatible
+        # stub). Runs only after a successful install so the local config
+        # never ships ahead of the bridge files it parameterizes.
+        if rc == 0 and getattr(opts, "interactive", False):
+            run_interactive_init(project_root, opts.force)
+        return rc
     except ConflictAbort as exc:
         warn(exc.message)
         return 1
@@ -3538,9 +3740,13 @@ def _main_project_install(
         info(f"Package:  {package_root}")
         info(f"Type:     {package_type}")
         info(f"Profile:  {opts.profile}")
+        if opts.user_type:
+            info(f"UserType: {opts.user_type}")
         print()
 
-    ensure_agent_settings(project_root, package_root, opts.profile, opts.force)
+    ensure_agent_settings(
+        project_root, package_root, opts.profile, opts.force, opts.user_type
+    )
 
     # Install-mode marker (Step 8 A5) — full path flips any prior
     # minimal marker to "full" so doctor --context reflects the

package/scripts/install.sh

@@ -79,6 +79,13 @@ parse_args() {
             --skip-gitignore) SKIP_GITIGNORE=true; shift ;;
             --tools)   TOOLS="$2"; shift 2 ;;
             --tools=*) TOOLS="${1#*=}"; shift ;;
+            # --user-type is consumed by install.py (settings persistence).
+            # Accepted here so direct `bash scripts/install.sh --user-type=...`
+            # invocations from the `install` wrapper / standalone users do not
+            # trip the "Unknown argument" guard. Value is intentionally unused
+            # by the payload-sync stage.
+            --user-type)   shift 2 ;;
+            --user-type=*) shift ;;
             --minimal|--settings-only) MINIMAL=true; shift ;;
             --help|-h) show_help; exit 0 ;;
             *) log_error "Unknown argument: $1"; show_help; exit 1 ;;