@event4u/agent-config 2.25.0 → 3.0.0

package/scripts/check_council_layout.py

@@ -4,21 +4,23 @@
 Council artefacts (questions, responses, sessions) belong in three
 canonical directories under `agents/`:
 
-  - agents/council-questions/<topic-slug>.md       (paired with roadmap/ADR)
-  - agents/council-responses/<topic-slug>.json     (paired with question)
-  - agents/council-sessions/<UTC-timestamp>.json   (ad-hoc sessions)
+  - agents/runtime/council/questions/<topic-slug>.md       (paired with roadmap/ADR)
+  - agents/runtime/council/responses/<topic-slug>.json     (paired with question)
+  - agents/runtime/council/sessions/<UTC-timestamp>.json   (ad-hoc sessions)
 
 The three canonical dirs are gitignored — the linter therefore only
 catches **misplacement**, not naming-conventions inside the dirs:
 
   - Files at agents/ root with a council-* or .council-* prefix
-    (e.g. agents/council-question-foo.md, agents/.council-foo.md).
+    (e.g. agents/council-foo.md, agents/.council-foo.md).
   - council-* files under any other subdirectory of agents/.
 
-`agents/audit-*/` directories are exempt — historical audit bundles
-are cohesive, checked-in narratives (the canonical council dirs are
-gitignored) and may legitimately include council-* artefacts as part
-of the audit's evidence trail.
+`agents/evidence/audits/` is exempt — historical audit bundles are cohesive,
+checked-in narratives (the canonical council dirs are gitignored)
+and may legitimately include council-* artefacts as part of the
+audit's evidence trail. `agents/runtime/` is exempt too — the
+canonical council dirs live at `agents/runtime/council/{questions,
+responses,sessions}/` and the whole `runtime/` tree is gitignored.
 
 Failure modes are enforced by `.agent-src.uncompressed/skills/ai-council/SKILL.md`
 § "Output path convention".
@@ -40,15 +42,17 @@ from pathlib import Path
 QUIET = "--quiet" in sys.argv
 
 AGENTS_ROOT = Path("agents")
+# Canonical council dirs now live under agents/runtime/council/.
+# Stored as relative POSIX paths from AGENTS_ROOT.
 CANONICAL_DIRS = {
-    "council-questions": ".md",
-    "council-responses": ".json",
-    "council-sessions": ".json",
+    "runtime/council/questions": ".md",
+    "runtime/council/responses": ".json",
+    "runtime/council/sessions": ".json",
 }
-# Subdirectory prefixes whose contents are exempt from the layout check.
-# `audit-*/` covers historical audit bundles where council artefacts
-# form part of the documented evidence trail.
-EXEMPT_DIR_PREFIXES = ("audit-",)
+# Top-level subdirectories whose contents are exempt from the layout
+# check. `audits/` covers historical audit bundles. `runtime/` is the
+# gitignored volatile tree (canonical council dirs live there).
+EXEMPT_DIR_PREFIXES = ("audits", "runtime")
 # A council artefact is a file whose name starts with `council-` or
 # `.council-`. This intentionally excludes roadmaps like
 # `road-to-ai-council.md` whose stem only contains the word "council".
@@ -71,8 +75,8 @@ def find_violations(root: Path) -> list[str]:
         if is_council_artefact(path):
             findings.append(
                 f"{path}: council artefact at agents/ root — move to "
-                f"agents/council-questions/, agents/council-responses/, "
-                f"or agents/council-sessions/ per ai-council § Output path "
+                f"agents/runtime/council/questions/, agents/runtime/council/responses/, "
+                f"or agents/runtime/council/sessions/ per ai-council § Output path "
                 f"convention."
             )
 
@@ -86,14 +90,16 @@ def find_violations(root: Path) -> list[str]:
             continue
         if len(rel.parts) == 1:
             continue  # already handled above
-        if rel.parts[0] in CANONICAL_DIRS:
+        rel_posix = rel.as_posix()
+        if any(rel_posix.startswith(d + "/") for d in CANONICAL_DIRS):
             continue
         if rel.parts[0].startswith(EXEMPT_DIR_PREFIXES):
             continue
         findings.append(
             f"{path}: council artefact in non-canonical directory "
-            f"agents/{rel.parts[0]}/ — only council-questions/, "
-            f"council-responses/, council-sessions/ are allowed."
+            f"agents/{rel.parts[0]}/ — only "
+            f"agents/runtime/council/{{questions,responses,sessions}}/ "
+            f"are allowed."
         )
 
     return findings

package/scripts/check_council_references.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """CI guard for the council clause of the `no-roadmap-references` rule.
 
-Council artefacts under `agents/council-{questions,responses,sessions}/`
+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
@@ -19,7 +19,7 @@ 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/council-sessions/...json` <!-- council-ref-allowed: <reason> -->
+    `agents/runtime/council/sessions/...json` <!-- council-ref-allowed: <reason> -->
 
 Exit codes:
   0 — no forbidden references.
@@ -44,7 +44,7 @@ ROOT = Path(".")
 # must NOT contain `<` or `>` (placeholders), must NOT contain backticks
 # or quotes (those are line delimiters, not path content).
 PATTERN = re.compile(
-    r"agents/council-(?:questions|responses|sessions)/"
+    r"agents/runtime/council/(?:questions|responses|sessions)/"
     r"([^\s\"'<>)\]`]+\.(?:md|json))"
 )
 
@@ -53,8 +53,8 @@ PATTERN = re.compile(
 SCAN_ROOTS = (
     ".agent-src.uncompressed",
     "agents/roadmaps",
-    "agents/contexts",
-    "agents/docs",
+    "agents/settings/contexts",
+    "agents/reference/docs",
     "docs/contracts",
     "docs/decisions",
     "docs/guidelines",
@@ -68,7 +68,7 @@ ALLOWLIST_PREFIXES: tuple[str, ...] = (
     "agents/roadmaps/archive/",
     # Working comparison docs — forward-refs to planned artefacts (mirrors
     # the SKIP_DIRS contract in scripts/check_references.py).
-    "agents/analysis/",
+    "agents/evidence/analysis/",
     # The rule itself documents forbidden vs. allowed forms.
     ".agent-src.uncompressed/rules/no-roadmap-references.md",
     # ai-council skill documents the output-path schema.
@@ -87,7 +87,7 @@ 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/council-sessions/2026-05-14-p3-4-references/synthesis.md).
+# (agents/runtime/council/sessions/2026-05-14-p3-4-references/synthesis.md).
 #
 # Each entry: source file matches `source` regex AND the captured
 # reference path matches `target` regex → reference is allowed without
@@ -97,15 +97,15 @@ STRUCTURAL_CARVEOUTS: tuple[tuple[re.Pattern[str], re.Pattern[str]], ...] = (
     # the question file is a frozen function-parameter / spend-gate
     # input, not a documentation link.
     (
-        re.compile(r"^agents/contexts/evaluation-[^/]+\.md$"),
-        re.compile(r"^agents/council-questions/[^/]+\.md$"),
+        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/council-sessions/[^/]+/synthesis\.md$"),
+        re.compile(r"^agents/runtime/council/sessions/[^/]+/synthesis\.md$"),
     ),
 )
 

package/scripts/check_discovery_determinism.py

@@ -0,0 +1,70 @@
+#!/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[1]
+SCANNER = ROOT / "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/scripts/check_kernel_rule_bundle.py

@@ -20,7 +20,7 @@ Inputs:
 Exit codes: 0 = pass · 1 = fail (> 1 kernel rule, no override) ·
 3 = internal error.
 
-Source: `agents/contexts/adr-always-budget-relief-strategy.md`.
+Source: `agents/settings/contexts/adr-always-budget-relief-strategy.md`.
 """
 from __future__ import annotations
 
@@ -140,7 +140,7 @@ def main(argv: list[str] | None = None) -> int:
         file=sys.stderr,
     )
     print(
-        "   Source: agents/contexts/adr-always-budget-relief-strategy.md "
+        "   Source: agents/settings/contexts/adr-always-budget-relief-strategy.md "
         "(Phase 4.2).",
         file=sys.stderr,
     )

package/scripts/check_no_roadmap_refs.py

@@ -34,7 +34,7 @@ STABLE_TREES = (
     ".agent-src.uncompressed/contexts",
     ".agent-src.uncompressed/templates",
     ".agent-src.uncompressed/personas",
-    "agents/contexts",
+    "agents/settings/contexts",
     "docs/guidelines",
     "docs/contracts",
 )
@@ -128,7 +128,7 @@ def format_text(violations: list[Violation]) -> str:
     for v in violations:
         lines.append(f"  🔴 {v.file}:{v.line}  →  {v.match}")
     lines.append(
-        "\nPromote the durable conclusion to agents/contexts/ and cite that "
+        "\nPromote the durable conclusion to agents/settings/contexts/ and cite that "
         "instead. See .agent-src.uncompressed/rules/no-roadmap-references.md."
     )
     return "\n".join(lines)

package/scripts/check_one_off_location.py

@@ -7,7 +7,7 @@ guard fails CI if a new probe lands anywhere else in the tree.
 
 Rationale: one-off council probes / phase-specific measurements are
 inherently single-purpose; their durable artefact is the council
-session under ``agents/council-sessions/``. Keeping them in the
+session under ``agents/runtime/council/sessions/``. Keeping them in the
 archive prevents the ``scripts/`` root from accumulating noise and
 makes their lifecycle visible (folder == month archived).
 

package/scripts/check_public_links.py

@@ -14,7 +14,7 @@ Rules:
   - target stability=experimental  → ERROR. Public surface MUST NOT link
                                      to experimental contracts.
   - target outside docs/contracts/ but referenced for contract-shaped
-    intent (links into agents/contexts/*.md from public files) → ERROR.
+    intent (links into agents/settings/contexts/*.md from public files) → ERROR.
   - target file missing            → ERROR.
   - target file under docs/contracts/ without `stability:` frontmatter
     (except STABILITY.md itself) → ERROR.
@@ -100,7 +100,7 @@ def scan_file(public_file: Path, contracts: dict[Path, str | None]) -> list[Viol
                 continue
             if target.parts[:2] == ("agents", "contexts") and target.suffix == ".md":
                 violations.append(Violation(str(public_file), lineno, href,
-                    "public surface MUST NOT link into agents/contexts/ — move target to docs/contracts/",
+                    "public surface MUST NOT link into agents/settings/contexts/ — move target to docs/contracts/",
                     "error"))
                 continue
             if target.parts[:2] != ("docs", "contracts") or target.suffix != ".md":

package/scripts/check_references.py

@@ -34,10 +34,11 @@ class BrokenRef:
 SCAN_DIRS = [".agent-src", "agents"]
 SKIP_DIRS = [
     "agents/roadmaps/archive",   # archived roadmaps have historical refs
-    "agents/council-sessions",   # per-user audit trail (gitignored), captured provider output
-    "agents/council-responses",  # paired council output (gitignored), captured provider output
-    "agents/council-questions",  # design Q&A trail — forward-refs to planned artifacts
-    "agents/analysis",           # plate-comparison working docs — forward-refs to planned artifacts
+    "agents/runtime/council/sessions",   # per-user audit trail (gitignored), captured provider output
+    "agents/runtime/council/responses",  # paired council output (gitignored), captured provider output
+    "agents/runtime/council/questions",  # design Q&A trail — forward-refs to planned artifacts
+    "agents/evidence/analysis",           # plate-comparison working docs — forward-refs to planned artifacts
+    "agents/runtime",            # volatile / machine-generated artefacts (gitignored)
 ]
 
 # Per-file opt-out marker. When present in the first 10 lines of a .md
@@ -90,14 +91,14 @@ _SKIP_NAMES = {"the", "a", "an", "this", "that", "your", "my", "no", "any", "eac
 
 # Paths that are clearly example/template placeholders (not real references)
 EXAMPLE_PATH_PATTERNS = [
-    re.compile(r"agents/analysis/"),           # project-analyze output template
+    re.compile(r"agents/evidence/analysis/"),           # project-analyze output template
     re.compile(r"agents/roadmaps/template"),   # template reference
     re.compile(r"agents/overrides/"),           # override examples
     re.compile(r"commands/old-cmd"),            # example placeholder
     re.compile(r"agents/README"),               # README reference (may not exist in package)
     re.compile(r"agents/index[\w.-]*\.md"),     # planned auto-generated artefact index (F5)
-    re.compile(r"agents/docs/"),               # project-specific docs (not in package)
-    re.compile(r"agents/contexts/"),           # project-specific contexts (not in package)
+    re.compile(r"agents/reference/docs/"),               # project-specific docs (not in package)
+    re.compile(r"agents/settings/contexts/"),           # project-specific contexts (not in package)
     re.compile(r"agents/gates"),               # project-specific policy docs
     re.compile(r"agents/features/"),           # project-specific feature docs
     re.compile(r"agents/authentication"),       # project-specific auth docs
@@ -324,20 +325,12 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
                         if (prefix / rel).exists():
                             resolved = True
                             break
-                # `agents/state/*.json` are runtime hook state files —
-                # gitignored, written by hooks at session/turn time, never
-                # committed. Prose references to them are descriptive, not
-                # checkable file paths.
-                if not resolved and raw_ref.startswith("agents/state/"):
-                    resolved = True
-                # `agents/.agent-prices.md` is a runtime-bootstrapped pricing
-                # cache — gitignored (.gitignore:/agents/.agent-prices.md),
-                # auto-generated by scripts/ai_council/pricing.py from
-                # _default_prices.py if missing. Same class as agents/state/*
-                # but a single named file, not a directory pattern, so the
-                # carve-out stays narrow.
-                if not resolved and raw_ref == "agents/.agent-prices.md":
-                    resolved = True
+                # `agents/runtime/state/*.json` are runtime hook state files
+                # under the gitignored runtime tree. `agents/runtime/.agent-prices.md`
+                # is the runtime-bootstrapped pricing cache, auto-generated by
+                # scripts/ai_council/pricing.py from _default_prices.py if
+                # missing. The SKIP_DIRS check above already swallows refs
+                # into `agents/runtime/`, so no extra carve-out is needed.
             if not resolved:
                 broken.append(BrokenRef(
                     file=str(filepath), line=i, ref=m.group(1),

package/scripts/check_release_includes_discovery.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Assert dist/discovery/discovery-manifest.json ships with the package.
+
+Phase 5.3 of R3 — wired as a `prepublishOnly` hook in package.json and
+re-used by the publish workflow. Fails loudly when:
+  - dist/discovery/discovery-manifest.json is missing
+  - the file is empty or not valid JSON
+  - the artefacts array is empty
+  - the summary sibling is missing (release tarball ships both)
+
+The intent is that `npm publish` (and `npm pack`) refuse to produce a
+silently-broken artifact where the discovery contract surface
+(ADR-013) is absent from the consumer install path.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+SUMMARY = ROOT / "dist" / "discovery" / "discovery-manifest.summary.md"
+
+
+def _die(msg: str) -> int:
+    sys.stderr.write(f"check-release-discovery: {msg}\n")
+    sys.stderr.write(
+        "  hint: run `python3 scripts/build_discovery_manifest.py --write --strict`"
+        " before `npm pack` / `npm publish`.\n"
+    )
+    return 1
+
+
+def main() -> int:
+    if not MANIFEST.is_file():
+        return _die(f"{MANIFEST.relative_to(ROOT)} is missing.")
+    raw = MANIFEST.read_text(encoding="utf-8").strip()
+    if not raw:
+        return _die(f"{MANIFEST.relative_to(ROOT)} is empty.")
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return _die(f"{MANIFEST.relative_to(ROOT)} is not valid JSON: {exc}.")
+    artefacts = data.get("artefacts")
+    if not isinstance(artefacts, list) or not artefacts:
+        return _die(
+            f"{MANIFEST.relative_to(ROOT)} carries no artefacts — discovery"
+            " scanner produced an empty manifest."
+        )
+    if not SUMMARY.is_file():
+        return _die(f"{SUMMARY.relative_to(ROOT)} is missing.")
+    sys.stdout.write(
+        f"check-release-discovery: OK ({len(artefacts)} artefacts in"
+        f" {MANIFEST.relative_to(ROOT)})\n"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/ci_summary.py

@@ -6,7 +6,7 @@ Consumes JSON files produced by `scripts/runtime_dispatcher.py run
 --output FILE`. Each file is an ExecutionResult dump (see runtime_handler).
 
 Usage:
-    python3 scripts/ci_summary.py --runs agents/reports/runs [--title TITLE]
+    python3 scripts/ci_summary.py --runs agents/runtime/reports/runs [--title TITLE]
 
 Writes to $GITHUB_STEP_SUMMARY if the environment variable is set,
 otherwise prints the markdown to stdout. Missing or empty run
@@ -110,7 +110,7 @@ def write_output(summary: str) -> bool:
 def main() -> int:
     parser = argparse.ArgumentParser(description="Render CI summary from dispatcher runs")
     parser.add_argument(
-        "--runs", type=Path, default=Path("agents/reports/runs"),
+        "--runs", type=Path, default=Path("agents/runtime/reports/runs"),
         help="Directory containing ExecutionResult JSON files",
     )
     parser.add_argument(

package/scripts/ci_time_ratio.py

@@ -17,7 +17,7 @@ Threshold rule (Round-3 Sonnet protocol):
 - Median ratio < 3× across all classes      → structural overhead acceptable
 
 Output: human-readable table on stdout + JSON to
-`agents/reports/ci-time-ratio.json`.
+`agents/runtime/reports/ci-time-ratio.json`.
 
 Usage:
     python3 scripts/ci_time_ratio.py --limit 30

package/scripts/command_suggester/__init__.py

@@ -7,7 +7,7 @@ ranking, suppresses cooled-down suggestions, and renders a numbered
 options block. It never executes a command — the user pick is what
 triggers the standard slash flow.
 
-See `agents/contexts/command-suggestion-eligibility.md` for the
+See `agents/settings/contexts/command-suggestion-eligibility.md` for the
 locked eligibility table and `road-to-context-aware-command-suggestion`
 for the full design.
 """

package/scripts/context_hygiene_hook.py

@@ -6,7 +6,7 @@ freshness threshold, the 3-failure stop, and tool-loop detection. The
 agent's job shrinks from "remember three counters" to "read this file
 before responding".
 
-Output: `agents/state/context-hygiene.json`
+Output: `agents/runtime/state/context-hygiene.json`
   {
     "tool_calls": <int>,                 // running PostToolUse count
     "consecutive_same_tool": <int>,      // includes the latest call
@@ -31,7 +31,7 @@ import sys
 from pathlib import Path
 
 # Re-use the shared atomic-write helper so concerns honour the single
-# `agents/state/.dispatcher.lock` discipline (hook-architecture-v1.md
+# `agents/runtime/state/.dispatcher.lock` discipline (hook-architecture-v1.md
 # § Concurrency, Phase 7.4).
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from hooks.state_io import atomic_write_json  # noqa: E402