@event4u/agent-config 1.22.0 → 1.24.0

package/scripts/measure_frugality_savings.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Phase 0 baseline harness for road-to-trim-frugality-canon.
+
+Measures the *current state* of the frugality canon along four
+deterministic axes. Output: JSONL baseline appended to
+agents/.frugality-baseline.jsonl (gitignored).
+
+Metrics:
+  A. footprint    — per-rule char/token count, kernel/tier breakdown
+  B. fillers      — filler-phrase prevalence in chat-history corpus
+                    (heuristic signal, not full transcript)
+  C. compression  — uncompressed → compressed char delta per rule
+  D. redundancy   — cross-ref overlap across "Interactions:" /
+                    "See also" sections in the canon
+
+Trim phases re-run this harness after each PR. Decline condition fires
+if metric B regresses (filler prevalence increases) or metric C drops
+below current baseline by >10% per rule.
+"""
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+CANON_RULES = [
+    ("direct-answers", "kernel"),
+    ("no-cheap-questions", "kernel"),
+    ("ask-when-uncertain", "kernel"),
+    ("user-interaction", "tier_1"),
+    ("caveman-speak", "tier_1"),
+    ("token-efficiency", "tier_2"),
+]
+CHARTER = "frugality-charter"
+
+FILLER_PATTERNS = [
+    r"\bgreat question\b", r"\bfascinating\b", r"\bexcellent point\b",
+    r"\blet me\s+(check|look|find|verify|investigate|see)\b",
+    r"\bnow\s+(i'll|i will|let's)\b",
+    r"\bgoing to\s+(check|run|use|call|invoke)\b",
+    r"\bperfect\b!?", r"\bawesome\b!?",
+    r"\bhere's what i\b", r"\bfound it\b",
+    r"^\s*(ok|okay|alright)[!,.]\s",
+]
+FILLER_RE = re.compile("|".join(FILLER_PATTERNS), re.IGNORECASE | re.MULTILINE)
+
+# Cross-ref section headers to count for redundancy metric
+XREF_HEADERS = re.compile(r"^##\s+(Interactions|See also|Related)\s*$", re.MULTILINE)
+
+
+def _read(path: Path) -> str:
+    return path.read_text() if path.exists() else ""
+
+
+def metric_a_footprint(root: Path) -> dict:
+    """Per-rule char count, tier classification, total kernel %."""
+    rows = []
+    kernel_total = 0
+    tier1_total = 0
+    tier2_total = 0
+    for name, tier in CANON_RULES:
+        compressed = root / ".agent-src" / "rules" / f"{name}.md"
+        chars = len(_read(compressed))
+        tokens = chars // 4  # rough 4-char/token approximation
+        rows.append({"rule": name, "tier": tier, "chars": chars, "tokens_approx": tokens})
+        if tier == "kernel":
+            kernel_total += chars
+        elif tier == "tier_1":
+            tier1_total += chars
+        elif tier == "tier_2":
+            tier2_total += chars
+    charter_chars = len(_read(root / ".agent-src" / "contexts" / "contracts" / f"{CHARTER}.md"))
+    return {
+        "rules": rows,
+        "kernel_total_chars": kernel_total,
+        "tier_1_total_chars": tier1_total,
+        "tier_2_total_chars": tier2_total,
+        "charter_chars": charter_chars,
+        "kernel_budget_chars": 26000,
+        "kernel_pct": round(100 * kernel_total / 26000, 2),
+    }
+
+
+def metric_b_fillers(corpus: Path) -> dict:
+    """Filler-phrase hits per agent turn in chat-history corpus."""
+    if not corpus.exists():
+        return {"corpus_present": False}
+    lines = corpus.read_text().splitlines()
+    agent_turns = 0
+    filler_hits = 0
+    total_chars = 0
+    for ln in lines[1:]:
+        try:
+            d = json.loads(ln)
+        except json.JSONDecodeError:
+            continue
+        if d.get("t") != "agent":
+            continue
+        text = d.get("text", "")
+        agent_turns += 1
+        total_chars += len(text)
+        filler_hits += len(FILLER_RE.findall(text))
+    return {
+        "corpus_present": True,
+        "agent_turns": agent_turns,
+        "filler_hits_total": filler_hits,
+        "filler_hits_per_turn": round(filler_hits / max(agent_turns, 1), 3),
+        "agent_chars_total": total_chars,
+        "patterns_count": len(FILLER_PATTERNS),
+        "note": "chat-history texts are digests, not full transcripts; signal not output volume",
+    }
+
+
+def metric_c_compression(root: Path) -> dict:
+    """Uncompressed → compressed char delta per rule."""
+    rows = []
+    for name, _ in CANON_RULES:
+        un = len(_read(root / ".agent-src.uncompressed" / "rules" / f"{name}.md"))
+        co = len(_read(root / ".agent-src" / "rules" / f"{name}.md"))
+        delta = un - co
+        ratio = round(co / un, 3) if un else 0
+        rows.append({"rule": name, "uncompressed_chars": un, "compressed_chars": co, "delta": delta, "ratio": ratio})
+    return {"rules": rows}
+
+
+def metric_d_redundancy(root: Path) -> dict:
+    """Cross-ref section count + total xref-block size."""
+    rows = []
+    for name, _ in CANON_RULES:
+        path = root / ".agent-src.uncompressed" / "rules" / f"{name}.md"
+        text = _read(path)
+        xref_count = len(XREF_HEADERS.findall(text))
+        # naive: chars after last xref header to EOF
+        m = list(XREF_HEADERS.finditer(text))
+        xref_block_chars = (len(text) - m[-1].start()) if m else 0
+        rows.append({"rule": name, "xref_sections": xref_count, "xref_block_chars": xref_block_chars})
+    return {"rules": rows, "total_xref_chars": sum(r["xref_block_chars"] for r in rows)}
+
+
+def main() -> int:
+    root = Path(__file__).resolve().parent.parent
+    corpus = root / "agents" / ".agent-chat-history"
+
+    record = {
+        "schema_version": 1,
+        "ts": datetime.now(tz=timezone.utc).isoformat(timespec="seconds"),
+        "phase": "phase_0_baseline",
+        "metric_a_footprint": metric_a_footprint(root),
+        "metric_b_fillers": metric_b_fillers(corpus),
+        "metric_c_compression": metric_c_compression(root),
+        "metric_d_redundancy": metric_d_redundancy(root),
+    }
+
+    out = root / "agents" / ".frugality-baseline.jsonl"
+    with out.open("a") as fh:
+        fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+    print(json.dumps(record, indent=2, ensure_ascii=False))
+    print(f"\nappended → {out.relative_to(root)}", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/measure_markitdown_lift.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Measure markitdown's token-saving lift on the bundled corpus.
+
+Runs against `tests/fixtures/markitdown-corpus/`. By default (no flags) the
+script computes the baseline-only — raw byte size and a tokens-per-4-bytes
+estimate — without calling `markitdown-mcp`. With `--convert`, the script
+tries to invoke `markitdown` (CLI binary) via subprocess and computes the
+converted-Markdown token estimate plus the ratio per file.
+
+Stdlib-only. Never installs anything. Never invokes a network host. Never
+calls `markitdown-mcp` over HTTP — only through the `markitdown` CLI on
+the user's PATH (peer-side install per the skill's Step 1 recipes).
+
+Exit codes:
+  0  — baseline produced (always, when fixtures exist)
+  2  — corpus not found
+  3  — `--convert` was requested but `markitdown` is not on PATH
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+CORPUS = REPO_ROOT / "tests" / "fixtures" / "markitdown-corpus"
+TOKEN_PER_BYTES = 4  # rough OpenAI/Anthropic tokenizer-of-thumb
+
+
+def _baseline_tokens(p: Path) -> int:
+    return max(1, p.stat().st_size // TOKEN_PER_BYTES)
+
+
+def _converted_tokens(p: Path, *, binary: str) -> int | None:
+    try:
+        out = subprocess.run(
+            [binary, str(p)],
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=30,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if out.returncode != 0:
+        return None
+    chars = len(out.stdout)
+    if chars == 0:
+        return None
+    return max(1, chars // TOKEN_PER_BYTES)
+
+
+def _format_ratio(baseline: int, converted: int | None) -> str:
+    if converted is None or converted == 0:
+        return "—"
+    ratio = baseline / converted
+    return f"{ratio:.1f}×"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Measure markitdown lift on the bundled corpus.")
+    parser.add_argument(
+        "--convert",
+        action="store_true",
+        help="Invoke `markitdown <fixture>` per file and compute the converted-token ratio.",
+    )
+    parser.add_argument(
+        "--binary",
+        default="markitdown",
+        help="Name or path of the markitdown CLI binary (default: markitdown).",
+    )
+    args = parser.parse_args()
+
+    if not CORPUS.is_dir():
+        print(f"ERROR: corpus not found at {CORPUS}", file=sys.stderr)
+        print(
+            "Generate it: python3 tests/fixtures/markitdown-corpus/_generate.py",
+            file=sys.stderr,
+        )
+        return 2
+
+    fixtures = sorted(p for p in CORPUS.iterdir() if p.is_file() and p.suffix in {".pdf", ".pptx", ".docx", ".xlsx"})
+    if not fixtures:
+        print(f"ERROR: no fixtures in {CORPUS}", file=sys.stderr)
+        return 2
+
+    binary_path: str | None = None
+    if args.convert:
+        binary_path = shutil.which(args.binary)
+        if binary_path is None:
+            print(
+                f"ERROR: --convert requested but `{args.binary}` not on PATH.\n"
+                "Install peer-side per the skill's Step 1 recipes "
+                "(Docker / pipx / uv) and re-run.",
+                file=sys.stderr,
+            )
+            return 3
+
+    print(f"Corpus: {CORPUS.relative_to(REPO_ROOT)}  ({len(fixtures)} files)")
+    print(f"Mode:   {'convert (peer markitdown CLI)' if binary_path else 'baseline-only'}")
+    if binary_path:
+        print(f"Binary: {binary_path}")
+    print()
+    header = f"{'fixture':<32} {'bytes':>7} {'baseline tok':>13} {'converted tok':>14} {'ratio':>7}"
+    print(header)
+    print("-" * len(header))
+    for p in fixtures:
+        size = p.stat().st_size
+        base = _baseline_tokens(p)
+        converted = _converted_tokens(p, binary=binary_path) if binary_path else None
+        ratio = _format_ratio(base, converted)
+        conv_str = f"{converted}" if converted is not None else "—"
+        print(f"{p.name:<32} {size:>7} {base:>13} {conv_str:>14} {ratio:>7}")
+    print()
+    if not binary_path:
+        print(
+            "Re-run with --convert (after installing markitdown-mcp peer-side per the skill's "
+            "Step 1 recipes) for the actual ratio."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/runtime_dispatcher.py

@@ -30,6 +30,7 @@ from typing import List, Optional
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from runtime_registry import SkillRuntime, build_registry
 from runtime_handler import ExecutionResult, HandlerError, execute_shell
+from _lib.script_output import resolve_level  # type: ignore[import-not-found]
 
 
 @dataclass
@@ -187,6 +188,16 @@ def _print_execution(result: ExecutionResult, fmt: str) -> None:
     if fmt == "json":
         print(json.dumps(asdict(result), indent=2))
         return
+    level = resolve_level()
+    if level == "silent" and result.is_success:
+        return
+    if level == "minimal" and result.is_success:
+        marker = "✅" if result.is_success else "❌"
+        print(
+            f"{marker}  {result.skill_name} · {result.handler} · "
+            f"exit={result.exit_code} ({result.duration_ms}ms)"
+        )
+        return
     print(f"Skill: {result.skill_name}")
     print(f"Handler: {result.handler}")
     print(f"Command: {' '.join(result.command)}")

package/scripts/skill_linter.py

@@ -76,6 +76,26 @@ RULE_BAD_SIGNS = [
     "## Gotchas",
 ]
 
+# --- Frugality charter validator (see road-to-token-frugality Phase 0.4) ---
+# Layer 1 = writer-cite check (every writer skill carries the section + link).
+# Layer 2 = charter index integrity (the four canonical rules referenced by
+# the charter resolve to real H2/H3 anchors in the rule files).
+
+FRUGALITY_WRITER_SKILLS = {
+    "skill-writing", "rule-writing", "command-writing",
+    "guideline-writing", "context-authoring", "agent-docs-writing",
+    "conventional-commits-writing", "readme-writing",
+    "readme-writing-package", "adr-create",
+    "persona-writing", "roadmap-writing", "script-writing",
+}
+FRUGALITY_CHARTER_RELPATH = "contexts/communication/frugality-charter.md"
+FRUGALITY_CHARTER_INDEX_RULES = {
+    "direct-answers.md": "iron-law-3",
+    "user-interaction.md": "iron-law-1",
+    "no-cheap-questions.md": "pre-send-self-check",
+    "token-efficiency.md": "the-iron-laws",
+}
+
 VAGUE_VALIDATION_PATTERNS = [
     r"\bcheck if it works\b",
     r"\bverify it works\b",
@@ -1381,6 +1401,15 @@ def gather_all_candidate_files(root: Path) -> list[Path]:
             if not f.is_symlink():
                 candidates.append(f)
 
+    # Frugality charter (Phase 0.4 Layer 2). Lives in contexts/, not
+    # walked by the artifact-type loops above, but still needs the
+    # index-integrity check.
+    for base in (root / ".agent-src.uncompressed", root / ".agent-src"):
+        charter = base / FRUGALITY_CHARTER_RELPATH
+        if charter.exists() and not charter.is_symlink():
+            candidates.append(charter)
+            break
+
     return sorted(set(candidates))
 
 
@@ -1860,6 +1889,156 @@ def lint_verification_maturity(path: Path, text: str, artifact_type: str) -> Lis
 # --- Governance & packaging checks ---
 
 
+# --- Frugality validator helpers + Layers 1 & 2 ---
+
+def _heading_to_slug(heading: str) -> str:
+    """Slugify a markdown heading using GitHub's algorithm: lowercase,
+    drop punctuation (em-dash, period, etc.), spaces -> hyphens,
+    preserve adjacent hyphens (so `Iron Law 3 — Brevity` becomes
+    `iron-law-3--brevity`, matching the anchor GitHub renders)."""
+    s = heading.strip().lower()
+    s = re.sub(r"[^a-z0-9 \-]", "", s)
+    s = s.replace(" ", "-")
+    return s.strip("-")
+
+
+def _extract_heading_slugs(text: str) -> set[str]:
+    """Return the set of slugs for every H2/H3 heading in a markdown body."""
+    slugs: set[str] = set()
+    for line in text.splitlines():
+        if line.startswith("## ") or line.startswith("### "):
+            heading = line.split(" ", 1)[1].strip()
+            slugs.add(_heading_to_slug(heading))
+    return slugs
+
+
+def _skill_id_from_path(path: Path) -> Optional[str]:
+    """Extract the writer-skill id from a SKILL.md path. Returns the
+    parent-directory name, or None if the file is not a SKILL.md."""
+    if path.name.lower() != "skill.md":
+        return None
+    return path.parent.name
+
+
+def _is_frugality_charter(path: Path) -> bool:
+    """True iff the path ends in the canonical charter relpath, regardless
+    of whether it lives under .agent-src/ or .agent-src.uncompressed/."""
+    norm = str(path).replace("\\", "/")
+    return norm.endswith("/" + FRUGALITY_CHARTER_RELPATH)
+
+
+# Section header recognised by Layer 1. Literal H2 only — sub-headings
+# inside the section do not count as the section itself.
+_FRUGALITY_STANDARDS_PATTERN = re.compile(
+    r"^##\s+Frugality Standards\s*$", re.MULTILINE
+)
+_FRUGALITY_CHARTER_LINK_PATTERN = re.compile(
+    r"\]\([^)]*frugality-charter\.md[^)]*\)"
+)
+
+
+def lint_frugality_writer_cite(path: Path, text: str,
+                                artifact_type: str) -> List[Issue]:
+    """Layer 1 — every writer skill must carry a `## Frugality Standards`
+    section that links to the charter. No-op for non-writer skills and
+    non-skill artifacts."""
+    if artifact_type != "skill":
+        return []
+    skill_id = _skill_id_from_path(path)
+    if skill_id is None or skill_id not in FRUGALITY_WRITER_SKILLS:
+        return []
+    issues: List[Issue] = []
+    section_match = _FRUGALITY_STANDARDS_PATTERN.search(text)
+    if not section_match:
+        issues.append(Issue(
+            "error", "frugality_section_missing",
+            "Writer skill must carry a `## Frugality Standards` section "
+            "(road-to-token-frugality Phase 0.4 Layer 1)",
+        ))
+        return issues
+    # Section body = from match-end to next H2 or EOF.
+    body_start = section_match.end()
+    next_h2 = re.search(r"^##\s+", text[body_start:], re.MULTILINE)
+    body_end = body_start + next_h2.start() if next_h2 else len(text)
+    body = text[body_start:body_end]
+    if not _FRUGALITY_CHARTER_LINK_PATTERN.search(body):
+        issues.append(Issue(
+            "error", "frugality_charter_cite_missing",
+            "`## Frugality Standards` section must link to "
+            "`frugality-charter.md` (road-to-token-frugality Phase 0.4 "
+            "Layer 1)",
+        ))
+    return issues
+
+
+# Markdown link pattern: [text](path#anchor) — anchor optional.
+_MD_LINK_PATTERN = re.compile(
+    r"\[[^\]]+\]\(([^)#]+)(?:#([^)]+))?\)"
+)
+
+
+def lint_frugality_charter_index(path: Path, text: str) -> List[Issue]:
+    """Layer 2 — every cited anchor must resolve to a real H2/H3 heading
+    in the target rule file, AND each of the four canonical rules must
+    be cited at least once with the required canonical anchor substring.
+    Additional citations to the same rule (net-new sections referencing
+    other anchors) are validated for resolution but do not need the
+    canonical substring."""
+    if not _is_frugality_charter(path):
+        return []
+    issues: List[Issue] = []
+    rules_dir = path.parent.parent.parent / "rules"
+    rule_slugs_cache: dict[str, set[str]] = {}
+    canonical_satisfied: set[str] = set()
+    for link_match in _MD_LINK_PATTERN.finditer(text):
+        link_path, link_anchor = link_match.group(1), link_match.group(2)
+        rule_name = Path(link_path).name
+        if rule_name not in FRUGALITY_CHARTER_INDEX_RULES:
+            continue
+        if link_anchor is None:
+            continue
+        anchor_lc = link_anchor.lower()
+        required_substr = FRUGALITY_CHARTER_INDEX_RULES[rule_name]
+        if required_substr in anchor_lc:
+            canonical_satisfied.add(rule_name)
+        if rule_name not in rule_slugs_cache:
+            rule_file = rules_dir / rule_name
+            if not rule_file.exists():
+                issues.append(Issue(
+                    "error", "frugality_charter_rule_missing",
+                    f"Charter cites {rule_name} but the rule file does "
+                    f"not exist at {rule_file}",
+                ))
+                rule_slugs_cache[rule_name] = set()
+                continue
+            try:
+                rule_text = rule_file.read_text(encoding="utf-8")
+            except OSError as e:
+                issues.append(Issue(
+                    "error", "frugality_charter_rule_unreadable",
+                    f"Cannot read {rule_name}: {e}",
+                ))
+                rule_slugs_cache[rule_name] = set()
+                continue
+            rule_slugs_cache[rule_name] = _extract_heading_slugs(rule_text)
+        if anchor_lc not in rule_slugs_cache[rule_name]:
+            issues.append(Issue(
+                "error", "frugality_charter_anchor_unresolved",
+                f"Charter cites {rule_name}#{link_anchor} but no H2/H3 "
+                f"heading with that slug exists in the rule file",
+            ))
+    missing = set(FRUGALITY_CHARTER_INDEX_RULES) - canonical_satisfied
+    for rule_name in sorted(missing):
+        required_substr = FRUGALITY_CHARTER_INDEX_RULES[rule_name]
+        issues.append(Issue(
+            "error", "frugality_charter_canonical_missing",
+            f"Charter index lacks a canonical citation of {rule_name} "
+            f"with anchor containing '{required_substr}' "
+            f"(road-to-token-frugality Phase 0.4 Layer 2)",
+        ))
+    return issues
+
+
 def lint_governance(path: Path, text: str, artifact_type: str, repo_root: Path | None = None) -> List[Issue]:
     """Check governance and packaging consistency.
 
@@ -2139,6 +2318,17 @@ def lint_file(path: Path, repo_root: Path | None = None) -> LintResult:
     elif artifact_type == "persona":
         result = lint_persona(display_path, text)
     else:
+        # Frugality charter lives in contexts/ (artifact_type == unknown)
+        # but still needs Layer 2 index-integrity validation.
+        if _is_frugality_charter(path):
+            charter_issues = lint_frugality_charter_index(path, text)
+            return LintResult(
+                file=str(display_path),
+                artifact_type="unknown",
+                status=classify_status(charter_issues),
+                issues=charter_issues,
+                suggestions=[],
+            )
         return lint_unknown(display_path, text)
 
     # Post-processing: frontmatter schema validation (errors). Runs first
@@ -2195,10 +2385,20 @@ def lint_file(path: Path, repo_root: Path | None = None) -> LintResult:
             result.issues.extend(malice_issues)
             result.status = classify_status(result.issues)
 
+    # Post-processing: frugality validator Layer 1 (writer-cite). Errors
+    # if a writer skill lacks the `## Frugality Standards` section or its
+    # link to the charter.
+    frugality_issues = lint_frugality_writer_cite(
+        display_path, text, artifact_type
+    )
+    if frugality_issues:
+        result.issues.extend(frugality_issues)
+        result.status = classify_status(result.issues)
+
     return result
 
 
-def format_text(results: list[LintResult]) -> str:
+def format_text(results: list[LintResult], quiet: bool = False) -> str:
     lines: list[str] = []
     # Phase 5.2: malice findings render in the spec shape
     # ``<path>:<line>:malice:<pattern>:<matched>`` ahead of the badge
@@ -2216,7 +2416,10 @@ def format_text(results: list[LintResult]) -> str:
     if malice_total:
         lines.append("")
 
+    # P10.5: quiet mode skips PASS-without-issues; malice + WARN/FAIL still rendered.
     for result in results:
+        if quiet and result.status == "pass" and not result.issues and not result.suggestions:
+            continue
         badge = {"pass": "[PASS]", "pass_with_warnings": "[WARN]", "fail": "[FAIL]"}[result.status]
         lines.append(f"{badge} {result.file} ({result.artifact_type})")
         if result.issues:
@@ -2458,6 +2661,8 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--strict-warnings", action="store_true", help="Return non-zero on warnings")
     parser.add_argument("--report", action="store_true", help="Output quality score report")
     parser.add_argument("--repo-root", default=".", help="Repository root")
+    parser.add_argument("--quiet", action="store_true",
+                        help="suppress per-file PASS lines; keep malice + WARN/FAIL + summary (P10.5)")
     return parser.parse_args()
 
 
@@ -2604,7 +2809,7 @@ def main() -> int:
         elif args.format == "json":
             print(format_json(results))
         else:
-            print(format_text(results))
+            print(format_text(results, quiet=args.quiet))
 
         return compute_exit_code(results, strict_warnings=args.strict_warnings)