@event4u/agent-config 2.26.0 → 3.1.0

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.
@@ -39,26 +39,48 @@ 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/council-(?:questions|responses|sessions)/"
+    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.
-SCAN_ROOTS = (
-    ".agent-src.uncompressed",
+#
+# Source roots (legacy `.agent-src.uncompressed/` and every
+# `packages/*/.agent-src.uncompressed/`) are discovered at runtime via
+# `artefact_roots()` so the linter follows the monorepo physical layout.
+FIXED_SCAN_ROOTS = (
     "agents/roadmaps",
-    "agents/contexts",
-    "agents/docs",
+    "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
@@ -68,7 +90,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 +109,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,23 +119,40 @@ 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$"),
     ),
 )
 
 
 def _is_allowlisted(rel: str) -> bool:
+    """Match a repo-relative POSIX path against the allowlist.
+
+    Allowlist prefixes are written against the legacy
+    ``.agent-src.uncompressed/`` layout. A physical hit under
+    ``packages/*/.agent-src.uncompressed/`` is normalised to the same
+    logical path before matching so entries keep covering relocated files.
+    """
     if rel in ALLOWLIST_FILES:
         return True
-    return any(rel.startswith(prefix) for prefix in ALLOWLIST_PREFIXES)
+    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.uncompressed/"
 
 
 def _is_structurally_allowed(source_rel: str, target_capture: str) -> bool:
@@ -156,7 +195,7 @@ def _iter_files(roots: Iterable[str]) -> Iterable[Path]:
 
 def main() -> int:
     violations: list[tuple[Path, int, str]] = []
-    for path in _iter_files(SCAN_ROOTS):
+    for path in _iter_files(_scan_roots()):
         rel = path.as_posix()
         if _is_allowlisted(rel):
             continue

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_overlay_cascade_subdirs.py

@@ -30,10 +30,14 @@ from scripts._lib.agents_overlay import (  # noqa: E402
 
 DOCS_PATH = REPO_ROOT / "docs" / "customization.md"
 
-# Match `agents/<kind>/` in the first column of the overlay table, plus
-# the ✅/❌ markers in columns 2 and 3.
+# Match `agents/<...>/<kind>/` in the first column of the overlay
+# table, plus the ✅/❌ markers in columns 2 and 3. Captures only the
+# **final** path segment as the kind, so both flat (`agents/overrides/`)
+# and nested (`agents/settings/contexts/`) rows resolve to the bare
+# kind name that ``CASCADE_ELIGIBLE_KINDS`` carries.
 ROW_RE = re.compile(
-    r"^\|\s*`agents/([a-z][a-z0-9_-]*)/`\s*\|\s*(✅|❌)[^|]*\|\s*(✅|❌)[^|]*\|",
+    r"^\|\s*`agents/(?:[a-z][a-z0-9_-]*/)*([a-z][a-z0-9_-]*)/`\s*\|"
+    r"\s*(✅|❌)[^|]*\|\s*(✅|❌)[^|]*\|",
 )
 
 

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
@@ -80,8 +81,10 @@ SKILL_REF_PATTERN = re.compile(r'`([\w-]+)`\s+skill')
 RULE_REF_PATTERN = re.compile(r'`([\w-]+)`\s+rule')
 
 # Unchecked TODO items (roadmap checkboxes) legitimately reference files
-# and artifacts that do not exist yet. Skip these lines.
-UNCHECKED_TODO_PATTERN = re.compile(r'^\s*[-*+]\s+\[ \]\s')
+# and artifacts that do not exist yet. Skip these lines. `[~]` marks
+# deferred work — same semantics as `[ ]` for reference resolution
+# (forward-looking path, will materialize when the step ships).
+UNCHECKED_TODO_PATTERN = re.compile(r'^\s*[-*+]\s+\[[ ~]\]\s')
 _SKIP_NAMES = {"the", "a", "an", "this", "that", "your", "my", "no", "any", "each", "one",
                "always", "auto", "fail", "vue", "guidelines", "naming",
                "orderBy", "no-commit", "skill-linter", "skill-validator",
@@ -90,14 +93,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
@@ -109,6 +112,7 @@ EXAMPLE_PATH_PATTERNS = [
     re.compile(r"agents/learnings/"),           # consumer-project learning notes
     re.compile(r"agents/proposals/"),           # consumer-project self-improvement proposals
     re.compile(r"agents/drafts/"),              # consumer-project artefact drafts
+    re.compile(r"agents/\.event4u-bridge\.yml"),  # consumer-project bridge marker (ADR-020)
     re.compile(r"guidelines/php-"),             # flattened override naming convention
     re.compile(r"rules/no-commit"),            # example rule in commands
     re.compile(r"skills/[\w-]+\.md"),          # short skill refs in examples (not SKILL.md path)
@@ -324,20 +328,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/check_reply_consistency.py

@@ -21,6 +21,10 @@ import re
 import sys
 from pathlib import Path
 
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
 QUIET = "--quiet" in sys.argv
 
 OPTION_LINE_RE = re.compile(r"^\s*>?\s*(\d+)\.\s+\S")
@@ -95,23 +99,42 @@ def validate(text: str, strict: bool = False) -> tuple[int, str]:
 
 
 def cmd_scan_dir(root: Path) -> int:
+    # If the requested root is the legacy ".agent-src.uncompressed" and it
+    # no longer exists (post-monorepo-move), fall back to artefact_roots()
+    # so every packages/*/.agent-src.uncompressed/ is scanned.
     if not root.is_dir():
-        print(f"error: not a directory: {root}", file=sys.stderr)
-        return 9
+        legacy = ROOT / ".agent-src.uncompressed"
+        if root.resolve() == legacy.resolve():
+            roots = artefact_roots()
+            if not roots:
+                print("error: no artefact roots found (legacy or packages/*)", file=sys.stderr)
+                return 9
+        else:
+            print(f"error: not a directory: {root}", file=sys.stderr)
+            return 9
+    else:
+        roots = [root]
     violations: list[tuple[Path, int, str]] = []
-    for md in sorted(root.rglob("*.md")):
-        text = md.read_text(encoding="utf-8")
-        for idx, raw in enumerate(text.splitlines(), start=1):
-            stripped = _strip_codespans(raw)
-            if OPTION_LINE_RE.match(stripped) and TAG_RE.search(stripped):
-                violations.append((md, idx, raw.strip()))
+    for r in roots:
+        for md in sorted(r.rglob("*.md")):
+            text = md.read_text(encoding="utf-8")
+            for idx, raw in enumerate(text.splitlines(), start=1):
+                stripped = _strip_codespans(raw)
+                if OPTION_LINE_RE.match(stripped) and TAG_RE.search(stripped):
+                    violations.append((md, idx, raw.strip()))
     if violations:
         for path, line, snippet in violations:
             print(f"  🔴 {path}:{line} — inline-tag — {snippet}", file=sys.stderr)
         print(f"\n❌  {len(violations)} legacy-pattern violation(s)", file=sys.stderr)
         return 6
     if not QUIET:
-        print(f"✅  No legacy (recommended) tags found under {root}")
+        def _rel(p: Path) -> str:
+            try:
+                return p.relative_to(ROOT).as_posix()
+            except ValueError:
+                return p.as_posix()
+        scanned = ", ".join(_rel(r) for r in roots)
+        print(f"✅  No legacy (recommended) tags found under {scanned}")
     return 0
 
 

package/scripts/check_template_pin_drift.py

@@ -24,12 +24,26 @@ import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_logical  # noqa: E402
 
 PACKAGE_JSON = REPO_ROOT / "package.json"
-TEMPLATE_FILES = (
-    REPO_ROOT / ".agent-src.uncompressed" / "templates" / "agents" / "agent-project-settings.example.yml",
-    REPO_ROOT / ".agent-src" / "templates" / "agents" / "agent-project-settings.example.yml",
-)
+
+# Source-of-truth template lives under whichever artefact root owns it
+# (legacy .agent-src.uncompressed/ pre-move, packages/*/.agent-src.uncompressed/
+# post-ADR-017). Compressed twin always lands at the flat .agent-src/ surface.
+_TEMPLATE_LOGICAL = "templates/agents/agent-project-settings.example.yml"
+
+
+def _template_files() -> tuple[Path, ...]:
+    src = resolve_logical(_TEMPLATE_LOGICAL)
+    files: list[Path] = []
+    if src is not None:
+        files.append(src)
+    else:
+        files.append(REPO_ROOT / ".agent-src.uncompressed" / _TEMPLATE_LOGICAL)
+    files.append(REPO_ROOT / ".agent-src" / _TEMPLATE_LOGICAL)
+    return tuple(files)
 PIN_LINE_RE = re.compile(r"^\s*agent_config_version\s*:\s*\"?([^\"\s#]*)\"?")
 
 
@@ -70,12 +84,15 @@ def main(argv: list[str] | None = None) -> int:
         return 1
 
     failures: list[str] = []
-    for template in TEMPLATE_FILES:
+    for template in _template_files():
+        try:
+            rel = template.relative_to(REPO_ROOT)
+        except ValueError:
+            rel = template
         if not template.is_file():
-            failures.append(f"missing template file: {template.relative_to(REPO_ROOT)}")
+            failures.append(f"missing template file: {rel}")
             continue
         pin = _read_template_pin(template)
-        rel = template.relative_to(REPO_ROOT)
         if pin is None:
             failures.append(f"{rel}: no `agent_config_version:` line found")
             continue

package/scripts/check_token_optimizer_freshness.py

@@ -21,7 +21,16 @@ import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-SKILL = REPO_ROOT / ".agent-src.uncompressed" / "skills" / "token-optimizer" / "SKILL.md"
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_logical  # noqa: E402
+
+# Post-ADR-017 the source-of-truth lives under whichever package owns
+# the skill; resolve_logical() walks every artefact root.
+SKILL = resolve_logical("skills/token-optimizer/SKILL.md") or (
+    REPO_ROOT / ".agent-src.uncompressed" / "skills" / "token-optimizer" / "SKILL.md"
+)
+
+from _lib.agent_src import strip_source_prefix  # noqa: E402
 
 # Catalog row pattern: | name | path | keywords | description |
 ROW_RE = re.compile(
@@ -74,8 +83,14 @@ def resolve(path: str) -> Path | None:
         return None
     cleaned = path.strip().lstrip("`").rstrip("`")
     cleaned = cleaned.split(")")[0].lstrip("[(")
-    candidate = (REPO_ROOT / cleaned).resolve()
-    return candidate
+    # Catalog rows still cite the legacy .agent-src.uncompressed/ prefix
+    # for compactness; resolve those across every packages/* root.
+    logical = strip_source_prefix(cleaned)
+    if logical is not None:
+        hit = resolve_logical(logical)
+        if hit is not None:
+            return hit
+    return (REPO_ROOT / cleaned).resolve()
 
 
 def check_row(row: dict[str, str]) -> list[str]:

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.
 """