@event4u/agent-config 6.1.0 → 7.0.1

package/src/scripts/check_council_references.py

@@ -1,228 +0,0 @@
-#!/usr/bin/env python3
-"""CI guard for the council clause of the `no-roadmap-references` rule.
-
-Council artefacts under `agents/runtime/council/{questions,responses,sessions}/`
-are gitignored, local-only, and auto-pruned. A link to a specific
-council file rots three ways: gitignored (not in cloned repo),
-pruned after the retention window (gone even locally), and the
-installed `.augment/` projection cannot follow a path that does not
-exist in the consumer.
-
-This linter scans durable artefacts for forbidden links to specific
-council files. Directory mentions and placeholder paths
-(`<timestamp>`, `<topic-slug>`) are allowed — they document the
-output-path convention, not a live reference.
-
-Forbidden hits in this codebase exist today (kernel-membership ADRs
-cite real session JSONs as decision traces). Two source/target shapes
-are exempt structurally — see STRUCTURAL_CARVEOUTS below — because
-they encode immutable decision provenance, not transient drafting
-state. Anything else needs an inline pragma at the end of the line:
-
-    `agents/runtime/council/sessions/...json` <!-- council-ref-allowed: usage example in this docstring -->
-
-Exit codes:
-  0 — no forbidden references.
-  1 — at least one forbidden reference found.
-
-Invocation (from project root):
-  python3 scripts/check_council_references.py
-"""
-
-from __future__ import annotations
-
-import re
-import sys
-from pathlib import Path
-from typing import Iterable
-
-QUIET = "--quiet" in sys.argv
-
-ROOT = Path(".")
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _lib.agent_src import artefact_roots, strip_source_prefix  # noqa: E402
-
-# A specific file inside a council dir: must end with .md or .json,
-# must NOT contain `<` or `>` (placeholders), must NOT contain backticks
-# or quotes (those are line delimiters, not path content).
-PATTERN = re.compile(
-    r"agents/runtime/council/(?:questions|responses|sessions)/"
-    r"([^\s\"'<>)\]`]+\.(?:md|json))"
-)
-
-# Only these durable surfaces are scanned. Archive, analysis, and the
-# council dirs themselves are excluded by design.
-#
-# Source roots (legacy `.agent-src.uncondensed/` and every
-# `packages/*/.agent-src.uncondensed/`) are discovered at runtime via
-# `artefact_roots()` so the linter follows the monorepo physical layout.
-FIXED_SCAN_ROOTS = (
-    "agents/roadmaps",
-    "agents/settings/contexts",
-    "agents/reference/docs",
-    "docs/contracts",
-    "docs/decisions",
-    "docs/guidelines",
-)
-
-
-def _scan_roots() -> tuple[str, ...]:
-    cwd = Path(".").resolve()
-    roots: list[str] = []
-    for r in artefact_roots():
-        try:
-            roots.append(r.relative_to(cwd).as_posix() if r.is_absolute() else r.as_posix())
-        except ValueError:
-            # Root lives outside the current working directory (e.g. tests
-            # chdir into a tmp tree). Skip — the test isolates its own
-            # source tree.
-            continue
-    roots.extend(FIXED_SCAN_ROOTS)
-    return tuple(roots)
-
-
-SCAN_EXTS = (".md", ".yml", ".yaml", ".json", ".py")
-
-# Files (or directory prefixes) that legitimately document the output
-# convention or are scratch / archived. Paths are POSIX-style, repo-relative.
-ALLOWLIST_PREFIXES: tuple[str, ...] = (
-    # Archived roadmaps — historical evidence trail.
-    "agents/roadmaps/archive/",
-    # Working comparison docs — forward-refs to planned artefacts (mirrors
-    # the SKIP_DIRS contract in scripts/check_references.py).
-    "agents/evidence/analysis/",
-    # The rule itself documents forbidden vs. allowed forms.
-    ".agent-src.uncondensed/rules/no-roadmap-references.md",
-    # ai-council skill documents the output-path schema.
-    ".agent-src.uncondensed/skills/ai-council/",
-    # Council commands document the output-path schema.
-    ".agent-src.uncondensed/commands/council/",
-    ".agent-src.uncondensed/commands/council.md",
-)
-# Top-level files that are also exempt (e.g. CHANGELOG with historical entries).
-ALLOWLIST_FILES: frozenset[str] = frozenset({
-    "CHANGELOG.md",
-})
-
-INLINE_PRAGMA = re.compile(r"<!--\s*council-ref-allowed:[^>]*-->")
-
-# Structural carve-outs — (source_pattern, target_pattern) pairs where
-# the reference is immutable decision provenance rather than transient
-# drafting state. Driven by the 2026-05-14 P3.4 council round
-# (agents/runtime/council/sessions/2026-05-14-p3-4-references/synthesis.md). <!-- council-ref-allowed: carve-out documentation example -->
-#
-# Each entry: source file matches `source` regex AND the captured
-# reference path matches `target` regex → reference is allowed without
-# an inline pragma.
-STRUCTURAL_CARVEOUTS: tuple[tuple[re.Pattern[str], re.Pattern[str]], ...] = (
-    # (a) evaluation-context → council-question:
-    # the question file is a frozen function-parameter / spend-gate
-    # input, not a documentation link.
-    (
-        re.compile(r"^agents/settings/contexts/evaluation-[^/]+\.md$"),
-        re.compile(r"^agents/runtime/council/questions/[^/]+\.md$"),
-    ),
-    # (b) contract → council-session-synthesis:
-    # the synthesis file is the audit-trail receipt the contract cites
-    # as decision provenance; the contract inlines the decision body.
-    (
-        re.compile(r"^docs/contracts/[^/]+\.md$"),
-        re.compile(r"^agents/runtime/council/sessions/[^/]+/synthesis\.md$"),
-    ),
-)
-
-
-def _is_allowlisted(rel: str) -> bool:
-    """Match a repo-relative POSIX path against the allowlist.
-
-    Allowlist prefixes are written against the legacy
-    ``.agent-src.uncondensed/`` layout. A physical hit under
-    ``packages/*/.agent-src.uncondensed/`` is normalised to the same
-    logical path before matching so entries keep covering relocated files.
-    """
-    if rel in ALLOWLIST_FILES:
-        return True
-    if any(rel.startswith(prefix) for prefix in ALLOWLIST_PREFIXES):
-        return True
-    logical = strip_source_prefix(rel)
-    if logical is not None:
-        canon = f"{_LEGACY_PREFIX_STR}{logical}"
-        if any(canon.startswith(prefix) for prefix in ALLOWLIST_PREFIXES):
-            return True
-    return False
-
-
-_LEGACY_PREFIX_STR = ".agent-src.uncondensed/"
-
-
-def _is_structurally_allowed(source_rel: str, target_capture: str) -> bool:
-    """True when (source, target) matches a structural carve-out pair."""
-    for src_re, tgt_re in STRUCTURAL_CARVEOUTS:
-        if src_re.match(source_rel) and tgt_re.match(target_capture):
-            return True
-    return False
-
-
-def _scan_file(path: Path) -> list[tuple[int, str]]:
-    findings: list[tuple[int, str]] = []
-    rel = path.as_posix()
-    try:
-        text = path.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
-        return findings
-    for ln, line in enumerate(text.splitlines(), 1):
-        if INLINE_PRAGMA.search(line):
-            continue
-        for m in PATTERN.finditer(line):
-            if _is_structurally_allowed(rel, m.group(0)):
-                continue
-            findings.append((ln, m.group(0)))
-    return findings
-
-
-def _iter_files(roots: Iterable[str]) -> Iterable[Path]:
-    for root in roots:
-        base = ROOT / root
-        if not base.exists():
-            continue
-        if base.is_file():
-            yield base
-            continue
-        for path in sorted(base.rglob("*")):
-            if path.is_file() and path.suffix in SCAN_EXTS:
-                yield path
-
-
-def main() -> int:
-    violations: list[tuple[Path, int, str]] = []
-    for path in _iter_files(_scan_roots()):
-        rel = path.as_posix()
-        if _is_allowlisted(rel):
-            continue
-        for ln, ref in _scan_file(path):
-            violations.append((path, ln, ref))
-
-    if not violations:
-        if not QUIET:
-            print("✅  No forbidden council references in durable artefacts.")
-        return 0
-
-    print(f"❌  {len(violations)} forbidden council reference(s):\n")
-    for path, ln, ref in violations:
-        print(f"  - {path.as_posix()}:{ln}: {ref}")
-    print(
-        "\nRule: dist/agent-src/rules/no-roadmap-references.md (council clause)\n"
-        "Fix: inline the convergence summary (members + date) instead of\n"
-        "linking the file. Two source/target shapes are exempt structurally\n"
-        "(evaluation-context → council-question, contract →\n"
-        "council-session-synthesis) — see STRUCTURAL_CARVEOUTS in this\n"
-        "script. Otherwise append "
-        "<!-- council-ref-allowed: <reason> --> on the same line to\n"
-        "suppress when the reference is genuinely required (ADR decision\n"
-        "trace)."
-    )
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/check_discovery_determinism.py

@@ -1,70 +0,0 @@
-#!/usr/bin/env python3
-"""Determinism check — runs the discovery scanner twice and diffs the output.
-
-The `generated_at` field is normalised because it intentionally captures
-wall-clock time. Everything else (artefact order, unassigned order,
-checksum) MUST be byte-identical between runs.
-
-CLI:
-  python scripts/check_discovery_determinism.py
-
-Exit codes:
-  0  byte-identical (apart from generated_at)
-  1  drift detected
-"""
-from __future__ import annotations
-
-import json
-import subprocess
-import sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[2]
-SCANNER = ROOT / "src" / "scripts" / "build_discovery_manifest.py"
-
-
-def _run() -> dict:
-    proc = subprocess.run(
-        [sys.executable, str(SCANNER)],
-        capture_output=True,
-        text=True,
-        check=False,
-        cwd=str(ROOT),
-    )
-    if proc.returncode != 0:
-        print(proc.stderr, file=sys.stderr)
-        raise SystemExit(f"scanner failed: exit {proc.returncode}")
-    return json.loads(proc.stdout)
-
-
-def _normalise(manifest: dict) -> dict:
-    out = dict(manifest)
-    out["generated_at"] = "<normalised>"
-    return out
-
-
-def main() -> int:
-    a = _normalise(_run())
-    b = _normalise(_run())
-    sa = json.dumps(a, indent=2, sort_keys=True, ensure_ascii=False)
-    sb = json.dumps(b, indent=2, sort_keys=True, ensure_ascii=False)
-    if sa != sb:
-        print("DRIFT: scanner produced different output across two runs", file=sys.stderr)
-        # show first divergence
-        for i, (la, lb) in enumerate(zip(sa.splitlines(), sb.splitlines()), 1):
-            if la != lb:
-                print(f"  line {i}:", file=sys.stderr)
-                print(f"    run1: {la}", file=sys.stderr)
-                print(f"    run2: {lb}", file=sys.stderr)
-                break
-        return 1
-    # also assert the checksum survives the round-trip
-    if a["checksum"] != b["checksum"]:
-        print(f"DRIFT: checksum changed ({a['checksum']} vs {b['checksum']})", file=sys.stderr)
-        return 1
-    print(f"OK: deterministic across 2 runs, checksum {a['checksum'][:24]}...")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/check_gate_paths.py

@@ -1,128 +0,0 @@
-#!/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 source target still resolves that target on disk. A 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).
-
-6.0.x (ADR-051) collapsed the ``packages/`` tree: the uncondensed source
-container moved to ``src/agent-src/`` and the command surface to
-``src/domains/``. The enforced targets therefore now resolve under ``src/``,
-not ``packages/core/``. The integrity property is unchanged — every declared
-target must exist on disk under the active source tree.
-
-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 the source tree ·
-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.parent
-sys.path.insert(0, str(REPO_ROOT / "src" / "scripts"))
-
-# Active source tree roots a gate target may legitimately resolve under.
-# ``packages/`` is retained for back-compat with any pre-collapse layout that
-# still ships it; post-ADR-051 the targets live under ``src/``.
-_SOURCE_TREE_ROOTS = (REPO_ROOT / "src", REPO_ROOT / "packages")
-
-# 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_source_tree(p: Path) -> bool:
-    rp = p.resolve()
-    for root in _SOURCE_TREE_ROOTS:
-        try:
-            rp.relative_to(root.resolve())
-            return True
-        except ValueError:
-            continue
-    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 source 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 the source tree
-    (``src/`` or ``packages/``) 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_source_tree(p):
-                failures.append((gate, "not under the source tree (src/ or packages/)", 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 the source tree:")
-        for gate, reason, path in failures:
-            print(f"    {gate}: {reason} → {path}")
-        print("\n  A source-tree move likely desynced a gate. Fix the gate's")
-        print("  GATE_CORE_PATHS 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 the source tree.")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/scripts/check_iron_law_prominence.py

@@ -1,145 +0,0 @@
-#!/usr/bin/env python3
-"""
-Iron Law prominence checker — enforces that any rule file declaring an
-"Iron Law" places it at the top of the file at H2 level.
-
-Rules:
-  1. No heading at H3 or deeper may match "Iron Law(s)" — Iron Laws must
-     be H2 sections, never sub-sections.
-  2. If a file declares one or more Iron-Law H2 sections, at least one
-     of them must be among the first two H2 headings of the file.
-
-Files with no Iron-Law heading at all are exempt — they may legitimately
-reference Iron Laws from other rules in prose only.
-
-Code blocks are skipped to avoid false positives on quoted text.
-
-Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import re
-import sys
-from dataclasses import dataclass, asdict
-from pathlib import Path
-
-HEADING_RE = re.compile(r"^(#{1,6})\s+(.+?)\s*$")
-IRON_LAW_RE = re.compile(r"\biron\s+laws?\b", re.IGNORECASE)
-FENCE_RE = re.compile(r"^\s*```")
-
-
-@dataclass
-class Violation:
-    file: str
-    line: int
-    kind: str        # "deep_iron_law" | "buried_iron_law"
-    detail: str
-
-
-def _parse_headings(text: str) -> list[tuple[int, int, str]]:
-    """Return (line_no, depth, title) for each heading outside code fences."""
-    headings: list[tuple[int, int, str]] = []
-    in_fence = False
-    for lineno, raw in enumerate(text.splitlines(), start=1):
-        if FENCE_RE.match(raw):
-            in_fence = not in_fence
-            continue
-        if in_fence:
-            continue
-        m = HEADING_RE.match(raw)
-        if not m:
-            continue
-        depth = len(m.group(1))
-        title = m.group(2).strip()
-        headings.append((lineno, depth, title))
-    return headings
-
-
-def scan_file(path: Path) -> list[Violation]:
-    text = path.read_text(encoding="utf-8")
-    headings = _parse_headings(text)
-
-    violations: list[Violation] = []
-
-    # Rule 1: no Iron Law at H3 or deeper
-    for lineno, depth, title in headings:
-        if depth >= 3 and IRON_LAW_RE.search(title):
-            violations.append(Violation(
-                file=str(path), line=lineno, kind="deep_iron_law",
-                detail=f"H{depth} heading `{title}` — promote to H2",
-            ))
-
-    # Rule 2: if any H2 Iron Law exists, it must be in first 2 H2 positions
-    h2 = [(ln, t) for ln, d, t in headings if d == 2]
-    iron_h2 = [(ln, t) for ln, t in h2 if IRON_LAW_RE.search(t)]
-    if iron_h2:
-        first_two_lines = {ln for ln, _ in h2[:2]}
-        if not any(ln in first_two_lines for ln, _ in iron_h2):
-            first_iron_ln, first_iron_title = iron_h2[0]
-            preceding = [t for ln, t in h2 if ln < first_iron_ln]
-            violations.append(Violation(
-                file=str(path), line=first_iron_ln, kind="buried_iron_law",
-                detail=(
-                    f"Iron Law H2 `{first_iron_title}` at line {first_iron_ln} "
-                    f"is preceded by {len(preceding)} non-Iron-Law H2 section(s): "
-                    f"{preceding}. Move Iron Law into the first 2 H2 positions."
-                ),
-            ))
-
-    return violations
-
-
-def _resolve_targets(paths: list[str]) -> list[Path]:
-    out: list[Path] = []
-    for raw in paths:
-        p = Path(raw)
-        if p.is_dir():
-            out.extend(sorted(p.rglob("*.md")))
-        elif p.suffix == ".md":
-            out.append(p)
-    return out
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
-        "paths", nargs="*",
-        default=[".agent-src.uncondensed/rules"],
-        help="Files or directories to scan (default: .agent-src.uncondensed/rules)",
-    )
-    parser.add_argument("--format", choices=["text", "json"], default="text")
-    parser.add_argument("--quiet", action="store_true", help="Only print on failure")
-    args = parser.parse_args()
-
-    targets = _resolve_targets(args.paths)
-    all_violations: list[Violation] = []
-    for path in targets:
-        if not path.exists():
-            print(f"⚠️  Not found: {path}", file=sys.stderr)
-            continue
-        all_violations.extend(scan_file(path))
-
-    if args.format == "json":
-        print(json.dumps([asdict(v) for v in all_violations], indent=2, ensure_ascii=False))
-    else:
-        if not all_violations:
-            if not args.quiet:
-                print(f"✅  Iron Law prominence clean ({len(targets)} file(s) scanned).")
-        else:
-            print(f"❌  {len(all_violations)} Iron-Law prominence violation(s):\n")
-            for v in all_violations:
-                print(f"  {v.file}:{v.line} — {v.kind}")
-                print(f"    │ {v.detail}")
-
-    return 1 if all_violations else 0
-
-
-if __name__ == "__main__":
-    try:
-        sys.exit(main())
-    except Exception as exc:  # noqa: BLE001
-        print(f"❌  Internal error: {exc}", file=sys.stderr)
-        sys.exit(3)