@event4u/agent-config 4.9.0 → 5.1.0

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 "