@event4u/agent-config 2.25.0 → 3.0.0

package/scripts/audit_likelihood.py

@@ -2,19 +2,19 @@
 """Activation-likelihood heuristic for the Rule-Governance pass
 (Phase 5.3 of road-to-augment-limit-fit).
 
-For every auto-rule from `agents/reports/auto-rules-audit.json`:
+For every auto-rule from `agents/runtime/reports/auto-rules-audit.json`:
 
 1. Build a token set from `description`, `triggers[].keyword`,
    `triggers[].intent`, and the rule name itself.
 2. Index a corpus of skills (`SKILL.md`), contexts
-   (`agents/contexts/**/*.md`), guidelines, and command files.
+   (`agents/settings/contexts/**/*.md`), guidelines, and command files.
 3. Score `corpus_hits = sum(1 for token in tokens if token in corpus)`.
 4. Flag rules with `< 2` corpus hits as "low-likelihood" (their trigger
    surface is so generic that the host LLM is unlikely to find a
    project-local file the rule was written to bridge to).
 
 Result is a JSON dump + Markdown section appended to
-`agents/reports/auto-rules-audit.md`.
+`agents/runtime/reports/auto-rules-audit.md`.
 """
 
 from __future__ import annotations
@@ -34,7 +34,7 @@ LIKELIHOOD_JSON = REPORT_DIR / "auto-rules-likelihood.json"
 CORPUS_GLOBS = [
     ".agent-src.uncompressed/skills/**/SKILL.md",
     ".agent-src.uncompressed/commands/**/*.md",
-    "agents/contexts/**/*.md",
+    "agents/settings/contexts/**/*.md",
     "docs/guidelines/**/*.md",
 ]
 

package/scripts/audit_overlap.py

@@ -2,7 +2,7 @@
 """Trigger-overlap analysis for the Rule-Governance pass (Phase 5.2 of
 road-to-augment-limit-fit).
 
-Reads `agents/reports/auto-rules-audit.json` (produced by
+Reads `agents/runtime/reports/auto-rules-audit.json` (produced by
 `audit_auto_rules.py`) and computes:
 
 - path-prefix Jaccard similarity (per pair of rules);
@@ -10,8 +10,8 @@ Reads `agents/reports/auto-rules-audit.json` (produced by
 
 Pairs scoring `path_jaccard >= 0.5` OR `keyword_overlap >= 0.4` are
 flagged as merge candidates. Output is appended to
-`agents/reports/auto-rules-audit.md` and a structured JSON list is
-written to `agents/reports/auto-rules-overlap.json` for downstream
+`agents/runtime/reports/auto-rules-audit.md` and a structured JSON list is
+written to `agents/runtime/reports/auto-rules-overlap.json` for downstream
 consumers (Phase 5.3 likelihood, 5.4 council walk).
 """
 

package/scripts/audit_user_type_axis.py

@@ -11,7 +11,7 @@ Two checks across `.agent-src.uncompressed/skills/`:
    at least one skill. Unused configs are WARN-only (exit 0): seeding
    future identities ahead of consumption is allowed.
 
-Writes a markdown report to `agents/reports/user-type-axis-audit.md` and
+Writes a markdown report to `agents/runtime/reports/user-type-axis-audit.md` and
 emits a one-line summary to stdout. Stdlib-only — no PyYAML dependency.
 
 Usage:

package/scripts/build_discovery_manifest.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+"""Release-time discovery scanner — produces discovery-manifest.json.
+
+Walks the trusted-root tree (`.agent-src.uncompressed/`), extracts the
+five Phase-4 frontmatter keys (`workspaces`, `packs`, `lifecycle`,
+`trust`, `install`), validates each value against the closed vocabulary
+in `config/discovery/*.yml`, and emits a deterministic JSON manifest
+plus a human-readable Markdown summary.
+
+CLI: see `--help`. Stdlib + pyyaml only at runtime.
+Schema: docs/contracts/discovery-manifest.schema.json
+Roadmap: agents/roadmaps/archive/automated-pack-workspace-and-skill-discovery.md §2 (archived, status: completed)
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Iterable
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from validate_frontmatter import parse_frontmatter  # noqa: E402
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / ".agent-src.uncompressed"
+VOCAB_DIR = ROOT / "config" / "discovery"
+DEFAULT_OUT = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+DEFAULT_SUMMARY = ROOT / "dist" / "discovery" / "discovery-manifest.summary.md"
+TRUST_ROOTS = (".agent-src.uncompressed", ".augment", ".claude", ".agent-src")
+
+_FM_KEYS = ("workspaces", "packs", "lifecycle", "trust", "install")
+_TRUST_REQ = ("level", "confidence", "human_review_required")
+_INSTALL_REQ = ("default", "removable")
+
+
+def _load_yaml(path: Path) -> Any:
+    return yaml.safe_load(path.read_text(encoding="utf-8"))
+
+
+def _vocab() -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, str]]:
+    workspaces = _load_yaml(VOCAB_DIR / "workspaces.yml") or []
+    packs = _load_yaml(VOCAB_DIR / "packs.yml") or []
+    raw_un = _load_yaml(VOCAB_DIR / "unassigned-artefacts.yml") or []
+    overrides = {e["path"]: e["reason"] for e in raw_un} if raw_un else {}
+    return workspaces, packs, overrides
+
+
+def _scanner_version() -> str:
+    h = hashlib.sha256(Path(__file__).read_bytes()).hexdigest()
+    return h[:12]
+
+
+def _iter_artefacts() -> Iterable[tuple[Path, str]]:
+    """Deterministic order: skills → rules → commands → templates."""
+    for p in sorted((SRC / "skills").rglob("SKILL.md")):
+        yield p, "skill"
+    for p in sorted((SRC / "rules").rglob("*.md")):
+        yield p, "rule"
+    for p in sorted((SRC / "commands").rglob("*.md")):
+        yield p, "command"
+    if (SRC / "templates").exists():
+        for p in sorted((SRC / "templates").rglob("*.md")):
+            yield p, "template"
+
+
+def _trusted(path: Path) -> bool:
+    rel = path.relative_to(ROOT).as_posix()
+    return any(rel.startswith(r + "/") for r in TRUST_ROOTS)
+
+
+def _parse(path: Path) -> dict[str, Any] | None:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    fm, _ = parse_frontmatter(text)
+    if not isinstance(fm, dict):
+        return None
+    return fm
+
+
+def _classify(
+    fm: dict[str, Any] | None,
+    ws_ids: set[str],
+    pack_ids: set[str],
+) -> tuple[dict[str, Any] | None, str | None]:
+    """Return (artefact_payload, unassigned_reason). Exactly one is None."""
+    if fm is None:
+        return None, "missing or unparseable frontmatter"
+    missing = [k for k in _FM_KEYS if k not in fm]
+    if missing:
+        return None, f"missing required key(s): {', '.join(missing)}"
+
+    ws = fm["workspaces"]
+    if not isinstance(ws, list) or not ws:
+        return None, "workspaces: must be a non-empty list"
+    bad = [w for w in ws if w not in ws_ids]
+    if bad:
+        return None, f"unknown workspace(s): {', '.join(bad)} (not in vocabulary)"
+
+    pk = fm["packs"]
+    if not isinstance(pk, list) or not pk:
+        return None, "packs: must be a non-empty list"
+    bad = [p for p in pk if p not in pack_ids]
+    if bad:
+        return None, f"unknown pack(s): {', '.join(bad)} (not in vocabulary)"
+
+    lc = fm["lifecycle"]
+    if lc not in ("active", "deprecated", "experimental", "archived"):
+        return None, f"lifecycle: invalid value '{lc}'"
+
+    trust = fm["trust"]
+    if not isinstance(trust, dict) or any(k not in trust for k in _TRUST_REQ):
+        return None, f"trust: missing required key(s) {_TRUST_REQ}"
+    if trust["level"] not in ("core", "professional", "experimental", "advisory", "restricted"):
+        return None, f"trust.level: invalid '{trust['level']}'"
+    if trust["confidence"] not in ("high", "medium", "low"):
+        return None, f"trust.confidence: invalid '{trust['confidence']}'"
+    if not isinstance(trust["human_review_required"], bool):
+        return None, "trust.human_review_required: must be boolean"
+
+    install = fm["install"]
+    if not isinstance(install, dict) or any(k not in install for k in _INSTALL_REQ):
+        return None, f"install: missing required key(s) {_INSTALL_REQ}"
+    if not isinstance(install["default"], bool) or not isinstance(install["removable"], bool):
+        return None, "install.default and install.removable must be boolean"
+
+    return {
+        "workspaces": list(ws),
+        "packs": list(pk),
+        "lifecycle": lc,
+        "trust": {
+            "level": trust["level"],
+            "confidence": trust["confidence"],
+            "human_review_required": trust["human_review_required"],
+        },
+        "install": {"default": install["default"], "removable": install["removable"]},
+    }, None
+
+
+
+def _build(strict: bool) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    workspaces, packs, overrides = _vocab()
+    ws_ids = {w["id"] for w in workspaces}
+    pack_ids = {p["id"] for p in packs}
+
+    artefacts: list[dict[str, Any]] = []
+    unassigned: list[dict[str, Any]] = []
+    pack_counts: dict[str, int] = {pid: 0 for pid in pack_ids}
+
+    documented_unassigned: list[dict[str, Any]] = []
+
+    for path, category in _iter_artefacts():
+        rel = path.relative_to(ROOT).as_posix()
+        if not _trusted(path):
+            unassigned.append({"path": rel, "category": category, "reason": "outside trusted-root allow-list"})
+            continue
+        if rel in overrides:
+            documented_unassigned.append({"path": rel, "category": category, "reason": overrides[rel]})
+            continue
+        fm = _parse(path)
+        payload, reason = _classify(fm, ws_ids, pack_ids)
+        if reason is not None:
+            unassigned.append({"path": rel, "category": category, "reason": reason})
+            continue
+        name = (fm or {}).get("name") if isinstance(fm, dict) else None
+        entry = {"path": rel, "category": category}
+        if isinstance(name, str) and name:
+            entry["name"] = name
+        entry.update(payload or {})
+        artefacts.append(entry)
+        for pid in payload["packs"] if payload else []:
+            pack_counts[pid] = pack_counts.get(pid, 0) + 1
+
+    artefacts.sort(key=lambda e: e["path"])
+    unassigned.sort(key=lambda e: e["path"])
+    documented_unassigned.sort(key=lambda e: e["path"])
+
+    ws_out = [
+        {
+            "id": w["id"],
+            "label": w["label"],
+            "description": w["description"],
+            "default_packs": list(w.get("default_packs") or []),
+            **({"optional_packs": list(w["optional_packs"])} if w.get("optional_packs") else {}),
+        }
+        for w in workspaces
+    ]
+    pk_out = []
+    for p in packs:
+        item = {
+            "id": p["id"],
+            "label": p["label"],
+            "description": p["description"],
+            "workspaces": list(p.get("workspaces") or []),
+            "trust_level_default": p["trust_level_default"],
+            "artefact_count": pack_counts.get(p["id"], 0),
+        }
+        if p.get("requires_hint"):
+            item["requires_hint"] = list(p["requires_hint"])
+        pk_out.append(item)
+
+    if strict and unassigned:
+        raise SystemExit(
+            f"strict mode: {len(unassigned)} unassigned artefact(s); "
+            f"first: {unassigned[0]['path']} — {unassigned[0]['reason']}"
+        )
+
+    manifest = {
+        "version": 1,
+        "generated_at": _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "scanner_version": _scanner_version(),
+        "checksum": "sha256:" + "0" * 64,
+        "workspaces": ws_out,
+        "packs": pk_out,
+        "artefacts": artefacts,
+        "unassigned": unassigned,
+        "documented_unassigned": documented_unassigned,
+    }
+    return manifest, unassigned
+
+
+def _serialize(manifest: dict[str, Any]) -> str:
+    """Deterministic JSON: sorted keys, 2-space indent, trailing newline."""
+    return json.dumps(manifest, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+
+
+def _finalise_checksum(manifest: dict[str, Any]) -> None:
+    # Checksum covers structural content only — `generated_at` is wall-clock
+    # and intentionally excluded so the hash stays byte-stable across runs.
+    generated_at = manifest.get("generated_at")
+    manifest["checksum"] = "sha256:" + "0" * 64
+    manifest["generated_at"] = "<normalised>"
+    raw = _serialize(manifest).encode("utf-8")
+    digest = hashlib.sha256(raw).hexdigest()
+    manifest["generated_at"] = generated_at
+    manifest["checksum"] = f"sha256:{digest}"
+
+
+def _summary(manifest: dict[str, Any]) -> str:
+    lines = ["# Discovery Manifest — Summary", ""]
+    lines.append(f"- Generated: `{manifest['generated_at']}`")
+    lines.append(f"- Scanner: `{manifest['scanner_version']}`")
+    lines.append(f"- Artefacts: **{len(manifest['artefacts'])}**")
+    lines.append(f"- Unassigned: **{len(manifest['unassigned'])}**")
+    lines.append("")
+    pack_by_id = {p["id"]: p for p in manifest["packs"]}
+    for w in manifest["workspaces"]:
+        lines.append(f"## `{w['id']}` — {w['label']}")
+        lines.append("")
+        lines.append(f"> {w['description']}")
+        lines.append("")
+        lines.append("| Pack | Artefacts |")
+        lines.append("|---|---|")
+        for pid in list(w.get("default_packs", [])) + list(w.get("optional_packs", [])):
+            p = pack_by_id.get(pid)
+            if p:
+                lines.append(f"| `{pid}` — {p['label']} | {p['artefact_count']} |")
+        lines.append("")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--write", action="store_true")
+    parser.add_argument("--out", type=Path, default=DEFAULT_OUT)
+    parser.add_argument("--summary", type=Path, default=DEFAULT_SUMMARY)
+    parser.add_argument("--strict", action="store_true")
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args(argv)
+
+    # Phase 4.4 gate: in CI, behave as if --strict were passed. Local
+    # invocations stay permissive unless --strict is explicit.
+    strict = args.strict or os.environ.get("CI", "").lower() in ("true", "1")
+    manifest, unassigned = _build(strict=strict)
+    _finalise_checksum(manifest)
+    body = _serialize(manifest)
+
+    if args.write:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(body, encoding="utf-8")
+        args.summary.write_text(_summary(manifest), encoding="utf-8")
+        # Sidecar SHA-256 of the on-disk manifest bytes for tamper detection
+        # by downstream consumers (security-engineer council fold-in, R3 Phase 7).
+        sidecar = args.out.with_suffix(args.out.suffix + ".sha256")
+        file_digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
+        sidecar.write_text(f"{file_digest}  {args.out.name}\n", encoding="utf-8")
+        if not args.quiet:
+            print(
+                f"wrote {args.out.relative_to(ROOT)} "
+                f"({len(manifest['artefacts'])} artefacts, {len(unassigned)} unassigned)"
+            )
+    else:
+        sys.stdout.write(body)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/build_linear_digest.py

@@ -93,7 +93,6 @@ WORKSPACE: list[RuleEntry] = [
 TEAM: list[RuleEntry] = [
     RuleEntry("docker-commands"),
     RuleEntry("laravel-translations"),
-    RuleEntry("e2e-testing"),
     RuleEntry("php-coding"),
 ]
 

package/scripts/build_mcp_registry_manifest.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Build `dist/mcp/registry-manifest.json` + the two rendered payloads.
+
+Reads three on-disk sources:
+  * `package.json`                          — name, version, description, homepage, repository
+  * `.github/topics.yml`                    — topics list (for registries that accept tags)
+  * `workers/mcp/content.json`              — `tool_catalog` (tools_count, install_hint_stdio)
+  * `dist/discovery/discovery-manifest.json` — artefact_count + scanner_version (HARD prereq per AI-Council R5)
+
+Emits:
+  * `dist/mcp/registry-manifest.json`            — source-of-truth manifest
+  * `dist/mcp/awesome-mcp-servers.row.md`        — single Markdown row
+  * `dist/mcp/mcp-cloudflare-catalogue.json`     — single JSON catalogue entry
+
+Lifecycle state (`status`, `submitted_at`, `pr_url`, `last_verified`) is
+**preserved** from the previous manifest. First-time generation seeds
+`status=pending` and nulls the rest. Status transitions are hand-edits
+under maintainer review — see `docs/distribution/mcp-submission-checklist.md`.
+
+CLI: `--write` / `--strict` / `--quiet` — matches the discovery scanner shape.
+
+Schema: `docs/contracts/mcp-registry-manifest.schema.json`
+Roadmap: agents/roadmaps/strategic-visibility-mcp-topics-positioning.md Phase 2.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+PKG_FILE = ROOT / "package.json"
+TOPICS_FILE = ROOT / ".github" / "topics.yml"
+CONTENT_FILE = ROOT / "workers" / "mcp" / "content.json"
+DISCOVERY_FILE = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+OUT_DIR = ROOT / "dist" / "mcp"
+OUT_MANIFEST = OUT_DIR / "registry-manifest.json"
+OUT_ROW_MD = OUT_DIR / "awesome-mcp-servers.row.md"
+OUT_CF_JSON = OUT_DIR / "mcp-cloudflare-catalogue.json"
+
+REGISTRIES_SEED = [
+    {
+        "id": "awesome-mcp-servers",
+        "label": "punkpeye/awesome-mcp-servers",
+        "listing_format": "markdown-row",
+        "submission_url": "https://github.com/punkpeye/awesome-mcp-servers",
+        "rendered_payload": "dist/mcp/awesome-mcp-servers.row.md",
+    },
+    {
+        "id": "mcp-cloudflare-catalogue",
+        "label": "Cloudflare MCP catalogue",
+        "listing_format": "json-entry",
+        "submission_url": "https://github.com/cloudflare/mcp-server-cloudflare",
+        "rendered_payload": "dist/mcp/mcp-cloudflare-catalogue.json",
+    },
+]
+
+
+def _repo_url(pkg: dict[str, Any]) -> str:
+    raw = (pkg.get("repository") or {}).get("url") or ""
+    return re.sub(r"^git\+|\.git$", "", raw)
+
+
+def _build(now_utc: _dt.datetime) -> dict[str, Any]:
+    pkg = json.loads(PKG_FILE.read_text(encoding="utf-8"))
+    topics_doc = yaml.safe_load(TOPICS_FILE.read_text(encoding="utf-8")) or {}
+    content = json.loads(CONTENT_FILE.read_text(encoding="utf-8"))
+    if not DISCOVERY_FILE.exists():
+        sys.exit(
+            "ERROR: dist/discovery/discovery-manifest.json missing. R3 (discovery) "
+            "is a hard prerequisite per the AI-Council external review. "
+            "Run `npm run build:discovery` first."
+        )
+    discovery = json.loads(DISCOVERY_FILE.read_text(encoding="utf-8"))
+
+    tc = content["tool_catalog"]
+    prior = json.loads(OUT_MANIFEST.read_text(encoding="utf-8")) if OUT_MANIFEST.exists() else {}
+    prior_reg = {r["id"]: r for r in (prior.get("registries") or [])}
+
+    registries: list[dict[str, Any]] = []
+    for seed in REGISTRIES_SEED:
+        prev = prior_reg.get(seed["id"], {})
+        registries.append({
+            **seed,
+            "status": prev.get("status", "pending"),
+            "submitted_at": prev.get("submitted_at"),
+            "pr_url": prev.get("pr_url"),
+            "last_verified": prev.get("last_verified"),
+        })
+
+    return {
+        "version": 1,
+        "generated_at": now_utc.strftime("%Y-%m-%d"),
+        "package": {
+            "name": pkg["name"],
+            "version": pkg["version"],
+            "description": pkg["description"],
+            "homepage": pkg["homepage"],
+            "repository": _repo_url(pkg),
+        },
+        "server": {
+            "name": "agent-config-mcp",
+            "transports": ["stdio", "worker"],
+            "tools_count": len(tc["tools"]),
+            "install_hint_stdio": tc["install_hint_stdio"],
+        },
+        "topics": sorted(topics_doc.get("topics") or []),
+        "discovery": {
+            "artefact_count": len(discovery["artefacts"]),
+            "scanner_version": discovery["scanner_version"],
+        },
+        "registries": registries,
+    }
+
+
+def _render_row_md(m: dict[str, Any]) -> str:
+    pkg = m["package"]
+    srv = m["server"]
+    transports = ", ".join(srv["transports"])
+    return (
+        f"| [{pkg['name']}]({pkg['homepage']}) "
+        f"| {pkg['description']} "
+        f"| {srv['tools_count']} tools ({transports}) "
+        f"| `{srv['install_hint_stdio']}` |\n"
+    )
+
+
+def _render_cf_json(m: dict[str, Any]) -> str:
+    pkg = m["package"]
+    srv = m["server"]
+    payload = {
+        "name": srv["name"],
+        "description": pkg["description"],
+        "homepage": pkg["homepage"],
+        "repository": pkg["repository"],
+        "transports": srv["transports"],
+        "tools_count": srv["tools_count"],
+        "install_hint_stdio": srv["install_hint_stdio"],
+        "topics": m["topics"],
+    }
+    return json.dumps(payload, indent=2, sort_keys=True) + "\n"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--write", action="store_true", help="write outputs to disk (default: print to stdout)")
+    ap.add_argument("--strict", action="store_true", help="exit 2 if on-disk outputs would change")
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+
+    now_utc = _dt.datetime.now(_dt.timezone.utc)
+    manifest = _build(now_utc)
+    manifest_text = json.dumps(manifest, indent=2, sort_keys=True) + "\n"
+    row_md = _render_row_md(manifest)
+    cf_json = _render_cf_json(manifest)
+
+    outputs = [(OUT_MANIFEST, manifest_text), (OUT_ROW_MD, row_md), (OUT_CF_JSON, cf_json)]
+    changed = [p for p, t in outputs if not p.exists() or p.read_text(encoding="utf-8") != t]
+
+    if args.write:
+        OUT_DIR.mkdir(parents=True, exist_ok=True)
+        for p, t in outputs:
+            p.write_text(t, encoding="utf-8")
+        if not args.quiet:
+            verb = "wrote" if changed else "unchanged"
+            print(f"\u2705  {verb} {len(outputs)} file(s) under dist/mcp/")
+    else:
+        if not args.quiet:
+            print(manifest_text, end="")
+
+    return 2 if (args.strict and changed and not args.write) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/build_rule_trigger_matrix.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Build agents/contexts/rule-trigger-matrix.md.
+"""Build agents/settings/contexts/rule-trigger-matrix.md.
 
 Emits a single matrix mapping every rule in `.agent-src.uncompressed/rules/`
 to its trigger event, observability, enforcement surface, hook-cost
@@ -113,7 +113,7 @@ add("commit-conventions.md", "commit message draft", "hook", "output",
 add("docs-sync.md", "file-edit on .augment/{skills,rules,commands}/**", "hook",
     "tool-call", "medium", "2a",
     notes="Detect add/rename/delete; remind to update count + cross-refs")
-add("agent-docs.md", "file-edit on agents/docs/, AGENTS.md", "hook",
+add("agent-docs.md", "file-edit on agents/reference/docs/, AGENTS.md", "hook",
     "tool-call", "medium", "2a", notes="Path-pattern based marker")
 add("upstream-proposal.md", "skill/rule create event", "hook", "output",
     "medium", "2a", notes="Marker after new artifact lands")

package/scripts/capture_showcase_session.py

@@ -11,7 +11,7 @@ Two subcommands:
             task_class, metrics).
 
   metrics   Compute one or all of the four outcome metrics defined in
-            `agents/contexts/outcome-baseline.md` from a captured session
+            `agents/settings/contexts/outcome-baseline.md` from a captured session
             file. Output as text table or JSON.
 
 The four metrics:

package/scripts/chat_history.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Persistent chat-history log for crash recovery.
 
-Maintains `agents/.agent-chat-history` — a JSONL file whose
+Maintains `agents/runtime/.agent-chat-history` — a JSONL file whose
 first line is a header (schema version, started timestamp, cadence
 frequency) and whose remaining lines are append-only entries (user
 messages, phases, tool calls, questions, answers, decisions, commits).
@@ -12,7 +12,7 @@ sessions coexist in one file; each entry self-identifies. No ownership
 layer, no sidecar, no auto-adopt — every hook invocation simply appends
 with its own session tag.
 
-File path defaults to `agents/.agent-chat-history` (relative to CWD) and
+File path defaults to `agents/runtime/.agent-chat-history` (relative to CWD) and
 can be overridden via `$AGENT_CHAT_HISTORY_FILE` (used by tests).
 
 Usage:
@@ -42,7 +42,7 @@ from collections import Counter, deque
 from pathlib import Path
 from typing import Any
 
-DEFAULT_FILE = "agents/.agent-chat-history"
+DEFAULT_FILE = "agents/runtime/.agent-chat-history"
 DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
 SCHEMA_VERSION = 4
 DEFAULT_MAX_SESSIONS = 5
@@ -691,7 +691,7 @@ CADENCE_EVENTS = {
 # internal VALID_HOOK_EVENTS. Used by hook_dispatch() to translate
 # stdin JSON payloads coming from Claude Code, Augment Code, Cursor,
 # Cline, Windsurf, and Gemini CLI into a unified entry-point. Sourced
-# from agents/contexts/chat-history-platform-hooks.md.
+# from agents/settings/contexts/chat-history-platform-hooks.md.
 PLATFORM_EVENT_MAP: dict[str, dict[str, str]] = {
     "claude": {
         "SessionStart": "session_start",
@@ -716,7 +716,7 @@ PLATFORM_EVENT_MAP: dict[str, dict[str, str]] = {
     # with `--setting-sources user`. Until those are resolved, the
     # mapping below is dispatcher-ready but the lifecycle events do
     # not actually fire from Cowork. See
-    # `agents/contexts/chat-history-platform-hooks.md` § Cowork.
+    # `agents/settings/contexts/chat-history-platform-hooks.md` § Cowork.
     "cowork": {
         "SessionStart": "session_start",
         "UserPromptSubmit": "user_prompt",

package/scripts/check_always_budget.py

@@ -56,9 +56,14 @@ CONCENTRATION_TOP3_PCT = 0.30
 # the measured extended-size ceiling at the day road-to-path-fixes was
 # closed; growth above the ceiling regresses CI. Future kernel-aware
 # trimming work retires entries here.
+# R3 Phase 4 mass-annotation added 12 lines of ADR-013 discovery
+# frontmatter (workspaces / packs / lifecycle / trust / install — 189
+# chars) to every always-rule. Both ceilings below were re-baselined
+# +189 to absorb that frontmatter-only growth, mirroring the Phase 2
+# feedback-consolidation `tier: "safety-floor"` precedent (+21).
 KNOWN_CONCENTRATION_BREACHES: dict[str, int] = {
-    "language-and-tone.md": 3_985,
-    "no-cheap-questions.md": 3_530,
+    "language-and-tone.md": 4_174,
+    "no-cheap-questions.md": 3_719,
 }
 # Top-3 non-floor concentration ceiling — same rationale as the
 # per-rule allowlist above. The current top-3 sum (language-and-tone +