@event4u/agent-config 1.20.0 → 1.21.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:
@@ -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/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.

package/.agent-src/contexts/communication/rules-auto/cli-output-handling-mechanics.md

@@ -1,87 +0,0 @@
-# CLI output handling — mechanics
-
-Codebase navigation tips, the redirect-summarize-target fallback
-pattern, the general rules around exit codes / summary lines, and the
-CLI-over-MCP catalog for the
-[`cli-output-handling`](../../../rules/cli-output-handling.md) rule.
-The Iron Law, the detection rule (`rtk_installed`), the verbose-command
-table, and the exceptions list live in the rule; this file is the
-lookup material when the agent has to fall back from `rtk`.
-
-## Codebase Navigation
-
-### Use what you already have
-
-- Edited a file → the edit tool already returned the result. Skip re-reading.
-- Ran a command → you have the output. Skip re-running to "verify".
-- File in context from recent messages → skip reloading.
-- Found a symbol → use it. Skip searching again differently.
-
-### Search before reading
-
-- **Search first** — `codebase-retrieval`, `search_query_regex`, or `grep`.
-- **Load only what you need** — use `view_range` or `search_query_regex`, not full files.
-- **Small files** (< 50 lines) — OK to read fully.
-
-### Ignored files (`.augmentignore`)
-
-- `vendor/`, `node_modules/`, lock files, and generated files are excluded from `codebase-retrieval`.
-- When you need to understand a vendor package (base class, interface, API), **read the specific file** with `view`. This bypasses the ignore.
-- Load only the file you need — never browse entire vendor directories.
-
-### Minimize tool calls
-
-- **Parallel reads** — read multiple files in one batch, not sequentially.
-- **`search_query_regex`** over full file reads.
-- **`view_range`** when you know the exact lines.
-- **One `codebase-retrieval` call** with all symbols — batch, not 5 separate calls.
-
-## Fallback Pattern: Redirect, Summarize, Target
-
-When `rtk` has no matching subcommand for the tool at hand, fall back to
-this pattern. Every command that MAY produce more than ~30 lines of output:
-
-### Step 1: Redirect to file
-```bash
-docker compose exec -T <service> <command> 2>&1 > /tmp/<tool>-output.txt
-echo "EXIT=$?"
-```
-
-### Step 2: Read ONLY the summary
-```bash
-tail -5 /tmp/<tool>-output.txt
-```
-
-### Step 3: If errors exist, read ONLY what you need to fix
-```bash
-grep "ERROR\|error\|✏️" /tmp/<tool>-output.txt | head -20
-grep "app/Services/MyService.php" /tmp/<tool>-output.txt
-```
-
-**NEVER** do:
-- `cat /tmp/<tool>-output.txt` (loads everything)
-- Read the full output of a passing command (waste)
-- Read diffs you don't plan to act on
-
-## General Rules
-
-For tool-specific commands → see the `quality-tools` skill.
-
-1. **Exit code first**: Check `$?` before reading ANY output. If 0, you're done — skip reading.
-2. **Summary line**: Most tools print a summary as the last few lines. That's all you need.
-3. **Targeted grep**: When you need details, `grep` for the specific file or error type.
-4. **Read once, act, move on**: Once you've read output and acted on it, skip re-reading.
-5. **Iterative fixing**: Fix one error at a time, re-run, check exit code.
-   Output becomes stale after each fix — always re-run before reading again.
-
-## CLI Over MCP
-
-MCP servers are **significantly more token-expensive** than CLI equivalents.
-When both options exist, prefer the CLI tool.
-
-- **Git**: `git` CLI, not Git MCP
-- **Files**: shell commands, not filesystem MCP
-- **APIs**: `curl`/`httpie`, not HTTP MCP
-- **Database**: `mysql`/`psql` CLI, not DB MCP
-
-Exception: MCPs with **unique capabilities** (Sentry, Playwright, Jira).