@event4u/agent-config 1.15.0 → 1.17.0

package/scripts/skill_linter.py

@@ -136,9 +136,7 @@ def read_text(path: Path) -> str:
 # --- Role-contract anchor cache (see road-to-role-modes Phase 1) ---
 # Populated lazily so the linter stays fast when the guideline is absent.
 _ROLE_CONTRACT_CANDIDATES = (
-    Path(".agent-src.uncompressed/guidelines/agent-infra/role-contracts.md"),
-    Path(".agent-src/guidelines/agent-infra/role-contracts.md"),
-    Path(".augment/guidelines/agent-infra/role-contracts.md"),
+    Path("docs/guidelines/agent-infra/role-contracts.md"),
 )
 _ROLE_CONTRACT_SLUGS_CACHE: Optional[set[str]] = None
 
@@ -373,7 +371,8 @@ def lint_skill(path: Path, text: str) -> LintResult:
 
     if description:
         if len(description) > 200:
-            issues.append(Issue("warning", "description_too_long", "Description is longer than 200 characters"))
+            issues.append(Issue("error", "description_too_long",
+                                f"Description is {len(description)} chars (hard cap: 200) — see road-to-governance-cleanup F6"))
         for pattern in TRIGGER_WARNING_PATTERNS:
             if re.search(pattern, description, re.IGNORECASE):
                 issues.append(Issue("warning", "weak_trigger", f"Description looks too generic: {description}"))
@@ -716,6 +715,12 @@ def lint_rule(path: Path, text: str) -> LintResult:
             if not description:
                 issues.append(Issue("error", "auto_missing_description", "Auto rules require a 'description' field for matching"))
 
+        # description length cap (F6 — 200-char hard cap, see road-to-governance-cleanup)
+        rule_description = extract_description(text)
+        if rule_description and len(rule_description) > 200:
+            issues.append(Issue("error", "description_too_long",
+                                f"Description is {len(rule_description)} chars (hard cap: 200) — see road-to-governance-cleanup F6"))
+
         # always-rules that look like auto candidates (rule-type-governance check)
         if rule_type == "always":
             description = extract_description(text) or ""
@@ -863,6 +868,9 @@ def lint_command(path: Path, text: str) -> LintResult:
         description = extract_description(text)
         if not description:
             issues.append(Issue("warning", "missing_description", "Frontmatter description is missing"))
+        elif len(description) > 200:
+            issues.append(Issue("error", "description_too_long",
+                                f"Description is {len(description)} chars (hard cap: 200) — see road-to-governance-cleanup F6"))
 
         # suggestion block (road-to-context-aware-command-suggestion Phase 2)
         issues.extend(_lint_command_suggestion_block(text))
@@ -878,6 +886,7 @@ def lint_command(path: Path, text: str) -> LintResult:
                     "error", "shim_missing_warning",
                     "Deprecation shim must contain a one-line warning matching "
                     "'⚠️  /<old-name> is deprecated; use /<cluster> <sub> instead.'"
+                    " (or '/<cluster> --<flag>' for flag-clusters)"
                     " (see docs/contracts/command-clusters.md § Deprecation shim contract)"
                 ))
 

package/scripts/sync_agent_settings.py

@@ -2,7 +2,7 @@
 """Sync `.agent-settings.yml` against the template + profile.
 
 Applies the section-aware merge rules documented in
-`.agent-src.uncompressed/guidelines/agent-infra/layered-settings.md`:
+`docs/guidelines/agent-infra/layered-settings.md`:
 
 - Template section order always wins — reorder keys to match.
 - Existing user scalar values are preserved verbatim (as parsed).
@@ -136,8 +136,31 @@ def _append_unknown(body: str, user_flat: dict[str, object], known: set[str]) ->
 
 
 def render_target(template_body: str, user_data: dict) -> str:
-    """Return the desired `.agent-settings.yml` body for the given user data."""
-    user_flat = _flatten(user_data) if user_data else {}
+    """Return the desired `.agent-settings.yml` body for the given user data.
+
+    The trailing ``_user:`` block (emitted by :func:`_append_unknown`) is
+    already in dotted-key form on every read after the first sync. Re-
+    flattening it would prepend another ``_user.`` segment on every run
+    and accumulate forever, so we strip the wrapper and merge its
+    contents straight into the flat dict.
+    """
+    if user_data:
+        user_only = user_data.pop("_user", None) if isinstance(user_data, dict) else None
+        user_flat = _flatten(user_data)
+        if isinstance(user_only, dict):
+            for key, value in user_only.items():
+                # Dotted keys round-trip verbatim — never re-flatten them.
+                if isinstance(key, str):
+                    # Heal legacy corruption: pre-fix syncs prepended a
+                    # `_user.` segment per run, so a key may carry an
+                    # arbitrary number of them. Strip them all back to
+                    # the original leaf path.
+                    healed = key
+                    while healed.startswith("_user."):
+                        healed = healed[len("_user."):]
+                    user_flat[healed] = value
+    else:
+        user_flat = {}
     known = _template_keys(template_body)
     body = _apply_user_values(template_body, user_flat)
     return _append_unknown(body, user_flat, known)

package/scripts/update_counts.py

@@ -28,14 +28,22 @@ def count(kind: str) -> int:
     if kind == "skills":
         return sum(1 for _ in (SRC / "skills").rglob("SKILL.md"))
     if kind == "guidelines":
-        # guidelines are grouped by topic subdirectory
-        return sum(1 for _ in (SRC / "guidelines").rglob("*.md"))
+        # Guidelines live under docs/guidelines/{topic}/ — they are reference
+        # material, not packaged artefacts. Recursive walk to count every .md.
+        return sum(1 for _ in (REPO_ROOT / "docs" / "guidelines").rglob("*.md"))
     if kind == "personas":
         # personas live as flat .md files, README excluded
         pdir = SRC / "personas"
         if not pdir.exists():
             return 0
         return sum(1 for f in pdir.glob("*.md") if f.name != "README.md")
+    if kind == "commands":
+        # Commands may be flat (`commands/<name>.md`) or nested under a
+        # cluster directory (`commands/<cluster>/<sub>.md`). Walk the tree
+        # and skip the AGENTS.md reference orchestrator.
+        return sum(
+            1 for f in (SRC / kind).rglob("*.md") if f.name != "AGENTS.md"
+        )
     return sum(1 for _ in (SRC / kind).glob("*.md"))
 
 
@@ -47,12 +55,16 @@ TARGETS: list[tuple[str, list[tuple[str, str]]]] = [
         [
             (r"(Browse all )(\d+)( commands\])", "commands"),
             (r"(package \(rules \+ )(\d+)( skills)", "skills"),
-            (r"(skills \+ )(\d+)( native commands)", "commands"),
             # Hero line: **NNN Skills** · **NNN Rules** · **NNN Commands** · **NNN Guidelines**
             (r"(<strong>)(\d+)( Skills</strong>)", "skills"),
             (r"(<strong>)(\d+)( Rules</strong>)", "rules"),
-            (r"(<strong>)(\d+)( Commands</strong>)", "commands"),
             (r"(<strong>)(\d+)( Guidelines</strong>)", "guidelines"),
+            # NOTE: hero `<strong>N Commands</strong>` and tools-blurb
+            # `skills + N native commands` are owned by
+            # `check_command_count_messaging.py` (Phase-1.2 of
+            # road-to-pr-34-followups). Those surfaces advertise the
+            # **active** command count (total − deprecation shims), not
+            # the raw file count this script computes.
         ],
     ),
     (

package/scripts/update_prices.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Refresh `.agent-prices.md` from the LiteLLM model-prices feed.
+
+Source: https://raw.githubusercontent.com/BerriAI/litellm/main/
+        model_prices_and_context_window.json
+
+Network failure or invalid response → fall back to
+`scripts.ai_council._default_prices.DEFAULT_PRICES` so the file is
+always written. Stdlib only; no extra dependency.
+
+Usage:
+    python3 scripts/update_prices.py            # writes .agent-prices.md
+    python3 scripts/update_prices.py --check    # exit 1 if file is stale
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT))
+
+from scripts.ai_council._default_prices import DEFAULT_PRICES, as_rows  # noqa: E402
+from scripts.ai_council.pricing import (  # noqa: E402
+    PRICES_FILE,
+    _render_markdown,
+    is_stale,
+    load_prices,
+)
+
+LITELLM_URL = (
+    "https://raw.githubusercontent.com/BerriAI/litellm/main/"
+    "model_prices_and_context_window.json"
+)
+HTTP_TIMEOUT_SECONDS = 10
+
+# Models we surface in the table. Anything not in this allow-list is
+# dropped from the LiteLLM payload; users can add more by editing the
+# Markdown file directly.
+ALLOW_LIST: set[tuple[str, str]] = set(DEFAULT_PRICES.keys())
+
+
+def _fetch_litellm() -> dict[str, dict[str, object]] | None:
+    try:
+        req = urllib.request.Request(LITELLM_URL, headers={"User-Agent": "agent-config"})
+        with urllib.request.urlopen(req, timeout=HTTP_TIMEOUT_SECONDS) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        if not isinstance(data, dict):
+            return None
+        return data
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, OSError) as exc:
+        print(f"[update_prices] upstream unreachable: {exc}", file=sys.stderr)
+        return None
+
+
+def _to_rows_from_litellm(payload: dict[str, dict[str, object]]) -> list[tuple[str, str, float, float]]:
+    """Translate LiteLLM keys into our (provider, model, input_per_1m, output_per_1m) tuples."""
+    rows: list[tuple[str, str, float, float]] = []
+    for key, entry in payload.items():
+        if not isinstance(entry, dict):
+            continue
+        provider = str(entry.get("litellm_provider", "")).lower()
+        # LiteLLM keys are sometimes "provider/model"; strip the prefix.
+        model = key.split("/", 1)[1] if "/" in key else key
+        if (provider, model) not in ALLOW_LIST:
+            continue
+        in_cost = entry.get("input_cost_per_token")
+        out_cost = entry.get("output_cost_per_token")
+        if not isinstance(in_cost, (int, float)) or not isinstance(out_cost, (int, float)):
+            continue
+        # LiteLLM ships per-token USD; convert to per-1M.
+        rows.append((provider, model, float(in_cost) * 1_000_000, float(out_cost) * 1_000_000))
+    rows.sort()
+    return rows
+
+
+def refresh(path: Path = PRICES_FILE) -> str:
+    """Write a fresh `.agent-prices.md`. Returns the source label used."""
+    payload = _fetch_litellm()
+    if payload is not None:
+        rows = _to_rows_from_litellm(payload)
+        if rows:
+            today = _dt.datetime.now(_dt.timezone.utc).date().isoformat()
+            path.write_text(_render_markdown(today, "litellm-github", rows), encoding="utf-8")
+            return "litellm-github"
+    # Network or filter failed → shipped defaults.
+    today = _dt.datetime.now(_dt.timezone.utc).date().isoformat()
+    path.write_text(_render_markdown(today, "shipped-default", as_rows()), encoding="utf-8")
+    return "shipped-default"
+
+
+def _cmd_check(path: Path) -> int:
+    if not path.exists():
+        print(f"[update_prices] {path} missing — run `python3 scripts/update_prices.py`")
+        return 1
+    table = load_prices(path)
+    if is_stale(table):
+        print(f"[update_prices] {path} stale (last_updated={table.last_updated})")
+        return 1
+    print(f"[update_prices] {path} fresh (last_updated={table.last_updated})")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="exit 1 if stale")
+    parser.add_argument("--path", default=str(PRICES_FILE), help="override target path")
+    args = parser.parse_args()
+    target = Path(args.path)
+    if args.check:
+        return _cmd_check(target)
+    src = refresh(target)
+    print(f"[update_prices] wrote {target} (source={src})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agent-src/guidelines/php/git.md

@@ -1,96 +0,0 @@
-# Git & Version Control Guidelines
-
-> Project-specific Git conventions. Branch naming, commit messages, PR workflow.
-
-**Related Skills:** `git-workflow`, `conventional-commits-writing`
-**Related Rules:** `commit-conventions.md`
-
-## Branch Naming
-
-```
-{type}/{ticket-id}/{short-description}
-```
-
-Types: `feat/`, `fix/`, `hotfix/`, `chore/`, `docs/`, `test/`
-
-```
-feat/DEV-1234/user-notification-preferences
-fix/DEV-5678/null-pointer-in-import
-chore/refactor-agent-setup
-hotfix/DEV-999/critical-payment-bug
-```
-
-## Commit Messages
-
-See `commit-conventions` rule for base format. Key type selection:
-
-- `feat` — new capability. `fix` — bug/regression. `refactor` — structure only, NO behavior change.
-- `docs` — docs only. `test` — tests only. `ci` — CI/workflows. `chore` — maintenance/cleanup.
-- `perf` — performance. `build` — build tooling. `style` — formatting only.
-
-**Scope:** Jira ID or area name (`api`, `auth`, `skills`). Only add when it improves clarity.
-
-**Description:** Intent, not implementation. Imperative mood. Max 72 chars. No generic filler.
-
-**Breaking:** `!` after type/scope or `BREAKING CHANGE:` footer.
-
-```
-feat(api)!: rename invoice status values
-refactor(auth)!: remove legacy session flow
-```
-
-**Splitting:** Mixed concerns → split commits. Don't hide unrelated changes in one.
-
-```
-refactor(skills): remove duplicate routing helpers
-ci(lint): add skill-lint workflow
-docs(readme): document new lint tasks
-```
-
-**Squash merge titles:** Conventional Commit format, describe net effect, not every internal commit.
-
-### Anti-patterns
-
-- `update stuff` / `fix bug` / `changes`
-- `refactor` for bug fixes, `chore` for behavior changes
-- Multiple unrelated concerns in one commit
-
-### Decision checklist
-
-1. Behavior changed? → `feat` or `fix`
-2. Structure only? → `refactor`
-3. Only docs/tests/CI? → `docs`/`test`/`ci`
-4. Scope useful or noise?
-5. Multiple commits hiding in one?
-
-### Examples by area
-
-```bash
-# Features
-feat(DEV-2133): send email to customer when product is shipped
-
-# Bug fixes
-fix(import): handle null values in equipment JSON
-
-# Refactoring
-refactor: extract user sync logic into dedicated service
-
-# Skills / Rules / Agent config
-refactor(skills): merge duplicate analysis skills
-feat(rules): add analysis routing quality gate
-fix(skills): restore concrete validation in skill reviewer
-
-# CI / Tooling
-ci(lint): add skill linter workflow
-feat(linter): detect pointer-only skills
-
-# Docs
-docs(roadmap): add phase 3 implementation plan
-docs(readme): clarify source-of-truth workflow
-```
-
-## Pull Requests
-
-- PR title: Conventional Commit format — `feat(DEV-1234): short description`
-- Fill PR template, link Jira ticket, ensure quality gates pass
-

package/.agent-src/rules/command-suggestion.md

@@ -1,134 +0,0 @@
----
-type: "always"
-description: "Surface matching slash commands as numbered options when user intent matches a command's purpose — never auto-executes; user always picks (read-only suggestion layer)."
-alwaysApply: true
-source: package
----
-
-# Command Suggestion
-
-When the user's prompt matches an eligible slash command, surface it
-as a **numbered option** alongside an "as-is" escape hatch. The user
-always picks. **Nothing auto-executes.** The suggestion layer is a
-read-only shortcut *finder*, not an invocation path.
-
-The deterministic engine lives in `scripts/command_suggester/`. The
-locked eligibility table lives in
-[`agents/contexts/command-suggestion-eligibility.md`](../../agents/contexts/command-suggestion-eligibility.md).
-The full design lives in
-[`road-to-context-aware-command-suggestion`](../../agents/roadmaps/road-to-context-aware-command-suggestion.md).
-
-## Iron Law — never auto-execute
-
-```
-SUGGEST. NEVER INVOKE. THE USER PICKS, ALWAYS.
-```
-
-A suggestion block emits options. It does **not** start a command
-flow. The user picking option N triggers `slash-commands` on the
-**next** turn — with all the command's own halts intact.
-
-## When to fire
-
-On a user turn that matches **all** of the following:
-
-1. The message does **not** start with an explicit `/command` (those
-   bypass suggestion entirely — see `slash-commands`).
-2. `commands.suggestion.enabled` is `true` (default).
-3. The user has not issued `/command-suggestion-off` in this conversation.
-4. No clarification is owed for the same turn (per
-   `ask-when-uncertain` — clarification wins; suggestion can fire next turn).
-5. No active engine flow is mid-halt (e.g. an `/implement-ticket`
-   step waiting on the user — the active flow has the floor).
-6. The matcher returns at least one match above the effective
-   `confidence_floor` after rank + cooldown + anti-noise.
-
-When all six hold, the suggestion block is the **first and only**
-thing the agent emits that turn. No tools, no edits, no other prose.
-
-## What to emit
-
-Render exactly one numbered-options block conforming to
-`user-interaction`:
-
-```
-> 💡 Your request matches a command. Pick one or run the prompt as-is:
->
-> 1. /implement-ticket — drive ticket end-to-end through refine → plan → implement → test
-> 2. /refine-ticket — tighten the AC and risks on a ticket before planning
-> 3. Just run the prompt as-is, no command
-
-**Recommendation: 1 — /implement-ticket** — the request matches its trigger description (`setze ticket abc-123 um`). Pick the last option to skip the command and run the prompt as written.
-```
-
-Rules — non-negotiable:
-
-- The "run as-is" option is **always present**, **always last**, never removed.
-- At most `commands.suggestion.max_options` command suggestions
-  precede the as-is option (default 4 → 5 total).
-- Exactly **one** `Recommendation:` line follows the block, naming
-  the highest-scoring command — or no recommendation when the top
-  two scores are within 0.05 of each other (single-source-of-truth
-  Iron Law from `user-interaction`).
-- Free-text replies count as the as-is option unless they
-  unambiguously name one of the listed commands.
-
-## Subordination — when to stay silent
-
-The suggestion rule is **junior** to:
-
-- `scope-control` — never surfaces a git-op command behind a
-  permission gate the user already declined this turn.
-- `ask-when-uncertain` — if a clarification is owed, the
-  clarification is the only question; suggestion suppresses for
-  that turn.
-- `verify-before-complete` — suggestion does not interrupt an
-  evidence-gate verification that's already running.
-- Any active role-mode contract (`role-mode-adherence`).
-- Any active engine halt (`/implement-ticket`, `/work`, etc.).
-
-On any conflict → suggestion stays silent. Zero output. The user's
-prompt is processed as it would be without this rule.
-
-## Anti-noise — silent when uncertain
-
-The engine's `rank.py` already drops:
-
-- Matches below the `confidence_floor` (default 0.6, per-command
-  override in frontmatter).
-- Single matches scoring `< floor + 0.1` with no structural bonus
-  (high uncertainty isn't worth interrupting for).
-- Short prompts (< 6 words) hitting > 2 commands with no structural
-  bonus (ticket key, file path) — too vague to disambiguate.
-- Pure-continuation messages (`ok`, `weiter`, `mach weiter`, `go on`,
-  …) — no new intent signal, no structural bonus → silent.
-- Suggestions that fired for the same `(command, evidence)` pair
-  within the cooldown window (default 10m, per-command override).
-
-If the engine returns an empty list → emit nothing. The user's
-prompt runs exactly as it would without this rule.
-
-## What this rule does NOT do
-
-- Invoke any command. Picking option N is what triggers `slash-commands`.
-- Stack with other questions. One numbered-options block per turn.
-- Re-trigger on its own output. Command names emitted in the
-  suggestion block are excluded from the next-turn matcher input.
-- Override `enabled: false`, blocklist entries, or per-conversation opt-out.
-- Suggest commands that are not in the locked eligibility table.
-
-## Cloud Behavior
-
-On cloud surfaces (Claude.ai Web, Skills API) the rule is **inert**
-unless the suggester package is shipped in the bundle. Treat
-`commands.suggestion.enabled` as `false` when the engine is not
-available — degrade silently, never crash the turn.
-
-## Interactions
-
-- [`slash-commands`](slash-commands.md) — explicit `/command` skips suggestion entirely.
-- [`user-interaction`](user-interaction.md) — numbered-options Iron Law and single-source recommendation.
-- [`ask-when-uncertain`](ask-when-uncertain.md) — clarification wins on conflict.
-- [`scope-control`](scope-control.md) — git-op gates outrank suggestion.
-- [`role-mode-adherence`](role-mode-adherence.md) — active mode contract outranks suggestion.
-- [`agents/contexts/command-suggestion-eligibility.md`](../../agents/contexts/command-suggestion-eligibility.md) — locked eligibility table.