@event4u/agent-config 1.20.0 → 1.22.0

package/scripts/skill_linter.py

@@ -117,6 +117,17 @@ VALID_RULE_TYPES = {"always", "auto"}
 VALID_RULE_SOURCES = {"package", "project"}
 VALID_STATUSES = {"active", "deprecated", "superseded"}
 
+# --- Router schema (docs/contracts/rule-router.md) ---
+ROUTER_ALLOWED_TRIGGER_KEYS = {"keyword", "phrase", "intent", "file_pattern",
+                               "path_prefix", "command"}
+ROUTER_ALLOWED_PROFILES = {"minimal", "balanced", "full"}
+KERNEL_RULE_IDS: set[str] = {
+    "agent-authority", "ask-when-uncertain", "commit-policy",
+    "direct-answers", "language-and-tone", "no-cheap-questions",
+    "non-destructive-by-default", "scope-control",
+    "verify-before-complete",
+}
+
 # --- Runtime execution metadata constants ---
 VALID_EXECUTION_TYPES = {"manual", "assisted", "automated"}
 VALID_EXECUTION_HANDLERS = {"none", "shell", "php", "node", "internal"}
@@ -220,6 +231,42 @@ def extract_sections(text: str) -> set[str]:
     return {match.group(1).strip() for match in SECTION_PATTERN.finditer(text)}
 
 
+def _count_code_blocks(text: str) -> int:
+    """Return the number of fenced code blocks (``` … ```) in *text*."""
+    fence_count = 0
+    for line in text.splitlines():
+        stripped = line.lstrip()
+        if stripped.startswith("```"):
+            fence_count += 1
+    return fence_count // 2
+
+
+def _fenced_content_ratio(text: str) -> float:
+    """Return the fraction of non-empty lines that sit inside fenced blocks.
+
+    Used as a structural signal: rules / files dominated by verbatim Iron-Law
+    blocks or worked examples score high and are exempted from raw line-count
+    warnings (council review 2026-05-06).
+    """
+    inside = False
+    fenced_lines = 0
+    non_empty = 0
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            inside = not inside
+            if stripped:
+                non_empty += 1
+            continue
+        if stripped:
+            non_empty += 1
+            if inside:
+                fenced_lines += 1
+    if non_empty == 0:
+        return 0.0
+    return fenced_lines / non_empty
+
+
 def extract_description(text: str) -> Optional[str]:
     frontmatter = FRONTMATTER_PATTERN.search(text)
     if not frontmatter:
@@ -495,8 +542,12 @@ def lint_skill(path: Path, text: str) -> LintResult:
             suggestions.append("Add a requirement-checking or validation step before implementation")
 
     # --- Size check (see guidelines/agent-infra/size-and-scope.md) ---
+    # Threshold raised from 300 → 400 (council review 2026-05-06): reference-rich
+    # skills (quality-tools 411, ai-council 399, project-analyzer 341) legitimately
+    # exceed 300 lines without being split-candidates. Structural follow-up tracked
+    # in agents/roadmaps/road-to-structural-linter-reform.md.
     total_lines = len(text.splitlines())
-    if total_lines > 300:
+    if total_lines > 400:
         issues.append(Issue("warning", "skill_too_large", f"Skill has {total_lines} lines; review for split (see size-and-scope guideline)"))
 
     # --- Pointer-only / guideline-dependent skill detection ---
@@ -553,6 +604,131 @@ def extract_frontmatter(text: str) -> Optional[str]:
     return match.group(1) if match else None
 
 
+def _parse_yaml_list(frontmatter: str, key: str) -> Optional[list]:
+    """Parse a simple top-level YAML list `key:` from frontmatter.
+
+    Supports the two shapes we emit in rule frontmatter:
+      triggers:
+        - keyword: "foo"
+        - phrase: "bar baz"
+      routes_to:
+        - skill:php-coder
+        - guideline:agent-infra/asking-and-brevity-examples
+
+    Returns ``None`` if the key is absent (so the caller can distinguish
+    "missing" from "empty"); returns ``[]`` for an explicitly empty list.
+    """
+    lines = frontmatter.splitlines()
+    out: list = []
+    in_block = False
+    for line in lines:
+        if not in_block:
+            if line.startswith(f"{key}:"):
+                rhs = line[len(key) + 1:].strip()
+                if rhs in ("", "[]"):
+                    if rhs == "[]":
+                        return []
+                    in_block = True
+                else:
+                    return None  # unexpected scalar shape
+            continue
+        if line.startswith("  - "):
+            item = line[4:].strip()
+            if ":" in item and not item.startswith(("'", '"')):
+                k, _, v = item.partition(":")
+                out.append({k.strip(): v.strip().strip('"').strip("'")})
+            else:
+                out.append(item.strip('"').strip("'"))
+        elif line.strip() == "" or line.startswith("    "):
+            continue
+        else:
+            break
+    return out if in_block else None
+
+
+def lint_router_frontmatter(rule_id: str, frontmatter: str,
+                             rule_type: Optional[str]) -> List[Issue]:
+    """Validate `triggers:` / `routes_to:` per docs/contracts/rule-router.md.
+
+    Strict checks (always errors): kernel rules MUST NOT carry router fields;
+    `triggers:` items must use one allowed key; `routes_to:` items must
+    follow `kind:id` with kind ∈ {skill, guideline} and the target file
+    must exist on disk.
+
+    Lenient checks (info-level until Phase 4 migrations land): non-kernel
+    rules without `triggers:` / `routes_to:` get an informational note,
+    not an error — the existing description-matching path still works.
+    """
+    issues: List[Issue] = []
+    triggers = _parse_yaml_list(frontmatter, "triggers")
+    routes_to = _parse_yaml_list(frontmatter, "routes_to")
+
+    is_kernel = rule_id in KERNEL_RULE_IDS or rule_type == "always"
+
+    if is_kernel:
+        if triggers is not None:
+            issues.append(Issue("error", "kernel_has_triggers",
+                "Kernel rules MUST NOT declare triggers: (kernel is unconditional)"))
+        if routes_to is not None:
+            issues.append(Issue("error", "kernel_has_routes_to",
+                "Kernel rules MUST NOT declare routes_to: (kernel body stays inline)"))
+        return issues
+
+    # Non-kernel rule path
+    if triggers is None:
+        issues.append(Issue("info", "router_triggers_missing",
+            "Non-kernel rule has no triggers: — falls back to description matching "
+            "until Phase 4 migration lands"))
+    else:
+        for idx, item in enumerate(triggers):
+            if not isinstance(item, dict) or len(item) != 1:
+                issues.append(Issue("error", "trigger_shape_invalid",
+                    f"triggers[{idx}] must be a single-key mapping"))
+                continue
+            (k,) = item.keys()
+            if k not in ROUTER_ALLOWED_TRIGGER_KEYS:
+                allowed = ", ".join(sorted(ROUTER_ALLOWED_TRIGGER_KEYS))
+                issues.append(Issue("error", "trigger_key_unknown",
+                    f"triggers[{idx}] key '{k}' not in allowed set ({allowed})"))
+
+    if routes_to is None:
+        issues.append(Issue("info", "router_routes_to_missing",
+            "Non-kernel rule has no routes_to: — body should migrate to skill / "
+            "guideline in Phase 4"))
+    else:
+        repo_root = Path(__file__).resolve().parent.parent
+        for idx, item in enumerate(routes_to):
+            if not isinstance(item, str) or ":" not in item:
+                issues.append(Issue("error", "route_shape_invalid",
+                    f"routes_to[{idx}] must be 'kind:id'"))
+                continue
+            kind, _, target_id = item.partition(":")
+            if kind == "skill":
+                target = repo_root / ".agent-src.uncompressed" / "skills" / target_id / "SKILL.md"
+            elif kind == "guideline":
+                target = repo_root / "docs" / "guidelines" / f"{target_id}.md"
+            elif kind == "command":
+                target = repo_root / ".agent-src.uncompressed" / "commands" / f"{target_id}.md"
+            elif kind == "contract":
+                # Contracts live in two places: stable host docs in
+                # docs/contracts/ and load-bearing flows in
+                # .agent-src.uncompressed/contexts/contracts/ (road-to-path-fixes
+                # P4 / Council R2). Try both before failing.
+                target = repo_root / "docs" / "contracts" / f"{target_id}.md"
+                if not target.exists():
+                    alt = repo_root / ".agent-src.uncompressed" / "contexts" / "contracts" / f"{target_id}.md"
+                    if alt.exists():
+                        target = alt
+            else:
+                issues.append(Issue("error", "route_kind_unknown",
+                    f"routes_to[{idx}] kind '{kind}' must be 'skill', 'guideline', 'command', or 'contract'"))
+                continue
+            if not target.exists():
+                issues.append(Issue("error", "route_target_missing",
+                    f"routes_to[{idx}] target '{item}' not found at {target}"))
+    return issues
+
+
 def extract_frontmatter_field(frontmatter: str, pattern: re.Pattern[str]) -> Optional[str]:
     match = pattern.search(frontmatter)
     return match.group(1).strip() if match else None
@@ -801,6 +977,9 @@ def lint_rule(path: Path, text: str) -> LintResult:
                                     f"Always-rule with topic-specific description ({', '.join(topic_keywords)}) — "
                                     f"consider auto type per rule-type-governance"))
 
+        # Router schema validation (docs/contracts/rule-router.md, Phase 3.3).
+        issues.extend(lint_router_frontmatter(path.stem, frontmatter, rule_type))
+
     # --- Structure checks ---
     # H1 heading
     if not H1_PATTERN.search(text):
@@ -817,14 +996,18 @@ def lint_rule(path: Path, text: str) -> LintResult:
         issues.append(Issue("warning", "double_blank_lines", "File contains double or triple blank lines"))
 
     # --- Content checks (see guidelines/agent-infra/size-and-scope.md) ---
+    # Length thresholds gated by fenced-content density (council review 2026-05-06):
+    # rules dominated by verbatim Iron-Law blocks / worked examples are protected
+    # from the > 40 / > 60 warnings. Hard error at 200 stays unconditional.
     line_count = len([line for line in text.splitlines() if line.strip()])
     total_lines = len(text.splitlines())
+    fenced_ratio = _fenced_content_ratio(text)
     if total_lines > 200:
         issues.append(Issue("error", "rule_too_large", f"Rule has {total_lines} lines (hard limit: 200); must split or move to guideline"))
-    elif line_count > 60:
-        issues.append(Issue("warning", "long_rule", f"Rule has {line_count} non-empty lines; prefer < 60 (see size-and-scope guideline)"))
-    elif line_count > 40:
-        issues.append(Issue("warning", "long_rule", f"Rule has {line_count} non-empty lines; rules should be concise"))
+    elif line_count > 60 and fenced_ratio < 0.30:
+        issues.append(Issue("warning", "long_rule", f"Rule has {line_count} non-empty lines (fenced-content {fenced_ratio:.0%}); prefer < 60 (see size-and-scope guideline)"))
+    elif line_count > 40 and fenced_ratio < 0.30:
+        issues.append(Issue("warning", "long_rule", f"Rule has {line_count} non-empty lines (fenced-content {fenced_ratio:.0%}); rules should be concise"))
 
     for bad_sign in RULE_BAD_SIGNS:
         if bad_sign in text:
@@ -859,7 +1042,7 @@ def _lint_command_suggestion_block(text: str) -> List[Issue]:
     suggestion = data.get("suggestion")
     if suggestion is None:
         issues.append(Issue(
-            "warning", "missing_suggestion_block",
+            "error", "missing_suggestion_block",
             "Command frontmatter is missing the 'suggestion' block — required by "
             "road-to-context-aware-command-suggestion Phase 2.",
         ))
@@ -969,9 +1152,16 @@ def lint_command(path: Path, text: str) -> LintResult:
         issues.append(Issue("warning", "no_steps", "Command has no Steps section or numbered sub-headings"))
 
     # --- Size check (see guidelines/agent-infra/size-and-scope.md) ---
+    # Word threshold (1000) gated by structural delegation signal (council review
+    # 2026-05-06): well-factored orchestrators with ≥ 5 sub-sections AND ≥ 3 code
+    # blocks are exempt — the size reflects dispatch breadth, not bloat.
     word_count = len(text.split())
     if word_count > 1000:
-        issues.append(Issue("warning", "large_command", f"Command has {word_count} words (target: 200-600, max ~1000)"))
+        section_count = len(sections)
+        code_block_count = _count_code_blocks(text)
+        delegation_signal = section_count >= 5 and code_block_count >= 3
+        if not delegation_signal:
+            issues.append(Issue("warning", "large_command", f"Command has {word_count} words (target: 200-600, max ~1000); {section_count} sub-sections, {code_block_count} code blocks — lacks delegation structure"))
 
     # File must end with exactly one newline
     if not text.endswith("\n"):

package/scripts/smoke_path_resolution.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Smoke-test path resolution against the package's own `.augment/` projection.
+
+Per `agents/roadmaps/road-to-path-fixes.md` Phase 7 (Council Decision 3,
+2026-05-06): the package's `.augment/` tree has the same shape as the
+`.augment/` tree a consumer would receive after `scripts/install.sh`.
+If `load_context:` entries resolve cleanly here, they resolve cleanly
+in any consumer.
+
+What it does:
+  - Walks `.augment/rules/*.md`.
+  - Parses each rule's YAML frontmatter.
+  - Resolves every `load_context:` and `load_context_eager:` entry
+    against the rule file's directory.
+  - Reports any miss with a file:entry line.
+
+Exit codes: 0 = all entries resolve, 1 = one or more misses, 3 = no
+`.augment/rules/` directory found (run `task sync` first).
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+AUGMENT_RULES = ROOT / ".augment" / "rules"
+
+
+def _split_frontmatter(text: str):
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    try:
+        fm = yaml.safe_load(text[4:end])
+    except yaml.YAMLError:
+        return None
+    return fm if isinstance(fm, dict) else {}
+
+
+def _check_rule(rule_file: Path, misses: list[tuple[str, str]]) -> int:
+    fm = _split_frontmatter(rule_file.read_text(encoding="utf-8"))
+    if not fm:
+        return 0
+    checked = 0
+    rule_dir = rule_file.parent
+    for key in ("load_context", "load_context_eager"):
+        entries = fm.get(key) or []
+        if not isinstance(entries, list):
+            continue
+        for entry in entries:
+            if not isinstance(entry, str):
+                continue
+            checked += 1
+            target = (rule_dir / entry).resolve()
+            if not target.is_file():
+                misses.append((str(rule_file.relative_to(ROOT)), entry))
+    return checked
+
+
+def main() -> int:
+    if not AUGMENT_RULES.is_dir():
+        print(
+            f"❌  {AUGMENT_RULES.relative_to(ROOT)} not found — run `task sync` first",
+            file=sys.stderr,
+        )
+        return 3
+
+    misses: list[tuple[str, str]] = []
+    rule_count = 0
+    entry_count = 0
+    for rule_file in sorted(AUGMENT_RULES.glob("*.md")):
+        rule_count += 1
+        entry_count += _check_rule(rule_file, misses)
+
+    if misses:
+        print(f"❌  {len(misses)} unresolved load_context entr(y/ies):")
+        for rule, entry in misses:
+            print(f"    {rule} → {entry!r}")
+        return 1
+
+    print(
+        f"✅  smoke-path-resolution clean "
+        f"({rule_count} rules, {entry_count} load_context entr(y/ies) resolved)"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate_frontmatter.py

@@ -157,15 +157,55 @@ def _parse_yaml_block(body: str) -> dict[str, Any]:
 def _consume_block_list(lines: list[str], start: int) -> tuple[list[Any], int]:
     items: list[Any] = []
     i = start
+    item_indent: int | None = None
     while i < len(lines):
         line = lines[i]
         if not line.strip():
             i += 1
             continue
         stripped = line.lstrip()
+        leading = len(line) - len(stripped)
         if not stripped.startswith("- "):
+            # Out of the list — caller resumes.
             break
-        items.append(_coerce(stripped[2:]))
+        if item_indent is None:
+            item_indent = leading
+        elif leading != item_indent:
+            break
+        item_body = stripped[2:].strip()
+        # Inline mapping inside the list: `- key: value`
+        m = re.match(r"^([\w-]+):\s*(.*)$", item_body)
+        if m:
+            mapping: dict[str, Any] = {}
+            key = m.group(1)
+            raw = m.group(2).strip()
+            mapping[key] = _coerce(raw) if raw != "" else ""
+            # Consume continuation lines that are indented past the dash —
+            # they belong to the same mapping item (`pattern: …`, `reason: …`).
+            cont_indent = item_indent + 2  # `- ` is two chars
+            i += 1
+            while i < len(lines):
+                cont = lines[i]
+                if not cont.strip():
+                    i += 1
+                    continue
+                cont_stripped = cont.lstrip()
+                cont_leading = len(cont) - len(cont_stripped)
+                if cont_stripped.startswith("- "):
+                    break
+                if cont_leading <= item_indent:
+                    break
+                cm = re.match(r"^([\w-]+):\s*(.*)$", cont_stripped)
+                if cm and cont_leading >= cont_indent:
+                    ckey = cm.group(1)
+                    cval = cm.group(2).strip()
+                    mapping[ckey] = _coerce(cval) if cval != "" else ""
+                    i += 1
+                else:
+                    break
+            items.append(mapping)
+            continue
+        items.append(_coerce(item_body))
         i += 1
     return items, i - start
 

package/.agent-src/commands/roadmap/execute.md

@@ -1,109 +0,0 @@
----
-name: roadmap:execute
-cluster: roadmap
-sub: execute
-skills: [agent-docs-writing]
-description: Read and interactively execute a roadmap from agents/roadmaps/
-disable-model-invocation: true
-suggestion:
-  eligible: true
-  trigger_description: "execute the roadmap, work through the roadmap step by step"
-  trigger_context: "existing agents/roadmaps/*.md referenced in the prompt"
----
-
-# /roadmap execute
-## Instructions
-
-### 1. Find the roadmap
-
-- List all roadmap files: `agents/roadmaps/*.md` (project root) and `app/Modules/*/agents/roadmaps/*.md` (modules).
-- Exclude `template.md`.
-- If only one roadmap exists → use it (confirm with user).
-- If multiple exist → present a numbered list and let the user choose.
-- If none exist → tell the user and suggest running `roadmap-create`.
-
-### 2. Read and understand the roadmap
-
-- Read the full roadmap file.
-- Identify the **phases** and **steps/tasks** within each phase.
-- Determine which steps are already completed (look for checkboxes `[x]`, status markers, or "done" notes).
-- Present a summary to the user:
-  > "Roadmap: {title}"
-  > "Phase 1: {name} — 3/5 Schritte erledigt"
-  > "Phase 2: {name} — noch nicht begonnen"
-  > "Next open step: {step description}"
-
-### 3. Resolve quality cadence (read once, before any step runs)
-
-Read `roadmap.quality_cadence` from `.agent-settings.yml`:
-
-| Value | When the project's quality pipeline runs |
-|---|---|
-| `end_of_roadmap` (default) | Once, in step 7 — before archiving |
-| `per_phase` | Once after every completed phase, plus step 7 |
-| `per_step` | After every completed step, plus step 7 (legacy verbose) |
-
-Missing key, unreadable file, or unknown value → fall back to `end_of_roadmap`.
-Cite the resolved cadence once in step 2's summary so the user can override it.
-
-The Iron Law `verify-before-complete` still applies — fresh quality
-output is mandatory before any "roadmap complete" claim, regardless of
-cadence. Step checkboxes and `agents/roadmaps-progress.md` are ALWAYS
-updated in the same response per `roadmap-progress-sync`; cadence only
-gates the *quality pipeline*, not progress tracking.
-
-### 4. Execute step by step
-
-For each open step:
-
-1. **Summarize** what needs to be done (in the user's language).
-2. **Analyze** the codebase to understand what's needed for this step.
-3. **Present a plan** — what files to change, what approach to take.
-4. **Ask for confirmation**: "Should I implement this step?"
-   - If yes → implement, mark the step `[x]` in the roadmap file.
-   - If no / skip → move to the next step.
-   - If the user wants to stop → stop and summarize progress.
-
-### 5. After each step
-
-- Update the roadmap file: mark the completed step `[x]` (or `[~]` / `[-]`).
-- Regenerate `agents/roadmaps-progress.md` — `./agent-config roadmap:progress`.
-- **Quality pipeline** — run only when `quality_cadence: per_step`.
-  Otherwise skip and proceed.
-- Ask: "Continue with the next step?"
-
-### 6. After all steps in a phase
-
-- Summarize what was accomplished in the phase.
-- **Quality pipeline** — run when `quality_cadence: per_phase` (or `per_step`).
-  Skip when `end_of_roadmap`.
-- Ask: "Phase {N} complete. Continue with Phase {N+1}?"
-
-### 7. When done (or stopped)
-
-- Summarize total progress: steps completed, steps remaining.
-- Update the roadmap file with the current status.
-- Regenerate the dashboard one last time so it matches the final state.
-- **If ALL steps are done** → run the project's quality pipeline now
-  (this is the `verify-before-complete` evidence gate; required for
-  every cadence value, including `end_of_roadmap`). On green, trigger
-  the completion & archiving workflow from the `roadmap-management`
-  skill. On red, stop, surface the failures, do not archive.
-
-### Rules
-
-- **Commits are governed by [`commit-policy`](../rules/commit-policy.md).**
-  By default: only apply local changes and update the roadmap file — no commits.
-  - If the roadmap **does not** contain explicit commit steps → never commit, never ask.
-  - If the roadmap **does** contain explicit commit steps:
-    - **Non-autonomous** (`personal.autonomy: off`, or `auto` before opt-in) →
-      ask before each commit step.
-    - **Autonomous** (`personal.autonomy: on`, or `auto` after opt-in) →
-      pre-scan the roadmap **before starting**, ask **once** upfront whether
-      to execute the listed commit steps, then proceed silently per the answer.
-- **Push, merge, branch, PR, tag** stay permission-gated by [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
-- **Always ask before implementing** a step — never auto-execute.
-- **Quality cadence** is set by `roadmap.quality_cadence` (see step 3).
-  Step 7 always runs the pipeline before archival regardless of cadence.
-- If a step is unclear or too large, suggest breaking it down further.
-- If a step reveals a problem not covered in the roadmap, flag it to the user.

package/.agent-src/contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md

@@ -1,72 +0,0 @@
-# Artifact Engagement Recording — mechanics
-
-CLI invocation, privacy contract, failure-mode handling, and "what
-this rule does NOT do" catalog for the
-[`artifact-engagement-recording`](../../../rules/artifact-engagement-recording.md)
-rule. The activation gate, cadence table, and consulted-vs-applied
-definitions live in the rule; this file is the lookup material for
-the actual `telemetry:record` call and the privacy floor.
-
-## What to record — id-only, no payload
-
-```bash
-./agent-config telemetry:record \
-  --task-id "$TASK_ID" \
-  --boundary task \
-  --consulted skills:php-coder \
-  --consulted skills:eloquent \
-  --consulted rules:scope-control \
-  --applied skills:php-coder \
-  --applied rules:scope-control
-```
-
-- `--task-id` — the ticket key (`PROJ-123`) for `/implement-ticket`, or a
-  short opaque slug derived from the prompt for `/work`. **Never** a
-  branch name, a file path, or a free-text title.
-- `--boundary` — `task` or `phase-step`, matching the cadence in the rule.
-- `--consulted <kind>:<id>` — repeat per artefact. `<kind>` is one of
-  `skills`, `rules`, `commands`, `guidelines`, `personas`.
-- `--applied <kind>:<id>` — repeat per artefact actually applied.
-- Exit `0` always when disabled (silent). Exit `1` on schema validation
-  failure (rule must NOT swallow this — surface to the user). Exit `2`
-  on IO failure.
-
-## Privacy contract — what NEVER goes into a record
-
-The CLI rejects most violations on the input boundary, but the agent must
-not even attempt these:
-
-- ❌  File paths (`src/Foo.php`, `tests/...`) — id fields are
-  artefact identifiers only.
-- ❌  Source code, prompt text, ticket body, AC text.
-- ❌  Branch names, commit shas, PR numbers, URLs.
-- ❌  Secrets, env vars, credentials, customer data.
-- ❌  Free-text strings longer than 200 chars (CLI enforces; agent must
-  not generate).
-
-When in doubt → **don't record**. A missing event is cheap; a leaked
-prompt is not.
-
-## Failure modes — DO NOT block the user's task
-
-- Schema rejection (CLI exit `1`) → log the message internally, continue
-  the user's task. Do **not** halt the dispatch loop.
-- IO failure (CLI exit `2`) → same. The telemetry is **observation**, not
-  a delivery requirement.
-- Settings malformed → already handled by the CLI: it falls back to
-  disabled and exits `0`. Agent treats it as "disabled this task".
-
-The only error the agent surfaces is when the user explicitly asked for
-recording (`telemetry:status` confirms enabled) but no event reached the
-log — that is a real bug, not a swallowed error.
-
-## What this rule does NOT do
-
-- Run when `enabled: false` (cost floor is zero — see
-  [`tests/telemetry/test_cost_floor.py`](../../../../tests/telemetry/test_cost_floor.py)).
-- Track the agent's tool calls, file reads, or token spend — that is
-  out of scope, see the roadmap's "out-of-scope" section.
-- Decide retirement. Phase 4's aggregator + report renderer are the only
-  consumers that may interpret the JSONL.
-- Run on cloud surfaces (Claude.ai Web, Skills API). The
-  `cloud_safe: noop` marker keeps it inert there.

package/.agent-src/contexts/communication/rules-auto/augment-portability-mechanics.md

@@ -1,79 +0,0 @@
-# Augment portability — mechanics
-
-`task`-to-script translation table, the `./agent-config` consumer-CLI
-table, and the rationale behind both for the
-[`augment-portability`](../../../rules/augment-portability.md) rule.
-The portability obligation, the agnostic-content rules, and the
-enforcement script reference live in the rule; this file is the
-lookup material when an agent is about to write or edit an artefact
-that mentions a runtime invocation.
-
-## Why no `task` commands inside artefacts
-
-Skills, rules, commands, guidelines, personas, and context docs
-shipped by this package run in **consumer projects**. Consumer
-projects may not have [Task](https://taskfile.dev) installed —
-they might use npm scripts, Composer scripts, Make, or nothing at
-all. A skill that instructs an agent to run `task <something>`
-silently breaks in every project without a `Taskfile.yml`.
-
-Task remains a convenience shortcut for maintainers working on the
-package repo itself — `task ci` is the recommended local gate before
-a PR and lives in `Taskfile.yml`, `AGENTS.md`, and the package README.
-Those maintainer-facing surfaces are outside the scope of this rule.
-Artefact files must assume Task is absent.
-
-The detection pattern *"if the consumer has a `Makefile` / build
-script, prefer its targets over raw commands"* is still allowed when
-the skill adapts to the **consumer's own** tooling (e.g.
-`tests-execute` detecting `php artisan test` vs `vendor/bin/pest`).
-It is not allowed to reference `task <name>` as the detected target —
-every direct invocation must resolve to a real script path.
-
-## Translation table — `task` → script
-
-| ❌ Forbidden | ✅ Portable |
-|---|---|
-| `task sync` | `bash scripts/compress.sh --sync` |
-| `task sync-check` | `bash scripts/compress.sh --check` |
-| `task sync-check-hashes` | `bash scripts/compress.sh --check-hashes` |
-| `task sync-changed` | `bash scripts/compress.sh --changed` |
-| `task sync-mark-done -- X` | `bash scripts/compress.sh --mark-done X` |
-| `task generate-tools` | `python3 scripts/compress.py --generate-tools` |
-| `task lint-skills` | `python3 scripts/skill_linter.py --all` |
-| `task check-refs` | `python3 scripts/check_references.py` |
-| `task check-portability` | `python3 scripts/check_portability.py` |
-| `task check-compression` | `python3 scripts/check_compression.py` |
-| `task validate-schema` | `python3 scripts/validate_frontmatter.py` |
-| `task counts-check` | `python3 scripts/update_counts.py --check` |
-| `task roadmap-progress` | `./agent-config roadmap:progress` |
-| `task ci` | run each underlying script directly (no single portable equivalent) |
-
-## Consumer CLI — `./agent-config`
-
-A subset of package scripts is exposed through a project-local CLI
-wrapper `./agent-config` (written into the project root by the
-installer, gitignored). Artefacts MUST prefer the CLI over raw
-`python3 scripts/…` paths for every command the CLI already covers,
-because the raw paths only resolve inside the package repo — in a
-consumer project the scripts live under `node_modules/` or `vendor/`.
-
-| ❌ Forbidden in artefacts | ✅ Portable |
-|---|---|
-| `python3 scripts/mcp_render.py` | `./agent-config mcp:render` |
-| `python3 scripts/mcp_render.py --check` | `./agent-config mcp:check` |
-| `python3 .augment/scripts/update_roadmap_progress.py` | `./agent-config roadmap:progress` |
-| `python3 .augment/scripts/update_roadmap_progress.py --check` | `./agent-config roadmap:progress-check` |
-| `bash scripts/first-run.sh` | `./agent-config first-run` |
-| `PYTHONPATH=… python3 -m implement_ticket` | `./agent-config implement-ticket` |
-| `python3 scripts/memory_lookup.py` | `./agent-config memory:lookup` |
-| `python3 scripts/memory_signal.py` | `./agent-config memory:signal` |
-| `python3 scripts/memory_hash.py` | `./agent-config memory:hash` |
-| `python3 scripts/check_memory.py` | `./agent-config memory:check` |
-| `python3 scripts/check_memory_proposal.py` | `./agent-config memory:check-proposal` |
-| `python3 scripts/check_proposal.py` | `./agent-config proposal:check` |
-| `python3 scripts/refine_ticket_detect.py` | `./agent-config refine-ticket:detect` |
-
-Commands not covered by the CLI stay as direct script invocations
-(e.g. `bash scripts/compress.sh --sync`) — those are maintainer-only
-and not reachable from a consumer project anyway.