@event4u/agent-config 2.26.0 → 3.0.0

package/scripts/prepack-check.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * prepack-check.mjs — guard the published artifact.
+ *
+ * Runs during `npm pack` and `npm publish`. Asserts the compiled TS
+ * CLI binary exists, is executable, and carries the Node shebang
+ * before the tarball is built. Otherwise a silently-broken `dist/`
+ * ships and every `npx @event4u/agent-config` greets the consumer
+ * with a cryptic `Cannot find module` panic.
+ *
+ * Folded from external council pass 2026-05-18 (Phase 1.3 acceptance).
+ *
+ * Skip with PREPACK_SKIP_BUILD_CHECK=1 only for local `npm pack` dry-runs
+ * that intentionally test the failure mode.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { argv, env, exit } from 'node:process';
+
+const BIN = resolve('dist/cli/agent-config.js');
+const SHEBANG = '#!/usr/bin/env node';
+
+function die(msg) {
+    process.stderr.write(`prepack-check: ${msg}\n`);
+    exit(1);
+}
+
+if (env.PREPACK_SKIP_BUILD_CHECK === '1') {
+    process.stderr.write('prepack-check: skipped (PREPACK_SKIP_BUILD_CHECK=1)\n');
+    exit(0);
+}
+
+let st;
+try {
+    st = statSync(BIN);
+} catch {
+    die(`compiled CLI binary missing at ${BIN}. Run \`npm run build\` before \`npm pack\`.`);
+}
+
+if (!st.isFile()) {
+    die(`${BIN} is not a regular file.`);
+}
+
+// Executable bit check (skip on Windows where mode bits are unreliable).
+if (process.platform !== 'win32') {
+    // 0o111 = any executable bit set
+    if ((st.mode & 0o111) === 0) {
+        die(`${BIN} is not executable. Build step must chmod +x the bin entry.`);
+    }
+}
+
+const head = readFileSync(BIN, 'utf8').slice(0, SHEBANG.length);
+if (head !== SHEBANG) {
+    die(`${BIN} missing Node shebang. Expected "${SHEBANG}" as first line.`);
+}
+
+process.stderr.write(`prepack-check: ${BIN} OK\n`);
+
+// Optional: invoked with --verbose dumps the size for tarball-budget bookkeeping.
+if (argv.includes('--verbose')) {
+    process.stderr.write(`prepack-check: size=${st.size} bytes\n`);
+}

package/scripts/probe_projection_fidelity.py

@@ -5,7 +5,7 @@ Reads tests/fixtures/projection_fidelity/fixtures.yml, walks the
 projected trees (.augment/, .claude/, .cursor/, .clinerules/,
 .windsurfrules, .windsurf/), and records pass/fail/partial per check.
 
-Output: agents/reports/projection-fidelity.json + stdout summary.
+Output: agents/runtime/reports/projection-fidelity.json + stdout summary.
 
 Pure stdlib (PyYAML reuse from scripts/_lib if installed; otherwise
 inline minimal YAML loader for the fixture's restricted shape).
@@ -172,7 +172,7 @@ def check_entry(entry: dict) -> dict:
 def main() -> int:
     ap = argparse.ArgumentParser()
     ap.add_argument("--fixture", default="tests/fixtures/projection_fidelity/fixtures.yml")
-    ap.add_argument("--report", default="agents/reports/projection-fidelity.json")
+    ap.add_argument("--report", default="agents/runtime/reports/projection-fidelity.json")
     args = ap.parse_args()
 
     fixture = yaml.safe_load((ROOT / args.fixture).read_text(encoding="utf-8"))

package/scripts/refine_ticket_detect.py

@@ -94,7 +94,7 @@ class RepoContext:
 
     Feeds the skill's Top-5 risks with project-specific vocabulary —
     recent branch names (naming-convention signal), recent commit
-    subjects (active modules signal), and on-disk `agents/contexts/`
+    subjects (active modules signal), and on-disk `agents/settings/contexts/`
     documents (domain-vocabulary signal).
 
     Empty when `repo_aware=False` — the skill still produces the same

package/scripts/schemas/command.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/command.schema.json",
   "title": "Command frontmatter",
-  "$comment": "Source: agents/docs/frontmatter-contract.md#commands. `description` is required at schema level because 66/67 commands declare it — the one exception is a known gap, not a supported shape.",
+  "$comment": "Source: agents/reference/docs/frontmatter-contract.md#commands. `description` is required at schema level because 66/67 commands declare it — the one exception is a known gap, not a supported shape.",
   "type": "object",
   "additionalProperties": false,
   "required": ["name", "description", "disable-model-invocation"],
@@ -117,6 +117,46 @@
           "description": "Optional per-command override of the global cooldown duration (e.g. '10m'). Defaults to settings."
         }
       }
+    },
+    "workspaces": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "description": "ADR-013 workspace ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/workspaces.yml."
+    },
+    "packs": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "description": "ADR-013 pack ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/packs.yml."
+    },
+    "lifecycle": {
+      "type": "string",
+      "enum": ["active", "deprecated", "experimental", "archived"],
+      "description": "ADR-013 lifecycle state."
+    },
+    "trust": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "confidence", "human_review_required"],
+      "properties": {
+        "level": {"type": "string", "enum": ["core", "professional", "experimental", "advisory", "restricted"]},
+        "confidence": {"type": "string", "enum": ["high", "medium", "low"]},
+        "human_review_required": {"type": "boolean"}
+      },
+      "description": "ADR-013 trust block. Vocabulary mirrored by scripts/lint_artefact_frontmatter.py."
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["default", "removable"],
+      "properties": {
+        "default": {"type": "boolean"},
+        "removable": {"type": "boolean"}
+      },
+      "description": "ADR-013 install hints (default-on at consumer install; user-removable)."
     }
   }
 }

package/scripts/schemas/persona.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/persona.schema.json",
   "title": "Persona frontmatter",
-  "$comment": "Source: agents/docs/frontmatter-contract.md#personas. `mode` enum mirrors the values declared in personas/*.md plus the additional `incident` value from templates/persona.md.",
+  "$comment": "Source: agents/reference/docs/frontmatter-contract.md#personas. `mode` enum mirrors the values declared in personas/*.md plus the additional `incident` value from templates/persona.md.",
   "type": "object",
   "additionalProperties": false,
   "required": ["id", "role", "description", "tier", "mode", "version", "source"],

package/scripts/schemas/rule.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/rule.schema.json",
   "title": "Rule frontmatter",
-  "$comment": "Source: agents/docs/frontmatter-contract.md#rules. `type` is authoritative; `alwaysApply` is a Cursor/Cline sidecar and accepted but not enforced.",
+  "$comment": "Source: agents/reference/docs/frontmatter-contract.md#rules. `type` is authoritative; `alwaysApply` is a Cursor/Cline sidecar and accepted but not enforced.",
   "type": "object",
   "additionalProperties": false,
   "required": ["type", "source", "description"],
@@ -29,8 +29,8 @@
       "type": "array",
       "items": {
         "type": "string",
-        "pattern": "^((\\.\\./)*contexts/|agents/contexts/|\\.agent-src/contexts/)[^\\s]+\\.md$",
-        "description": "Logical name (preferred — `contexts/<area>/<file>.md`) or project-local (`agents/contexts/<file>.md`). The `.agent-src.uncompressed/` prefix is rejected by the regex; the rewriter (`scripts/compress.py::_rewrite_paths`) resolves logical names at compress time. Rewritten relative forms (`../contexts/...`, `../../contexts/...`) are accepted so the linter passes on the compressed mirror in CI."
+        "pattern": "^((\\.\\./)*contexts/|agents/settings/contexts/|\\.agent-src/contexts/)[^\\s]+\\.md$",
+        "description": "Logical name (preferred — `contexts/<area>/<file>.md`) or project-local (`agents/settings/contexts/<file>.md`). The `.agent-src.uncompressed/` prefix is rejected by the regex; the rewriter (`scripts/compress.py::_rewrite_paths`) resolves logical names at compress time. Rewritten relative forms (`../contexts/...`, `../../contexts/...`) are accepted so the linter passes on the compressed mirror in CI."
       },
       "description": "Lazy on-demand context references. Use logical names rooted at the source (e.g. `contexts/execution/foo.md`); the `.agent-src.uncompressed/` prefix is forbidden by the regex (road-to-path-fixes.md P5.3). Path rules and budget caps enforced by scripts/lint_load_context.py. Contract: docs/contracts/load-context-schema.md."
     },
@@ -38,7 +38,7 @@
       "type": "array",
       "items": {
         "type": "string",
-        "pattern": "^((\\.\\./)*contexts/|agents/contexts/|\\.agent-src/contexts/)[^\\s]+\\.md$",
+        "pattern": "^((\\.\\./)*contexts/|agents/settings/contexts/|\\.agent-src/contexts/)[^\\s]+\\.md$",
         "description": "Same logical-name rule as `load_context`."
       },
       "description": "Eager auto-loaded context references. Same logical-name rule as `load_context`. Counts against the per-rule char budget; enforced by scripts/lint_load_context.py."
@@ -98,6 +98,46 @@
         }
       },
       "description": "Per-rule allowlist consumed by the post-compression validator (scripts/check_compressed_paths.py). Rules that document forbidden path substrings as their subject matter (e.g. augment-portability, no-roadmap-references) declare the literal strings here so the gate does not flag itself. road-to-path-fixes.md P5.1."
+    },
+    "workspaces": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "description": "ADR-013 workspace ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/workspaces.yml."
+    },
+    "packs": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "description": "ADR-013 pack ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/packs.yml."
+    },
+    "lifecycle": {
+      "type": "string",
+      "enum": ["active", "deprecated", "experimental", "archived"],
+      "description": "ADR-013 lifecycle state."
+    },
+    "trust": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "confidence", "human_review_required"],
+      "properties": {
+        "level": {"type": "string", "enum": ["core", "professional", "experimental", "advisory", "restricted"]},
+        "confidence": {"type": "string", "enum": ["high", "medium", "low"]},
+        "human_review_required": {"type": "boolean"}
+      },
+      "description": "ADR-013 trust block. Vocabulary mirrored by scripts/lint_artefact_frontmatter.py."
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["default", "removable"],
+      "properties": {
+        "default": {"type": "boolean"},
+        "removable": {"type": "boolean"}
+      },
+      "description": "ADR-013 install hints (default-on at consumer install; user-removable)."
     }
   }
 }

package/scripts/schemas/skill.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/skill.schema.json",
   "title": "Skill frontmatter",
-  "$comment": "Source: agents/docs/frontmatter-contract.md#skills. Keep in sync with inventory_frontmatter.py and the linter's lint_skill().",
+  "$comment": "Source: agents/reference/docs/frontmatter-contract.md#skills. Keep in sync with inventory_frontmatter.py and the linter's lint_skill().",
   "type": "object",
   "additionalProperties": false,
   "required": ["name", "description", "source", "domain"],
@@ -122,6 +122,46 @@
           "items": { "type": "string" }
         }
       }
+    },
+    "workspaces": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "description": "ADR-013 workspace ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/workspaces.yml."
+    },
+    "packs": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "description": "ADR-013 pack ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/packs.yml."
+    },
+    "lifecycle": {
+      "type": "string",
+      "enum": ["active", "deprecated", "experimental", "archived"],
+      "description": "ADR-013 lifecycle state."
+    },
+    "trust": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "confidence", "human_review_required"],
+      "properties": {
+        "level": {"type": "string", "enum": ["core", "professional", "experimental", "advisory", "restricted"]},
+        "confidence": {"type": "string", "enum": ["high", "medium", "low"]},
+        "human_review_required": {"type": "boolean"}
+      },
+      "description": "ADR-013 trust block. Vocabulary mirrored by scripts/lint_artefact_frontmatter.py."
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["default", "removable"],
+      "properties": {
+        "default": {"type": "boolean"},
+        "removable": {"type": "boolean"}
+      },
+      "description": "ADR-013 install hints (default-on at consumer install; user-removable)."
     }
   }
 }

package/scripts/score_skill_selection.py

@@ -18,7 +18,7 @@ Predictions source:
   pure description-matching would do and provides a numeric floor.
 
 Output: human-readable summary on stdout + machine JSON to
-`agents/reports/skill-selection-accuracy.json` (or `--out`).
+`agents/runtime/reports/skill-selection-accuracy.json` (or `--out`).
 """
 
 from __future__ import annotations

package/scripts/skill_collision_clusters.py

@@ -7,7 +7,7 @@ high-overlap skill pairs into clusters. The output drives the
 selection-accuracy fixture set defined by council file 05 (Round-3
 protocol — ≥ 3 shared significant terms → collision cluster).
 
-Output: `agents/reports/skill-collision-clusters.json`
+Output: `agents/runtime/reports/skill-collision-clusters.json`
 
 Schema:
     {

package/scripts/skill_linter.py

@@ -403,7 +403,7 @@ def _fenced_content_ratio(text: str) -> float:
 # --- Structural-density model (docs/contracts/linter-structural-model.md) ---
 # Replaces the raw line/word/fenced-ratio gates with four primitives that
 # distinguish complexity from bloat. Calibrated 2026-05-08 against the full
-# 310-artefact corpus (agents/.density-snapshot.jsonl).
+# 310-artefact corpus (agents/runtime/density/snapshot.jsonl).
 
 PROCEDURE_HEADING_PATTERN = re.compile(
     r"^##\s+Procedure(\s*[:\u2014\-].*)?\s*$", re.MULTILINE
@@ -2972,7 +2972,7 @@ def lint_frontmatter_schema(path: Path, text: str, artifact_type: str) -> List[I
     """Validate the frontmatter of an artefact against its JSON-Schema.
 
     Schemas live in ``scripts/schemas/``. One schema per artefact type;
-    see ``agents/docs/frontmatter-contract.md`` for the human-readable
+    see ``agents/reference/docs/frontmatter-contract.md`` for the human-readable
     contract the schemas encode. Guidelines have no frontmatter and are
     skipped.
     """

package/scripts/skill_overlap.py

@@ -4,7 +4,7 @@
 Implements step-2-skill-inventory-rationalization.md Phase 2 Step 2.
 Mirrors `scripts/audit_overlap.py` (the rule-side analog) but reads
 `.agent-src.uncompressed/skills/<slug>/SKILL.md` frontmatter directly
-and emits `agents/metrics/skill-overlap.md` listing pairs scoring
+and emits `agents/runtime/metrics/skill-overlap.md` listing pairs scoring
 ≥ 0.6 on either:
 
   - description-trigger Jaccard (tokenized union of `description` +

package/scripts/skill_tools/run_block_d_eval.py

@@ -3,7 +3,7 @@
 
 Runs D2 (`score_skill_relevance`), D3 (`audit_persona_coverage`), and
 D4 (`suggest_skill_for_task`) against the corpora in
-`agents/eval-corpora/block-d/` and emits a pass/fail summary per the
+`agents/evidence/eval-corpora/block-d/` and emits a pass/fail summary per the
 council verdict targets:
 
   - **D2**: ≥ 85 % of corpus tasks have an `expected_top3` skill in

package/scripts/skill_usage_collect.py

@@ -14,12 +14,12 @@ parses each turn for two signals:
     `.agent-src/skills/<slug>/`.
 
 Emits one JSONL record per (session, turn, slug, kind) to
-`agents/metrics/skill-usage.jsonl` (append-only, deduped on the
+`agents/runtime/metrics/skill-usage.jsonl` (append-only, deduped on the
 (session_id, turn_idx, slug, kind) tuple).
 
 Privacy: `prompt_excerpt_hash` = SHA-256 of the first 200 chars of the
 user prompt that opened the turn. No raw user or assistant bodies are
-persisted. See `agents/audit-2026-05-14-north-star/skill-usage-sources.md`.
+persisted. See `agents/evidence/audits/2026-05-14-north-star/skill-usage-sources.md`.
 """
 from __future__ import annotations
 
@@ -153,7 +153,7 @@ def dedup_key(rec: dict) -> tuple:
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     ap.add_argument("--project-slug", help="Override the ~/.claude/projects slug (defaults to current repo)")
-    ap.add_argument("--out", type=Path, default=OUT, help="Output jsonl (default: agents/metrics/skill-usage.jsonl)")
+    ap.add_argument("--out", type=Path, default=OUT, help="Output jsonl (default: agents/runtime/metrics/skill-usage.jsonl)")
     ap.add_argument("--quiet", action="store_true", help="Suppress non-error output")
     args = ap.parse_args()
 

package/scripts/skill_usage_report.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
-"""Aggregate `agents/metrics/skill-usage.jsonl` into a per-skill report.
+"""Aggregate `agents/runtime/metrics/skill-usage.jsonl` into a per-skill report.
 
 Implements step-2-skill-inventory-rationalization.md Phase 1 Step 3.
-Groups records by slug; emits `agents/metrics/skill-usage-report.md`
+Groups records by slug; emits `agents/runtime/metrics/skill-usage-report.md`
 with columns:
 
   slug · exposures_total · mentions_total · exposures_30d · mentions_30d
@@ -112,7 +112,7 @@ def render(per: dict[str, dict], known: set[str]) -> str:
         "# Skill Usage Report (baseline)",
         "",
         "> Generated by `scripts/skill_usage_report.py`. Source:",
-        "> `agents/metrics/skill-usage.jsonl` (collector emits per-turn",
+        "> `agents/runtime/metrics/skill-usage.jsonl` (collector emits per-turn",
         "> exposure/mention records). See",
         "> [`step-2-skill-inventory-rationalization.md`](../roadmaps/step-2-skill-inventory-rationalization.md)",
         "> Phase 1.",

package/scripts/smoke_quickstart.py

@@ -7,7 +7,7 @@ Verifies the 3-step Quickstart from a fresh-project perspective:
      `.agent-settings.yml` with the documented default `cost_profile`.
   2. The decision_engine block (P2.x of road-to-productization) parses
      cleanly through the same engine parser the runtime uses.
-  3. The work-engine state-file format (`agents/state/<id>.json`) is
+  3. The work-engine state-file format (`agents/runtime/state/<id>.json`) is
      emit-ready — schema for `decision_result` matches the contract.
 
 What it does NOT do:

package/scripts/spotcheck_thin_root.py

@@ -4,7 +4,7 @@
 Sends the refactored package-root AGENTS.md and the consumer template
 to Sonnet 4.5 + gpt-4o, asks each member to answer five questions
 that simulate a fresh agent landing on the file. Records qualitative
-verdicts in agents/reports/thin-root-platform-spotcheck.md.
+verdicts in agents/runtime/reports/thin-root-platform-spotcheck.md.
 """
 from __future__ import annotations
 

package/scripts/sync_github_metadata.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Sync `.github/topics.yml` + `.github/about.yml` to the GitHub repo.
+
+Reads two on-disk manifests and pushes them via the REST API:
+  * `PUT  /repos/{owner}/{repo}/topics`   \u2014 topics list
+  * `PATCH /repos/{owner}/{repo}`         \u2014 description + homepage
+
+Default mode is `--dry-run`: fetches remote state, prints a unified
+diff (remote \u2192 desired), exits 0 (or 2 if drift exists when
+`--strict` is passed). `--apply` is required to mutate; it also
+appends an audit row to `agents/evidence/notes/visibility-sync-audit.md`.
+
+Auth: `GITHUB_TOKEN` env var. The repo slug is taken from
+`package.json` `repository.url` (parsed) or `--repo owner/name`.
+
+Stdlib only \u2014 `urllib.request` matches the convention in
+`scripts/_lib/update_check.py`.
+
+Roadmap: agents/roadmaps/strategic-visibility-mcp-topics-positioning.md Phase 1.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import difflib
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+TOPICS_FILE = ROOT / ".github" / "topics.yml"
+ABOUT_FILE = ROOT / ".github" / "about.yml"
+AUDIT_FILE = ROOT / "agents" / "notes" / "visibility-sync-audit.md"
+API = "https://api.github.com"
+
+
+def _load_yaml(path: Path) -> dict:
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+
+
+def _resolve_repo(explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    pkg = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
+    url = (pkg.get("repository") or {}).get("url") or ""
+    m = re.search(r"github\.com[:/]+([^/]+/[^/.]+)", url)
+    if not m:
+        sys.exit("ERROR: cannot resolve owner/repo from package.json; pass --repo")
+    return m.group(1)
+
+
+def _request(method: str, url: str, token: str, body: dict | None = None) -> dict:
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method)
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("Accept", "application/vnd.github+json")
+    req.add_header("X-GitHub-Api-Version", "2022-11-28")
+    req.add_header("User-Agent", "event4u-agent-config-sync")
+    if body is not None:
+        req.add_header("Content-Type", "application/json")
+    try:
+        with urllib.request.urlopen(req, timeout=20) as resp:  # noqa: S310
+            return json.loads(resp.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        sys.exit(f"ERROR: {method} {url} \u2192 HTTP {e.code}: {e.read().decode('utf-8', 'replace')[:300]}")
+    except urllib.error.URLError as e:
+        sys.exit(f"ERROR: {method} {url} \u2192 {e.reason}")
+
+
+def _diff(label: str, remote, desired) -> list[str]:
+    a = json.dumps(remote, indent=2, sort_keys=True).splitlines()
+    b = json.dumps(desired, indent=2, sort_keys=True).splitlines()
+    return list(difflib.unified_diff(a, b, fromfile=f"remote/{label}", tofile=f"desired/{label}", lineterm=""))
+
+
+def _audit(repo: str, mutations: list[str]) -> None:
+    AUDIT_FILE.parent.mkdir(parents=True, exist_ok=True)
+    if not AUDIT_FILE.exists():
+        AUDIT_FILE.write_text("# Visibility sync audit log\n\nAppend-only. Every `--apply` run logs one block.\n", encoding="utf-8")
+    ts = _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    block = [f"\n## {ts} \u2014 {repo}\n"]
+    block.extend(f"- {m}\n" for m in mutations)
+    with AUDIT_FILE.open("a", encoding="utf-8") as f:
+        f.writelines(block)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--apply", action="store_true", help="actually mutate the remote (default: dry-run)")
+    ap.add_argument("--strict", action="store_true", help="exit 2 if drift exists (dry-run only)")
+    ap.add_argument("--quiet", action="store_true")
+    ap.add_argument("--repo", help="owner/name (default: parsed from package.json)")
+    args = ap.parse_args()
+
+    repo = _resolve_repo(args.repo)
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        sys.exit("ERROR: GITHUB_TOKEN not set")
+
+    topics_doc = _load_yaml(TOPICS_FILE)
+    about_doc = _load_yaml(ABOUT_FILE)
+    desired_topics = sorted(topics_doc.get("topics") or [])
+    desired_about = {"description": about_doc.get("description", ""), "homepage": about_doc.get("homepage", "")}
+
+    remote_topics = sorted((_request("GET", f"{API}/repos/{repo}/topics", token).get("names") or []))
+    repo_payload = _request("GET", f"{API}/repos/{repo}", token)
+    remote_about = {"description": repo_payload.get("description") or "", "homepage": repo_payload.get("homepage") or ""}
+
+    topic_diff = _diff("topics", remote_topics, desired_topics)
+    about_diff = _diff("about", remote_about, desired_about)
+    has_drift = bool(topic_diff or about_diff)
+
+    if not args.quiet:
+        if topic_diff:
+            print("\n".join(topic_diff))
+        if about_diff:
+            print("\n".join(about_diff))
+        if not has_drift:
+            print(f"\u2705  {repo}: topics + about already in sync")
+
+    if not args.apply:
+        return 2 if (has_drift and args.strict) else 0
+
+    mutations: list[str] = []
+    if topic_diff:
+        _request("PUT", f"{API}/repos/{repo}/topics", token, {"names": desired_topics})
+        mutations.append(f"topics \u2192 {desired_topics}")
+    if about_diff:
+        _request("PATCH", f"{API}/repos/{repo}", token, desired_about)
+        mutations.append(f"about \u2192 {desired_about}")
+    if mutations:
+        _audit(repo, mutations)
+        if not args.quiet:
+            print(f"\u2705  {repo}: applied {len(mutations)} mutation(s); audit appended")
+    elif not args.quiet:
+        print(f"\u2705  {repo}: nothing to apply")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/sync_gitignore.py

@@ -41,17 +41,27 @@ DEFAULT_GITIGNORE = ".gitignore"
 DEFAULT_TEMPLATE = Path(__file__).resolve().parent.parent / "config" / "gitignore-block.txt"
 
 # Legacy patterns that lived in older versions of config/gitignore-block.txt
-# before runtime artefacts moved under /agents/ (May 2026). They get stripped
-# wherever they appear in the consumer's .gitignore — inside the managed block
-# or outside (older installers / hand-edits). Current canonical equivalents
-# (e.g. /agents/.agent-chat-history) come from the template and are NOT
-# affected. Leading-slash variants are matched defensively.
+# before runtime artefacts moved under /agents/runtime/ (May 2026). They get
+# stripped wherever they appear in the consumer's .gitignore — inside the
+# managed block or outside (older installers / hand-edits). Current canonical
+# equivalents (e.g. /agents/runtime/.agent-prices.md) come from the template
+# and are NOT affected. Leading-slash variants are matched defensively.
 LEGACY_PATTERNS: tuple[str, ...] = (
     ".agent-chat-history",
     ".agent-chat-history.bak",
     ".agent-chat-history.*.bak",
     ".agent-prices.md",
     ".council-tmp/",
+    # 2.x intermediate: prices cache lived directly under agents/ before
+    # consolidating under agents/runtime/.
+    "agents/.agent-prices.md",
+    # Budget history JSONLs — previously listed explicitly at project
+    # root or under agents/; now covered by the /agents/runtime/
+    # catch-all in the managed block.
+    ".augment-budget-history.jsonl",
+    ".rule-budget-history.jsonl",
+    "agents/.augment-budget-history.jsonl",
+    "agents/.rule-budget-history.jsonl",
 )
 
 

package/scripts/update_prices.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Refresh `agents/.agent-prices.md` from the LiteLLM model-prices feed.
+"""Refresh `agents/runtime/.agent-prices.md` from the LiteLLM model-prices feed.
 
 Source: https://raw.githubusercontent.com/BerriAI/litellm/main/
         model_prices_and_context_window.json
@@ -9,7 +9,7 @@ Network failure or invalid response → fall back to
 always written. Stdlib only; no extra dependency.
 
 Usage:
-    python3 scripts/update_prices.py            # writes agents/.agent-prices.md
+    python3 scripts/update_prices.py            # writes agents/runtime/.agent-prices.md
     python3 scripts/update_prices.py --check    # exit 1 if file is stale
 """
 
@@ -81,7 +81,8 @@ def _to_rows_from_litellm(payload: dict[str, dict[str, object]]) -> list[tuple[s
 
 
 def refresh(path: Path = PRICES_FILE) -> str:
-    """Write a fresh `agents/.agent-prices.md`. Returns the source label used."""
+    """Write a fresh `agents/runtime/.agent-prices.md`. Returns the source label used."""
+    path.parent.mkdir(parents=True, exist_ok=True)
     payload = _fetch_litellm()
     if payload is not None:
         rows = _to_rows_from_litellm(payload)

package/scripts/verify_before_complete_hook.py

@@ -11,7 +11,7 @@ Wired to multiple events via the manifest:
   - post_tool_use → inspect tool + command, record verifications
   - stop                                → record stop fired (claim-done window)
 
-Output: `agents/state/verify-before-complete.json`
+Output: `agents/runtime/state/verify-before-complete.json`
   {
     "schema_version": 1,
     "session_id": "<str>",

package/scripts/verify_roadmap_closure.py

@@ -219,7 +219,7 @@ def verify_concept(name: str) -> bool:
     try:
         r = subprocess.run(
             ["git", "grep", "-l", "-w", name, "--",
-             ".agent-src.uncompressed/", "docs/", "scripts/", "agents/contexts/"],
+             ".agent-src.uncompressed/", "docs/", "scripts/", "agents/settings/contexts/"],
             cwd=REPO, capture_output=True, text=True, timeout=15,
         )
         return bool(r.stdout.strip())