@event4u/agent-config 5.6.1 → 5.8.0

package/scripts/_lib/value_report.py

@@ -43,10 +43,12 @@ try:
         condense_rung_from_telegraph_v2,
         destructive_stops_metric,
         load_rung_from_frugality,
+        load_rung_from_projection,
         load_rung_from_router,
         rtk_rung_from_report,
         selection_metric_from_dev_reports,
         terse_rung_from_telegraph_v1,
+        thin_rung_from_projection,
     )
 except ImportError:
     from scripts._lib.value_ladder import (  # type: ignore[no-redef]
@@ -59,15 +61,18 @@ except ImportError:
         condense_rung_from_telegraph_v2,
         destructive_stops_metric,
         load_rung_from_frugality,
+        load_rung_from_projection,
         load_rung_from_router,
         rtk_rung_from_report,
         selection_metric_from_dev_reports,
         terse_rung_from_telegraph_v1,
+        thin_rung_from_projection,
     )
 
 
 REPO_ROOT = Path(__file__).resolve().parent.parent.parent
 ROUTER_JSON = REPO_ROOT / "dist" / "router.json"
+PROJECTION_COST = REPO_ROOT / "internal" / "bench" / "reports" / "projection-cost.json"
 RULES_DIR = REPO_ROOT / ".agent-src" / "rules"
 CHARTER_PATH = REPO_ROOT / ".agent-src" / "contexts" / "contracts" / "frugality-charter.md"
 FRUGALITY_BASELINE = REPO_ROOT / "agents" / "runtime" / "frugality" / "baseline.jsonl"
@@ -240,28 +245,37 @@ def assemble_value_v1(
     # Load rung — prefer the canonical kernel list from dist/router.json
     # (real always-loaded footprint), fall back to the frugality canon
     # baseline only when the router is missing on disk.
-    router = safe_load_json(ROUTER_JSON)
-    if router and "kernel" in router:
-        rule_chars = {
-            p.stem: len(p.read_text())
-            for p in RULES_DIR.glob("*.md")
-        } if RULES_DIR.exists() else {}
-        charter_chars = (
-            len(CHARTER_PATH.read_text()) if CHARTER_PATH.exists() else 0
-        )
-        load_rung = load_rung_from_router(
-            router, rule_chars, charter_chars, ref, pricing_row
-        )
-    else:
-        load_rung = load_rung_from_frugality(
-            latest_frugality_record(), ref, pricing_row
-        )
+    # Prefer the REAL eager footprint (projection-cost.json) — 0B.6 confirmed
+    # the primary tool eager-loads every rule body. Fall back to the
+    # kernel-only router rung, then the frugality canon, when the projection
+    # report is missing.
+    projection = safe_load_json(PROJECTION_COST)
+    load_rung = load_rung_from_projection(projection, ref, pricing_row)
+    if load_rung is None:
+        router = safe_load_json(ROUTER_JSON)
+        if router and "kernel" in router:
+            rule_chars = {
+                p.stem: len(p.read_text())
+                for p in RULES_DIR.glob("*.md")
+            } if RULES_DIR.exists() else {}
+            charter_chars = (
+                len(CHARTER_PATH.read_text()) if CHARTER_PATH.exists() else 0
+            )
+            load_rung = load_rung_from_router(
+                router, rule_chars, charter_chars, ref, pricing_row
+            )
+        else:
+            load_rung = load_rung_from_frugality(
+                latest_frugality_record(), ref, pricing_row
+            )
+    thin_rung = thin_rung_from_projection(projection, ref, pricing_row)
     t2 = safe_load_json(TELEGRAPH_V2)
     t1 = safe_load_json(TELEGRAPH_V1)
     rtk = safe_load_json(RTK_LATEST)
     ladder: List[Dict[str, Any]] = [
         baseline_rung(ref),
         load_rung,
+        thin_rung,
         condense_rung_from_telegraph_v2(t2, baseline_input_tokens, ref, pricing_row),
         rtk_rung_from_report(rtk, ref, pricing_row),
         terse_rung_from_telegraph_v1(t1, ref, pricing_row),

package/scripts/ai_council/modes.py

@@ -17,7 +17,7 @@ Resolution precedence — first non-empty wins:
     3. Global setting       ``ai_council.mode``
     4. Built-in default     ``manual``
 
-This mirrors how ``cost_profile`` resolves in
+This mirrors how ``rule_loading_tier`` resolves in
 ``.augment/guidelines/agent-infra/layered-settings.md``.
 
 The resolver is pure — it never touches the filesystem or environment.

package/scripts/ai_council/session.py

@@ -28,6 +28,10 @@ import shutil
 import sys
 from dataclasses import dataclass, field
 from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
 from typing import Iterable
 
 from scripts.ai_council.clients import CouncilResponse
@@ -37,7 +41,7 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 SESSIONS_DIR = REPO_ROOT / "agents" / "runtime" / "council" / "sessions"
 QUESTIONS_DIR = REPO_ROOT / "agents" / "runtime" / "council" / "questions"
 RESPONSES_DIR = REPO_ROOT / "agents" / "runtime" / "council" / "responses"
-SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
+SETTINGS_FILE = project_settings_path(REPO_ROOT)
 
 # Default retention for all council artefacts (questions, responses,
 # sessions). Overridden by `ai_council.session_retention_days`

package/scripts/audit_command_surface.py

@@ -37,12 +37,18 @@ from pathlib import Path
 from typing import List
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_package_core_path  # noqa: E402
+
 # Pre-monorepo: REPO_ROOT/.agent-src.uncondensed/commands. Post-move (ADR-017)
 # the core command surface lives under packages/core/.agent-src.uncondensed.
 # Fall back to the legacy path only if the packages layout is absent.
-_CORE_COMMANDS = REPO_ROOT / "packages" / "core" / ".agent-src.uncondensed" / "commands"
+_CORE_COMMANDS = resolve_package_core_path(".agent-src.uncondensed/commands")
 _LEGACY_COMMANDS = REPO_ROOT / ".agent-src.uncondensed" / "commands"
 DEFAULT_ROOT = _CORE_COMMANDS if _CORE_COMMANDS.is_dir() else _LEGACY_COMMANDS
+# Enforced packages/core target — read by scripts/check_gate_paths.py so a
+# future move that desyncs this path fails CI instead of silently no-opping.
+GATE_CORE_PATHS = (_CORE_COMMANDS,)
 REPORT_DIR = REPO_ROOT / "agents" / "reports"
 OUT_JSON = REPORT_DIR / "command-surface.json"
 OUT_MD = REPORT_DIR / "command-surface.md"

package/scripts/audit_initial_context.py

@@ -35,6 +35,13 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(REPO_ROOT / "scripts"))
 from _lib import token_count  # noqa: E402
+from _lib.agent_src import resolve_package_core_path  # noqa: E402
+
+_CORE_SRC = resolve_package_core_path(".agent-src.uncondensed")
+# Enforced packages/core targets — the skills + commands dirs the
+# description-catalog globs scan. Read by scripts/check_gate_paths.py so a
+# future move that desyncs them fails CI instead of silently no-opping.
+GATE_CORE_PATHS = (_CORE_SRC / "skills", _CORE_SRC / "commands")
 
 try:
     import yaml
@@ -111,10 +118,11 @@ def _catalog(glob_pat: str) -> dict:
 
 def description_catalog() -> dict:
     """0B.4 — description-catalog cost (eager progressive-disclosure surface)."""
+    core_rel = _CORE_SRC.relative_to(REPO_ROOT).as_posix()
     return {
         "skills_projected": _catalog(".claude/skills/*/SKILL.md"),
-        "skills_core_source": _catalog("packages/core/.agent-src.uncondensed/skills/*/SKILL.md"),
-        "commands_core_source": _catalog("packages/core/.agent-src.uncondensed/commands/**/*.md"),
+        "skills_core_source": _catalog(f"{core_rel}/skills/*/SKILL.md"),
+        "commands_core_source": _catalog(f"{core_rel}/commands/**/*.md"),
     }
 
 
@@ -132,11 +140,27 @@ def longest_rules(top: int = 10) -> list[dict]:
     return rows[:top]
 
 
+def thin_projection() -> dict:
+    """Eager-vs-thin rule-layer footprint (Phase 3.1 lever).
+
+    Reuses `scripts/project_thin_rules.py::measure` so the value dashboard can
+    cite a single persisted source for both the eager always-on cost and the
+    thin-projection saving. Returns an empty dict if the measurer is
+    unavailable, so the audit never hard-fails on it.
+    """
+    try:
+        from project_thin_rules import measure as _measure  # noqa: E402
+        return _measure()
+    except Exception:  # pragma: no cover — best-effort enrichment
+        return {}
+
+
 def build() -> dict:
     return {
         "generated": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"),
         "token_method": token_count.method_note(),
         "rule_footprint": rule_footprint(),
+        "thin_projection": thin_projection(),
         "description_catalog": description_catalog(),
         "longest_rules": longest_rules(),
     }

package/scripts/check_gate_paths.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Gate path-integrity check (R2 of road-to-test-and-gate-integrity).
+
+Asserts that every security/quality gate which enforces something against
+a fixed ``packages/core/`` target still resolves that target on disk. A
+``packages/core/`` move that desyncs a gate's hard-coded path fails CI here
+instead of silently no-opping (the ``aab5755`` class: the Iron-Law SHA gate
+pointed at a stale path and enforced nothing while CI stayed green).
+
+Design (AI council, claude-sonnet-4-5 + gpt-4o, 2026-06-02):
+
+- The check reads each gate's ACTUAL enforced paths via its module-level
+  ``GATE_CORE_PATHS`` attribute — it does NOT re-declare a copy of the path
+  strings. A hand-maintained path registry would reintroduce the very
+  desync risk this guards against, one layer down.
+- Scope is strictly the single-root hard-coders. Multi-root gates that
+  resolve via ``artefact_roots()`` (e.g. ``iron_law_sha``) are excluded:
+  asserting a single ``packages/core/`` path for them would false-pass on a
+  legacy layout or false-fail on a pack-only layout.
+
+The input set is this gate list (no separate config file).
+
+Usage:
+    python3 scripts/check_gate_paths.py
+Exit codes: 0 = all enforced targets resolve under packages/core/ ·
+1 = at least one missing / out-of-tree target · 2 = a gate failed to import.
+"""
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_package_core_path  # noqa: E402
+
+PACKAGE_CORE = resolve_package_core_path("")
+
+# Single-root gates that enforce against a fixed packages/core/ target and
+# expose it via a module-level GATE_CORE_PATHS tuple. Adding a gate here is
+# the only manual step; its paths are read from the gate, never copied.
+GATES: tuple[str, ...] = (
+    "inventory_abstraction_budget",
+    "audit_command_surface",
+    "lint_agents_md",
+    "audit_initial_context",
+)
+
+
+def _is_under_core(p: Path) -> bool:
+    try:
+        p.resolve().relative_to(PACKAGE_CORE.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def collect_gate_paths(gate_modules: tuple[str, ...]) -> dict[str, list[Path]]:
+    """Import each gate and read its declared ``GATE_CORE_PATHS``.
+
+    Raises ``ImportError`` (surfaced as exit 2 by ``main``) if a gate cannot
+    be imported — a gate whose path logic broke at import time is itself a
+    failure this check should not swallow.
+    """
+    out: dict[str, list[Path]] = {}
+    for name in gate_modules:
+        mod = importlib.import_module(name)
+        paths = getattr(mod, "GATE_CORE_PATHS", None)
+        if not paths:
+            raise AttributeError(
+                f"{name} has no non-empty GATE_CORE_PATHS — gate cannot be "
+                f"checked. Declare the packages/core targets it enforces."
+            )
+        out[name] = [Path(p) for p in paths]
+    return out
+
+
+def check_paths(named: dict[str, list[Path]]) -> list[tuple[str, str, Path]]:
+    """Return ``(gate, reason, path)`` for every target that fails.
+
+    Pure (no import side effects) so tests can drive it with fixtures.
+    A target fails when it does not resolve under ``packages/core/`` or
+    does not exist on disk.
+    """
+    failures: list[tuple[str, str, Path]] = []
+    for gate, paths in named.items():
+        for p in paths:
+            if not _is_under_core(p):
+                failures.append((gate, "not under packages/core/", p))
+            elif not p.exists():
+                failures.append((gate, "target does not exist", p))
+    return failures
+
+
+def main() -> int:
+    try:
+        named = collect_gate_paths(GATES)
+    except (ImportError, AttributeError) as exc:
+        print(f"❌  check-gate-paths: {exc}", file=sys.stderr)
+        return 2
+    failures = check_paths(named)
+    if failures:
+        print("❌  check-gate-paths: gate target(s) do not resolve under packages/core/:")
+        for gate, reason, path in failures:
+            print(f"    {gate}: {reason} → {path}")
+        print("\n  A packages/core/ move likely desynced a gate. Fix the gate's")
+        print("  GATE_CORE_PATHS (built via resolve_package_core_path) or the move.")
+        return 1
+    total = sum(len(v) for v in named.values())
+    print(f"✅  check-gate-paths: {total} enforced target(s) across "
+          f"{len(named)} gate(s) resolve under packages/core/.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/check_references.py

@@ -133,6 +133,53 @@ EXAMPLE_PATH_PATTERNS = [
 ]
 
 
+@dataclass(frozen=True)
+class AllowlistPattern:
+    """A token-class allowlist entry. `reason` is mandatory and auditable."""
+    pattern: "re.Pattern[str]"
+    reason: str
+
+
+# Content-class allowlist for known NON-reference token shapes.
+#
+# The skill/rule prose patterns (`X` skill / `X` rule) occasionally match
+# a backtick token that is not an artifact id — an execution-type enum
+# value, a pack identifier, or a bare meta-qualifier keyword. Historically
+# each such false positive was dodged by *rewording the prose per file*
+# (e.g. dc84ed01 "reword execution-type mentions to dodge check-refs
+# false positive", bd02ef0b "avoid check-refs false-positive on pack
+# name"), a treadmill that distorts natural wording release after release.
+# This layer matches the token *class* centrally instead, so the natural
+# wording passes without per-file edits. It is distinct from:
+#   - SKIP_DIRS          (path-level, whole-directory)
+#   - FILE_SKIP_MARKER   (file-level opt-out)
+#   - LINE_IGNORE_MARKER (per-line opt-out)
+# Every entry carries a mandatory `reason` so the allowlist stays
+# auditable and a future reader can tell why a class is exempt.
+ALLOWLIST_PATTERNS: List[AllowlistPattern] = [
+    AllowlistPattern(
+        re.compile(r"^(?:manual|assisted|automated)$"),
+        "execution-type enum value (runtime-safety frontmatter), e.g. a "
+        "`manual` skill — not a skill/rule id (dc84ed01)",
+    ),
+    AllowlistPattern(
+        re.compile(r"^pack-[\w-]+$"),
+        "pack / workspace identifier, e.g. `pack-ai-video` skills — not a "
+        "skill/rule id (bd02ef0b)",
+    ),
+    AllowlistPattern(
+        re.compile(r"^(?:skill|rule|command|guideline|persona|context|pack|workspace)$"),
+        "bare meta-qualifier keyword used in prose (the `command` vs "
+        "`skill` distinction, etc.) — not an artifact id",
+    ),
+]
+
+
+def _is_allowlisted(name: str) -> bool:
+    """True when `name` matches a known non-reference token class."""
+    return any(entry.pattern.match(name) for entry in ALLOWLIST_PATTERNS)
+
+
 def collect_artifacts(root: Path) -> dict[str, set[str]]:
     """Build lookup sets for skills, rules, commands, guidelines, personas."""
     arts: dict[str, set[str]] = {
@@ -345,7 +392,8 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
         # Skill name references
         for m in SKILL_REF_PATTERN.finditer(line):
             name = m.group(1)
-            if name not in artifacts["skills"] and name not in _SKIP_NAMES:
+            if name not in artifacts["skills"] and name not in _SKIP_NAMES \
+                    and not _is_allowlisted(name):
                 broken.append(BrokenRef(
                     file=str(filepath), line=i, ref=name,
                     ref_type="skill", severity="warning",
@@ -355,7 +403,8 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
         # Rule name references
         for m in RULE_REF_PATTERN.finditer(line):
             name = m.group(1)
-            if name not in artifacts["rules"] and name not in _SKIP_NAMES:
+            if name not in artifacts["rules"] and name not in _SKIP_NAMES \
+                    and not _is_allowlisted(name):
                 broken.append(BrokenRef(
                     file=str(filepath), line=i, ref=name,
                     ref_type="rule", severity="warning",

package/scripts/check_skill_requires.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Skill-composition graph gate (roadmap 3.4).
+
+Validates the `requires_skills:` frontmatter field (the skill→skill
+composition graph) against two invariants:
+
+1. **Referential integrity** — every `requires_skills` target names a real
+   skill in the suite.
+2. **Co-availability** — whenever a parent skill ships, every sub-skill its
+   body assumes must ship too. A sub-skill is co-available under a parent's
+   pack `P` iff one of the sub-skill's packs is in `{P}` ∪ the transitive
+   `requires_hint` closure of `P` (from `config/discovery/packs.yml`), or
+   the sub-skill is always-on (no pack). A parent with no pack (always-on)
+   may only require always-on sub-skills.
+
+This is distinct from the ADR-015 artefact→pack `requires` field; this gate
+operates on `requires_skills` (skill→skill) only.
+
+Exit 0 = clean · 1 = at least one violation.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+sys.path.insert(0, str(Path(__file__).resolve().parent / "_lib"))
+
+import yaml  # noqa: E402
+
+from _lib.agent_src import ROOT, iter_artefacts  # noqa: E402
+from validate_frontmatter import parse_frontmatter  # noqa: E402
+
+PACKS_YML = ROOT / "config" / "discovery" / "packs.yml"
+
+
+def _load_pack_closure() -> dict[str, set[str]]:
+    """pack_id → transitive set of {self} ∪ requires_hint closure."""
+    raw = yaml.safe_load(PACKS_YML.read_text(encoding="utf-8")) or []
+    direct: dict[str, set[str]] = {}
+    for entry in raw:
+        pid = entry["id"]
+        direct[pid] = set(entry.get("requires_hint") or [])
+
+    closure: dict[str, set[str]] = {}
+
+    def resolve(pid: str, seen: set[str]) -> set[str]:
+        if pid in closure:
+            return closure[pid]
+        acc = {pid}
+        for dep in direct.get(pid, set()):
+            if dep in seen:
+                continue
+            acc |= resolve(dep, seen | {pid})
+        closure[pid] = acc
+        return acc
+
+    for pid in direct:
+        resolve(pid, set())
+    return closure
+
+
+def _collect_skills() -> dict[str, dict]:
+    """skill_id (directory name) → {packs: set[str], requires_skills: list[str], path}."""
+    skills: dict[str, dict] = {}
+    for path in iter_artefacts("SKILL.md"):
+        # logical id = the skill's directory name
+        skill_id = path.parent.name
+        fm, _ = parse_frontmatter(path.read_text(encoding="utf-8"))
+        if fm is None:
+            continue
+        skills[skill_id] = {
+            "packs": set(fm.get("packs") or []),
+            "requires_skills": list(fm.get("requires_skills") or []),
+            "path": path.relative_to(ROOT).as_posix(),
+        }
+    return skills
+
+
+def main() -> int:
+    closure = _load_pack_closure()
+    skills = _collect_skills()
+    errors: list[str] = []
+
+    for skill_id, info in sorted(skills.items()):
+        reqs = info["requires_skills"]
+        if not reqs:
+            continue
+        parent_packs: set[str] = info["packs"]
+        for req in reqs:
+            target = skills.get(req)
+            # (1) referential integrity
+            if target is None:
+                errors.append(
+                    f"{info['path']}: requires_skills → unknown skill '{req}' "
+                    f"(no skills/{req}/SKILL.md in the suite)."
+                )
+                continue
+            # (2) co-availability
+            req_packs: set[str] = target["packs"]
+            if not req_packs:
+                # always-on sub-skill is reachable from anywhere
+                continue
+            if not parent_packs:
+                # always-on parent may only require an always-on sub-skill
+                errors.append(
+                    f"{info['path']}: always-on skill '{skill_id}' requires "
+                    f"'{req}' which is pack-gated ({sorted(req_packs)}); a base "
+                    f"install would ship '{skill_id}' without '{req}'."
+                )
+                continue
+            for p in sorted(parent_packs):
+                reachable = closure.get(p, {p})
+                if req_packs & reachable:
+                    continue
+                hint = sorted(req_packs - reachable)
+                errors.append(
+                    f"{info['path']}: skill '{skill_id}' (pack '{p}') requires "
+                    f"'{req}' (pack {sorted(req_packs)}), but '{p}' does not reach "
+                    f"it. Add requires_hint: {hint} to pack '{p}' in "
+                    f"config/discovery/packs.yml, or move '{req}' into a reachable pack."
+                )
+
+    if errors:
+        print("❌  check_skill_requires: skill-composition graph has unmet edges:")
+        for e in errors:
+            print(f"  🔴 {e}")
+        print(
+            "\nEvery sub-skill a parent's body invokes must ship wherever the "
+            "parent ships. Declare the missing pack dependency or co-locate the skill."
+        )
+        return 1
+
+    n_edges = sum(len(i["requires_skills"]) for i in skills.values())
+    print(
+        f"✅  check_skill_requires: {n_edges} composition edge(s) across "
+        f"{sum(1 for i in skills.values() if i['requires_skills'])} skill(s) — all sub-skills co-available."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())