@event4u/agent-config 4.8.0 → 5.0.0

package/scripts/lint_bench_corpus.py

@@ -23,6 +23,7 @@ Flags:
 """
 from __future__ import annotations
 
+import json
 import re
 import sys
 from pathlib import Path
@@ -38,6 +39,8 @@ REQUIRE_FULL = "--require-full" in sys.argv
 
 REPO = Path(__file__).resolve().parents[1]
 CORPUS_DIR = REPO / "tests" / "eval"
+ROUTER_COVERAGE_DIR = REPO / "internal" / "bench" / "corpora" / "router-coverage"
+ROUTER_JSON = REPO / "dist" / "router.json"
 
 # Live skill directories live under every artefact root post-monorepo
 # Phase 4 (legacy + packages/*/.agent-src.uncondensed/skills/).
@@ -46,7 +49,7 @@ from _lib.agent_src import artefact_roots  # noqa: E402
 
 SKILLS_DIRS = [root / "skills" for root in artefact_roots() if (root / "skills").is_dir()]
 
-VALID_CATEGORIES = frozenset({"canonical", "ambiguous", "destructive", "long-context"})
+VALID_CATEGORIES = frozenset({"canonical", "ambiguous", "destructive", "long-context", "router-coverage"})
 # Non-dev corpus (pre-spec) uses legacy categories — accept them so the
 # new linter does not break that file. Migration is a follow-up.
 LEGACY_CATEGORIES = frozenset({"content", "consulting", "finance", "ops", "safety"})
@@ -66,7 +69,40 @@ def live_skills() -> set[str]:
     return slugs
 
 
-def lint_corpus(path: Path, skills: set[str]) -> list[str]:
+def live_rule_ids() -> set[str] | None:
+    """Return all rule ids known to dist/router.json (kernel + tier_1 + tier_2).
+
+    Returns ``None`` (not an empty set) when the router is missing or
+    unparseable, signalling "cannot validate rule ids — skip the
+    unknown-trigger checks" rather than "every referenced id is unknown".
+    A missing router is expected on a fresh clone before ``task sync``;
+    returning an empty set there would falsely flag every intended /
+    opaque trigger as ``unknown_intended_trigger``.
+    """
+    if not ROUTER_JSON.exists():
+        sys.stderr.write(
+            f"warning: {ROUTER_JSON.relative_to(REPO)} missing — skipping "
+            "trigger rule-id validation (run `task sync` to generate it)\n"
+        )
+        return None
+    try:
+        data = json.loads(ROUTER_JSON.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        sys.stderr.write(
+            f"warning: {ROUTER_JSON.relative_to(REPO)} unparseable — "
+            "skipping trigger rule-id validation\n"
+        )
+        return None
+    ids: set[str] = set()
+    ids.update(data.get("kernel", []) or [])
+    for tier in ("tier_1", "tier_2"):
+        ids.update(
+            r.get("id") for r in (data.get(tier, []) or []) if r.get("id")
+        )
+    return ids
+
+
+def lint_corpus(path: Path, skills: set[str], rule_ids: set[str] | None = None) -> list[str]:
     errors: list[str] = []
     try:
         data = yaml.safe_load(path.read_text(encoding="utf-8"))
@@ -121,7 +157,12 @@ def lint_corpus(path: Path, skills: set[str]) -> list[str]:
             errors.append(f"{loc}: empty_prompt")
 
         expected = p.get("expected_skills") or []
-        if not isinstance(expected, list) or not expected:
+        if not isinstance(expected, list):
+            errors.append(f"{loc}: bad_expected_shape")
+        elif not expected and cat != "router-coverage":
+            # router-coverage corpora can have empty expected_skills —
+            # the focus is rule-trigger activation, not skill selection.
+            # The intended_triggers field is the load-bearing assertion.
             errors.append(f"{loc}: empty_expected")
         else:
             for slug in expected:
@@ -133,6 +174,40 @@ def lint_corpus(path: Path, skills: set[str]) -> list[str]:
             if not isinstance(carve, list) or not carve:
                 errors.append(f"{loc}: missing_carve_out")
 
+        # router-coverage invariants (Council R3 honesty floor).
+        # A task's trigger prediction lives in two buckets:
+        #   intended_triggers      — deterministically replayable (keyword /
+        #                            phrase / command / path with supplied
+        #                            open_files or command context).
+        #   replay_opaque_triggers — fires at runtime only via an `intent`
+        #                            trigger (or a router coverage gap) the
+        #                            static replay cannot verify. Declared so
+        #                            the telemetry reports it separately, not
+        #                            as false `missed_intended` drift.
+        # router-coverage requires at least one bucket non-empty.
+        intended = p.get("intended_triggers")
+        opaque = p.get("replay_opaque_triggers")
+        intended_list = intended if isinstance(intended, list) else []
+        opaque_list = opaque if isinstance(opaque, list) else []
+
+        if intended is not None and not isinstance(intended, list):
+            errors.append(f"{loc}: bad_intended_triggers_shape")
+        if opaque is not None and not isinstance(opaque, list):
+            errors.append(f"{loc}: bad_replay_opaque_triggers_shape")
+
+        if cat == "router-coverage" and not intended_list and not opaque_list:
+            errors.append(f"{loc}: missing_intended_triggers")
+
+        # A rule belongs to exactly one bucket — both is a contradiction.
+        for rid in sorted(set(intended_list) & set(opaque_list)):
+            errors.append(f"{loc}: trigger_in_both_buckets: {rid}")
+
+        # Every referenced id (either bucket) must be a real router rule id.
+        if rule_ids is not None:
+            for rid in intended_list + opaque_list:
+                if rid not in rule_ids:
+                    errors.append(f"{loc}: unknown_intended_trigger: {rid}")
+
     if REQUIRE_FULL and not is_legacy:
         for bucket, want in FULL_COUNTS.items():
             have = bucket_counts.get(bucket, 0)
@@ -147,14 +222,21 @@ def main() -> int:
         sys.stderr.write(f"error: corpus dir missing: {CORPUS_DIR}\n")
         return 2
     corpora = sorted(CORPUS_DIR.glob("corpus-*.yaml"))
+    # Phase 2 of road-to-corpus-expansion-evidence-based-cuts adds a second
+    # corpus tree under internal/bench/corpora/router-coverage/. Linter scans
+    # both with the same invariants — router-coverage corpora additionally
+    # require `intended_triggers` per prompt.
+    if ROUTER_COVERAGE_DIR.is_dir():
+        corpora.extend(sorted(ROUTER_COVERAGE_DIR.glob("*.yaml")))
     if not corpora:
         sys.stderr.write("error: no corpora found\n")
         return 2
 
     skills = live_skills()
+    rule_ids = live_rule_ids()
     all_errors: list[str] = []
     for path in corpora:
-        errs = lint_corpus(path, skills)
+        errs = lint_corpus(path, skills, rule_ids)
         if errs:
             all_errors.extend(errs)
         elif not QUIET:

package/scripts/lint_global_paths.py

@@ -3,9 +3,10 @@
 
 Phase 5.0 / amendment A7 of road-to-global-only-install. Runs BEFORE
 any legacy snapshot write so a perms leak cannot be created by the
-migration itself: `agent-config migrate-to-global` is expected to call
-this script first, abort on any failure, and only then proceed with
-the copy → verify → move → bridge sequence.
+migration itself. Historically invoked by `agent-config migrate-to-global`;
+that command was collapsed into `agent-config migrate` (see
+`docs/contracts/migrate-command.md`). The audit now runs standalone via
+`agent-config doctor` or directly through this script.
 
 Policy source: scripts/expected_perms.json (parameterised so the policy
 can evolve without code changes).

package/scripts/lint_marketplace_install_completeness.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Lint that every command in `hooks/hooks.json` resolves to a real
+dispatcher subcommand in `scripts/_dispatch.bash`.
+
+Phase 6 of `road-to-hooks-actually-fire-in-consumers`.
+
+The linter checks **plugin-side completeness** — the package ships a
+valid `hooks.json` whose every command line points at a subcommand
+the dispatcher knows about. It does NOT check consumer-side
+scaffolding (that's the runtime `dispatch-issues.jsonl` log's job
+from Phase 1).
+
+This distinction is load-bearing — see Council R3 finding #1:
+"A valid plugin against an unscaffolded consumer is a PASS;
+the linter must not produce a false-positive on that state."
+
+Exit codes:
+  0 — every command resolves; clean.
+  1 — at least one command references an unknown subcommand.
+  2 — schema / file error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+HOOKS_JSON = REPO_ROOT / "hooks" / "hooks.json"
+DISPATCH_BASH = REPO_ROOT / "scripts" / "_dispatch.bash"
+
+
+# Map agent-config-cli subcommand → dispatcher function name. The
+# subcommand is what appears after `./agent-config <subcommand>` in
+# the hooks.json command line; the function is what's defined in
+# _dispatch.bash. The user-facing subcommand uses colons; the
+# function uses underscores (e.g. `dispatch:hook` → `cmd_dispatch_hook`).
+def subcommand_to_function(subcommand: str) -> str:
+    # Normalise: replace `:` and `-` with `_`.
+    sanitised = subcommand.replace(":", "_").replace("-", "_")
+    return f"cmd_{sanitised}"
+
+
+def load_hook_commands(hooks_path: Path) -> list[tuple[str, str]]:
+    """Return [(event_name, command_line)] for every hook entry."""
+    try:
+        data = json.loads(hooks_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise SystemExit(f"lint-marketplace-install: cannot read {hooks_path}: {exc}")
+
+    hooks = data.get("hooks") or {}
+    if not isinstance(hooks, dict):
+        raise SystemExit(f"lint-marketplace-install: {hooks_path} `hooks` is not an object")
+
+    out: list[tuple[str, str]] = []
+    for event, groups in hooks.items():
+        if not isinstance(groups, list):
+            continue
+        for group in groups:
+            if not isinstance(group, dict):
+                continue
+            for entry in group.get("hooks", []) or []:
+                if not isinstance(entry, dict):
+                    continue
+                cmd = entry.get("command")
+                if isinstance(cmd, str) and cmd.strip():
+                    out.append((str(event), cmd))
+    return out
+
+
+# Pattern: `"$CLAUDE_PROJECT_DIR"/agent-config <subcommand> [args...]`.
+# Accepts both quoted and bare CLAUDE_PROJECT_DIR.
+_CMD_RE = re.compile(
+    r'(?:"?\$\{?CLAUDE_PROJECT_DIR\}?"?/)?agent-config\s+([a-zA-Z0-9:_-]+)'
+)
+
+
+def extract_subcommand(command_line: str) -> str | None:
+    """Pull the agent-config subcommand out of a hooks.json command line."""
+    m = _CMD_RE.search(command_line)
+    if m:
+        return m.group(1)
+    return None
+
+
+def load_dispatcher_subcommands(dispatch_path: Path) -> set[str]:
+    """Return the set of subcommand identifiers the dispatcher knows.
+
+    Reads `cmd_<name>` function definitions from _dispatch.bash and
+    converts back to subcommand form (underscores → colons / hyphens
+    is ambiguous, so we keep BOTH forms in the set — `dispatch_hook`
+    AND `dispatch:hook` — so the linter accepts either).
+    """
+    try:
+        text = dispatch_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SystemExit(f"lint-marketplace-install: cannot read {dispatch_path}: {exc}")
+
+    out: set[str] = set()
+    for match in re.finditer(r"^cmd_([a-zA-Z0-9_]+)\(\)", text, flags=re.MULTILINE):
+        ident = match.group(1)
+        # Add the underscore form.
+        out.add(ident)
+        # Also add a colon-substituted variant — agent-config supports
+        # `:` in user-facing subcommand names; the function strips them
+        # to underscores. We accept either spelling on the hook side.
+        # First _ → `:`, the rest stay (heuristic; covers `dispatch:hook`,
+        # `mcp:render`, `hooks:install` etc.).
+        if "_" in ident:
+            head, _, tail = ident.partition("_")
+            out.add(f"{head}:{tail}")
+    return out
+
+
+def lint(hooks_path: Path = HOOKS_JSON, dispatch_path: Path = DISPATCH_BASH) -> int:
+    if not hooks_path.is_file():
+        sys.stderr.write(f"lint-marketplace-install: {hooks_path} not found\n")
+        return 2
+    if not dispatch_path.is_file():
+        sys.stderr.write(f"lint-marketplace-install: {dispatch_path} not found\n")
+        return 2
+
+    commands = load_hook_commands(hooks_path)
+    known = load_dispatcher_subcommands(dispatch_path)
+
+    issues: list[str] = []
+    checked = 0
+    for event, cmd in commands:
+        sub = extract_subcommand(cmd)
+        if sub is None:
+            issues.append(
+                f"  {event}: command does not reference `agent-config <subcommand>`: "
+                f"{cmd!r}"
+            )
+            continue
+        checked += 1
+        if sub not in known:
+            issues.append(
+                f"  {event}: unknown_dispatcher_subcommand: {sub!r} "
+                f"(not in scripts/_dispatch.bash)"
+            )
+
+    if issues:
+        try:
+            relative = hooks_path.resolve().relative_to(REPO_ROOT)
+        except ValueError:
+            relative = hooks_path
+        sys.stderr.write(
+            f"lint-marketplace-install: {len(issues)} issue(s) in {relative}:\n"
+        )
+        for line in issues:
+            sys.stderr.write(line + "\n")
+        return 1
+
+    print(
+        f"✅  lint-marketplace-install: {checked} hook command(s) checked, "
+        f"all resolve to known dispatcher subcommands."
+    )
+    return 0
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument(
+        "--hooks-json",
+        type=Path,
+        default=HOOKS_JSON,
+        help="Path to hooks/hooks.json (default: %(default)s)",
+    )
+    p.add_argument(
+        "--dispatch-bash",
+        type=Path,
+        default=DISPATCH_BASH,
+        help="Path to scripts/_dispatch.bash (default: %(default)s)",
+    )
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv if argv is not None else sys.argv[1:])
+    return lint(args.hooks_json, args.dispatch_bash)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_value_dashboard.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Lint `docs/value.md` for structural invariants.
+
+Phase 5 Step 3 of `agents/roadmaps/road-to-readable-value-dashboard.md`.
+
+Invariants enforced (any violation → exit 1):
+
+1. Required sections present (intro / Reference scale / Panel A / Panel B
+   / Glossar / NETTO line).
+2. Every cost-ladder rung row cites a `source_report` (or `n/a` for the
+   baseline rung) — no rung sneaks in without traceability.
+3. No `measured` rung renders a `pending` source — internal consistency
+   of confidence ↔ source state.
+4. No negative-saving label: the literal string "Ersparnis" must not
+   appear in a row where the displayed Δ-token value is positive (the
+   load + terse rungs are *costs*, not savings; mislabelling either is
+   a credibility failure the page explicitly forbids).
+5. The `latest.json` exists and its `cost_ladder` rung ids match the
+   five canonical rungs — the renderer cannot silently drop a rung.
+
+The linter loads `internal/bench/reports/value/latest.json` directly
+(not just the rendered `.md`) for items (3) and (5) — the rendered
+text alone is too lossy.
+
+Output: one violation per line in non-quiet mode; one-line summary in
+quiet mode. Exit 0 on clean, 1 on any violation.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DASHBOARD = REPO_ROOT / "docs" / "value.md"
+LATEST = REPO_ROOT / "internal" / "bench" / "reports" / "value" / "latest.json"
+
+REQUIRED_SECTIONS = (
+    "# Value Dashboard",
+    "## Reference scale",
+    "## Panel A",
+    "## Panel B",
+    "## Glossar",
+    "**NETTO",
+)
+
+CANONICAL_RUNG_IDS = ("baseline", "load", "condense", "rtk", "terse")
+
+
+def _log(msg: str, quiet: bool, *, err: bool = False) -> None:
+    if err:
+        print(msg, file=sys.stderr)
+    elif not quiet:
+        print(msg)
+
+
+def check_required_sections(text: str) -> List[str]:
+    return [
+        f"missing required section: '{section}'"
+        for section in REQUIRED_SECTIONS
+        if section not in text
+    ]
+
+
+def check_source_citations(report: Dict[str, Any]) -> List[str]:
+    violations = []
+    for rung in report.get("cost_ladder", []) or []:
+        source = rung.get("source_report")
+        if not source:
+            violations.append(
+                f"rung '{rung.get('id')}' has no source_report field"
+            )
+            continue
+        if not isinstance(source, str) or not source.strip():
+            violations.append(
+                f"rung '{rung.get('id')}' has empty source_report"
+            )
+    return violations
+
+
+def check_confidence_vs_source(report: Dict[str, Any]) -> List[str]:
+    """A `measured` rung's source_report must exist on disk."""
+    violations = []
+    for rung in report.get("cost_ladder", []) or []:
+        if rung.get("confidence") != "measured":
+            continue
+        source = rung.get("source_report") or ""
+        if source in ("", "n/a"):
+            continue  # baseline rung
+        path = REPO_ROOT / source
+        if not path.exists():
+            violations.append(
+                f"rung '{rung.get('id')}' is 'measured' but its "
+                f"source_report does not exist: {source}"
+            )
+    return violations
+
+
+def check_no_negative_savings(text: str) -> List[str]:
+    """A rung whose Δ-token value is positive must not be labelled a saving.
+
+    Heuristic: scan Panel A's rows; flag any row that contains the
+    German word "Ersparnis" with a positive token-delta in the same row.
+    """
+    violations = []
+    # Panel A rows are pipe-delimited; we read every line starting with "|"
+    # inside the cost ladder section.
+    in_panel_a = False
+    for line in text.splitlines():
+        if line.startswith("## Panel A"):
+            in_panel_a = True
+            continue
+        if in_panel_a and line.startswith("## "):
+            break
+        if not in_panel_a or not line.startswith("|"):
+            continue
+        if "Ersparnis" not in line:
+            continue
+        # Look for a "+" sign at the start of an integer-shaped delta.
+        # The format renders deltas as "+4 843" / "-186".
+        m = re.search(r"\|\s*([+-][0-9 ]+)\s*\|", line)
+        if m and m.group(1).strip().startswith("+"):
+            token_value = m.group(1).strip()
+            violations.append(
+                "row labelled 'Ersparnis' has a positive Δ-token value: "
+                f"{token_value!r} — positive deltas are costs, not savings."
+            )
+    return violations
+
+
+def check_canonical_rung_set(report: Dict[str, Any]) -> List[str]:
+    rungs = report.get("cost_ladder", []) or []
+    ids = [r.get("id") for r in rungs]
+    if list(ids) != list(CANONICAL_RUNG_IDS):
+        return [
+            f"cost_ladder rung ids must be {CANONICAL_RUNG_IDS}, "
+            f"got {tuple(ids)}"
+        ]
+    return []
+
+
+def lint(quiet: bool = False) -> int:
+    violations: List[str] = []
+
+    if not DASHBOARD.exists():
+        _log(
+            f"FAIL: dashboard not found: {DASHBOARD.relative_to(REPO_ROOT)}",
+            quiet,
+            err=True,
+        )
+        return 1
+    text = DASHBOARD.read_text()
+    violations.extend(check_required_sections(text))
+    violations.extend(check_no_negative_savings(text))
+
+    if not LATEST.exists():
+        # No JSON to deep-check — that's a placeholder dashboard.
+        # Required-sections check still applies; we degrade gracefully.
+        if violations:
+            for v in violations:
+                _log(f"FAIL: {v}", quiet, err=True)
+            return 1
+        _log(
+            "lint_value_dashboard: dashboard is a placeholder "
+            "(no value-v1.json yet) — structural checks pass.",
+            quiet=False,
+        )
+        return 0
+
+    try:
+        report = json.loads(LATEST.read_text())
+    except json.JSONDecodeError as exc:
+        _log(f"FAIL: {LATEST.name} is not valid JSON: {exc}", quiet, err=True)
+        return 1
+
+    violations.extend(check_source_citations(report))
+    violations.extend(check_confidence_vs_source(report))
+    violations.extend(check_canonical_rung_set(report))
+
+    if violations:
+        for v in violations:
+            _log(f"FAIL: {v}", quiet, err=True)
+        return 1
+    _log(
+        (
+            "lint_value_dashboard: OK — "
+            f"{len(report.get('cost_ladder', []))} rungs, "
+            f"{len(report.get('behaviour', []))} behaviour metrics, all "
+            "sections present, all sources cited."
+        ),
+        quiet=False,
+    )
+    return 0
+
+
+def parse_args(argv: List[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Lint docs/value.md for structural invariants."
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress non-error output.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: List[str] | None = None) -> int:
+    args = parse_args(argv if argv is not None else sys.argv[1:])
+    return lint(quiet=args.quiet)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/render_benchmark_md.py

@@ -103,10 +103,14 @@ def render_headline(track_a: dict, track_b: dict) -> str:
     lines = [
         "## Headline",
         "",
+        "> **Track A confirms surface availability** — a precondition, not an impact metric. "
+        "For the impact view (cost-ladder + behaviour with vs. without), see "
+        "[`docs/value.md`](value.md).",
+        "",
         "| Metric | with | without | delta |",
         "|---|---|---|---|",
-        f"| Track A trigger-accuracy | {fmt_pct(a_with_acc)} | {fmt_pct(a_wo_acc)} | "
-        f"{fmt_pct((a_with_acc or 0) - (a_wo_acc or 0))} |",
+        f"| Track A surface-availability | {fmt_pct(a_with_acc)} | {fmt_pct(a_wo_acc)} | "
+        f"{fmt_pct((a_with_acc or 0) - (a_wo_acc or 0))} _(structural — files present)_ |",
         f"| Track B completion-rate  | {fmt_pct(b_with_comp)} | {fmt_pct(b_wo_comp)} | "
         f"{fmt_pct((b_with_comp or 0) - (b_wo_comp or 0))} |",
         f"| Track B mean wall-time   | {fmt_num(b_results.get('mean_wall_time'))}s "