@event4u/agent-config 2.15.0 → 2.17.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/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/update-github-metadata.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# scripts/update-github-metadata.sh
+#
+# Step-12 Phase 6 L113 — apply the Universal-OS reframe to GitHub repo
+# metadata (description + topics). Drafted per AI-Council verdict
+# 2026-05-15-step12-final-push (Decision 3 AMEND: reviewable script,
+# explicit maintainer approval to execute).
+#
+# Iron Law (.augment/rules/non-destructive-by-default.md):
+#   GitHub repo description/topics are PUBLIC project metadata.
+#   This script does NOT auto-run. Maintainer must invoke it explicitly.
+#
+# Usage:
+#   ./scripts/update-github-metadata.sh            # dry-run (prints curl payload)
+#   ./scripts/update-github-metadata.sh --apply    # actually call the API
+#
+# Rollback:
+#   gh api repos/event4u-app/agent-config --method PATCH \
+#     -f description="agent-config — Behavior, Memory and Delivery Governance for AI Agents"
+#   (Topics: re-PUT the original list from `gh api repos/event4u-app/agent-config | jq .topics`.)
+set -euo pipefail
+
+OWNER_REPO="event4u-app/agent-config"
+
+NEW_DESCRIPTION="Universal AI Agent OS — governed skills, rules, commands for developers, founders, creators, GTM, finance/ops"
+
+# Existing topics preserved; reframe topics appended.
+TOPICS=(
+  "agent-rules"
+  "agent-skills"
+  "agentic-ai"
+  "agentskills-standard"
+  "ai-coding"
+  "augment-agent"
+  "claude-code"
+  "copilot"
+  "devcontainer"
+  "governance"
+  "laravel"
+  "php"
+  "react"
+  "symfony"
+  "universal-ai-os"
+  "ai-governance"
+  "non-developer-tools"
+)
+
+APPLY="${1:-}"
+
+if [[ "${APPLY}" != "--apply" ]]; then
+  echo "=== DRY RUN — no API call ==="
+  echo "Target repo:     ${OWNER_REPO}"
+  echo "New description: ${NEW_DESCRIPTION}"
+  echo "New topics:"
+  printf '  - %s\n' "${TOPICS[@]}"
+  echo
+  echo "To apply, re-run with --apply (requires gh authenticated as repo admin)."
+  exit 0
+fi
+
+# Apply path — requires gh CLI authenticated.
+if ! command -v gh >/dev/null 2>&1; then
+  echo "error: gh CLI not found. Install from https://cli.github.com." >&2
+  exit 1
+fi
+
+echo "Applying description …"
+gh api "repos/${OWNER_REPO}" \
+  --method PATCH \
+  -f "description=${NEW_DESCRIPTION}" \
+  --silent
+
+echo "Applying topics …"
+TOPIC_ARGS=()
+for t in "${TOPICS[@]}"; do
+  TOPIC_ARGS+=(-f "names[]=${t}")
+done
+gh api "repos/${OWNER_REPO}/topics" \
+  --method PUT \
+  -H "Accept: application/vnd.github.mercy-preview+json" \
+  "${TOPIC_ARGS[@]}" \
+  --silent
+
+echo "Done. Verify at https://github.com/${OWNER_REPO}"

package/templates/agent-config-wrapper.sh

@@ -21,6 +21,13 @@ set -euo pipefail
 
 SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
+# Step-7 Phase 3 — pin the project root for the master CLI so subdir
+# invocations of ``./agent-config`` (or symlinks to it) do not re-walk
+# the anchor tree. The wrapper lives at the project root by definition,
+# so SELF_DIR *is* the canonical root. Honor a pre-set value as an
+# escape hatch (test harnesses, supervisors that already pinned it).
+export AGENT_CONFIG_PROJECT_ROOT="${AGENT_CONFIG_PROJECT_ROOT:-$SELF_DIR}"
+
 locate_master() {
   if [[ -n "${AGENT_CONFIG_MASTER:-}" && -x "$AGENT_CONFIG_MASTER" ]]; then
     printf '%s' "$AGENT_CONFIG_MASTER"

package/templates/minimal/.agent-settings.yml

@@ -0,0 +1,23 @@
+# Agent Settings — minimal stub
+#
+# Created by `agent-config init --minimal`. This file marks the project as
+# an agent-config layer without installing any tool payload. The global
+# `agent-config` binary on $PATH supplies the rules / skills / commands;
+# this file is your per-project override point.
+#
+# Resolution order (deepest wins, see docs/contracts/layered-settings.md):
+#   1. <repo-root>/.agent-settings.yml  ← this file
+#   2. ~/.event4u/agent-config/agent-settings.yml  (user-global; whitelisted)
+#
+# Add keys here as you need them. Reference template:
+#   templates/consumer-settings/  or  docs/customization.md
+
+# --- Cost profile ---
+# Master switch for which rule tiers load. Options: minimal | balanced | full.
+# `balanced` is the recommended default; flip to `minimal` for kernel-only.
+cost_profile: balanced
+
+# --- Version pin (opt-in) ---
+# Leave commented out to follow whatever `agent-config` is on $PATH (per D4).
+# Uncomment and pin to a specific release for reproducible installs.
+# agent_config_version: ""

package/templates/minimal/agents-gitkeep

@@ -0,0 +1,2 @@
+# Placeholder so `agents/` is committable in a fresh `--minimal` install.
+# Rename / remove once you add real content under agents/ (roadmaps, contexts, …).