@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/generate_pack_manifests.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""Generate ``pack.yaml`` + ``README.md`` for every ``packages/*/`` tree.
+
+Phase 4.4 of the monorepo migration (ADR-017). The manifests are
+*derived* from frontmatter + ``config/discovery/packs.yml``; they are
+regenerated on every ``task sync`` and must never be hand-edited.
+
+For each package directory under ``packages/`` we emit:
+  - ``packages/<pkg>/pack.yaml`` — id, label, owner (workspaces),
+    requires, version, artefact_count
+  - ``packages/<pkg>/README.md`` — pack description + per-artefact
+    description table
+
+CLI:
+  --check     exit non-zero if any output would change (CI gate)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import iter_all_sources  # noqa: E402
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGES = ROOT / "packages"
+PACKS_VOCAB = ROOT / "config" / "discovery" / "packs.yml"
+PACKAGE_JSON = ROOT / "package.json"
+GENERATED_HEADER = "# Generated by scripts/generate_pack_manifests.py — DO NOT EDIT BY HAND\n"
+
+
+def _load_yaml(path: Path) -> Any:
+    if not path.exists():
+        return None
+    return yaml.safe_load(path.read_text(encoding="utf-8"))
+
+
+def _read_frontmatter(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}
+    try:
+        data = yaml.safe_load(text[4:end])
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _pack_id_from_dir(pkg_dir: Path) -> str:
+    name = pkg_dir.name
+    return "core" if name == "core" else name.removeprefix("pack-")
+
+
+def _vocab_lookup(packs_vocab: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+    return {p["id"]: p for p in (packs_vocab or [])}
+
+
+def _package_version() -> str:
+    if not PACKAGE_JSON.exists():
+        return "0.0.0"
+    return json.loads(PACKAGE_JSON.read_text(encoding="utf-8")).get("version", "0.0.0")
+
+
+def _collect_artefacts(pkg_dir: Path) -> list[dict[str, Any]]:
+    src_root = pkg_dir / ".agent-src.uncompressed"
+    if not src_root.is_dir():
+        return []
+    items: list[dict[str, Any]] = []
+    for p in sorted(src_root.rglob("*.md")):
+        if not p.is_file():
+            continue
+        fm = _read_frontmatter(p)
+        if not fm:
+            continue
+        items.append({
+            "path": p.relative_to(src_root).as_posix(),
+            "name": fm.get("name") or (p.parent.name if p.name == "SKILL.md" else p.stem),
+            "description": (fm.get("description") or "").strip(),
+            "category": _category_for(p, src_root),
+        })
+    return items
+
+
+def _category_for(path: Path, src_root: Path) -> str:
+    rel = path.relative_to(src_root).as_posix()
+    top = rel.split("/", 1)[0]
+    mapping = {"skills": "skill", "rules": "rule", "commands": "command",
+               "personas": "persona", "guidelines": "guideline",
+               "contexts": "context", "presets": "preset", "profiles": "profile"}
+    return mapping.get(top, top)
+
+
+def _build_pack_yaml(pkg_dir: Path, vocab: dict[str, dict[str, Any]],
+                     artefacts: list[dict[str, Any]], version: str) -> dict[str, Any]:
+    pid = _pack_id_from_dir(pkg_dir)
+    meta = vocab.get(pid) or {}
+    label = meta.get("label") or (pid.title() if pid == "core" else pid)
+    out: dict[str, Any] = {
+        "id": pid,
+        "label": label,
+        "description": meta.get("description") or ("Core framework-neutral artefacts." if pid == "core" else ""),
+        "owner": meta.get("workspaces") or (["agent-config-maintainer"] if pid == "core" else []),
+        "requires": meta.get("requires_hint") or [],
+        "trust_level_default": meta.get("trust_level_default") or "core",
+        "version": version,
+        "artefact_count": len(artefacts),
+    }
+    if isinstance(meta.get("onboarding"), dict):
+        out["onboarding"] = meta["onboarding"]
+    return out
+
+
+def _render_readme(pack_meta: dict[str, Any], artefacts: list[dict[str, Any]]) -> str:
+    lines = [GENERATED_HEADER, f"# {pack_meta['label']}", ""]
+    if pack_meta.get("description"):
+        lines += [pack_meta["description"], ""]
+    lines += [f"- **id**: `{pack_meta['id']}`",
+              f"- **version**: `{pack_meta['version']}`",
+              f"- **owner**: {', '.join(pack_meta['owner']) or '—'}",
+              f"- **requires**: {', '.join(pack_meta['requires']) or '—'}",
+              f"- **artefacts**: {pack_meta['artefact_count']}", ""]
+    by_cat: dict[str, list[dict[str, Any]]] = {}
+    for a in artefacts:
+        by_cat.setdefault(a["category"], []).append(a)
+    for cat in sorted(by_cat):
+        lines += [f"## {cat.title()}s ({len(by_cat[cat])})", ""]
+        for a in sorted(by_cat[cat], key=lambda x: x["name"]):
+            desc = a["description"] or "_(no description)_"
+            lines.append(f"- **`{a['name']}`** — {desc}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _write_if_changed(path: Path, content: str, check: bool) -> bool:
+    existing = path.read_text(encoding="utf-8") if path.exists() else None
+    if existing == content:
+        return False
+    if check:
+        return True
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--check", action="store_true", help="exit non-zero on drift")
+    args = ap.parse_args()
+    vocab = _vocab_lookup(_load_yaml(PACKS_VOCAB) or [])
+    version = _package_version()
+    if not PACKAGES.exists():
+        print("packages/ does not exist — nothing to generate", file=sys.stderr)
+        return 0
+    drift = 0
+    for pkg in sorted(PACKAGES.iterdir()):
+        if not pkg.is_dir():
+            continue
+        artefacts = _collect_artefacts(pkg)
+        meta = _build_pack_yaml(pkg, vocab, artefacts, version)
+        yaml_body = GENERATED_HEADER + yaml.safe_dump(meta, sort_keys=True, allow_unicode=True)
+        readme_body = _render_readme(meta, artefacts)
+        if _write_if_changed(pkg / "pack.yaml", yaml_body, args.check):
+            drift += 1
+            print(f"{'drift' if args.check else 'wrote'}: {pkg.name}/pack.yaml")
+        if _write_if_changed(pkg / "README.md", readme_body, args.check):
+            drift += 1
+            print(f"{'drift' if args.check else 'wrote'}: {pkg.name}/README.md")
+    if args.check and drift:
+        print(f"pack manifests out of date ({drift} file(s)) — run `task generate-pack-manifests`", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/hook_manifest.yaml

@@ -5,7 +5,7 @@
 #   - scripts/install.py               (per-platform config writer)
 #
 # Schema and event vocabulary: docs/contracts/hook-architecture-v1.md.
-# Per-platform event-name mapping: agents/contexts/chat-history-platform-hooks.md.
+# Per-platform event-name mapping: agents/settings/contexts/chat-history-platform-hooks.md.
 #
 # When you add or remove a concern, also update:
 #   - scripts/agent-config         (CLI subcommand wiring, if exposed)
@@ -32,14 +32,14 @@ concerns:
     fail_closed: false
   # Phase 5 — Tier-1 hook for the verify-before-complete rule. Records
   # observable evidence of verification commands (tests, quality tools,
-  # builds) into agents/state/verify-before-complete.json. The rule body
+  # builds) into agents/runtime/state/verify-before-complete.json. The rule body
   # cites that file as the source of truth for "verified this turn?".
   verify-before-complete:
     script: scripts/verify_before_complete_hook.py
     args: []
     fail_closed: false
   # Phase 5 — Tier-1 hook for the minimal-safe-diff rule. Counts unique
-  # files touched per turn into agents/state/minimal-safe-diff.json and
+  # files touched per turn into agents/runtime/state/minimal-safe-diff.json and
   # flips warning=true past hooks.minimal_safe_diff.threshold.
   minimal-safe-diff:
     script: scripts/minimal_safe_diff_hook.py
@@ -73,7 +73,7 @@ platforms:
   # plugin-scope hooks. Until those land, the dispatcher binding
   # below is structurally ready but lifecycle events do not fire.
   # Decision matrix + upstream blockers tracked in
-  # agents/contexts/chat-history-platform-hooks.md § Cowork.
+  # agents/settings/contexts/chat-history-platform-hooks.md § Cowork.
   cowork:
     session_start:    [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
     session_end:      [chat-history]
@@ -87,7 +87,7 @@ platforms:
   # to route into the active workspace. UserPromptSubmit maps to
   # `beforeSubmitPrompt` (Cursor third-party-hooks table). Stop is
   # IDE-only — CLI-only users fall back to /checkpoint per
-  # agents/contexts/chat-history-platform-hooks.md.
+  # agents/settings/contexts/chat-history-platform-hooks.md.
   cursor:
     session_start:      [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
     session_end:        [chat-history]

package/scripts/hooks/cline-dispatcher.sh

@@ -81,6 +81,6 @@ printf '%s' "$EVENT_DATA" \
 
 # Cline expects a JSON envelope on stdout; empty object = "no cancel,
 # no context modification, no error". Errors from concerns surface
-# through agents/state/.dispatcher/<session_id>/ per Phase 7.3.
+# through agents/runtime/state/.dispatcher/<session_id>/ per Phase 7.3.
 printf '%s\n' '{}'
 exit 0

package/scripts/hooks/cowork-dispatcher.sh

@@ -16,7 +16,7 @@
 # because Cowork spawns the CLI with `--setting-sources user`. The
 # trampoline is structurally ready; install plumbing is deferred
 # until upstream resolves the bugs and a stable settings location is
-# documented. See `agents/contexts/chat-history-platform-hooks.md`
+# documented. See `agents/settings/contexts/chat-history-platform-hooks.md`
 # § Cowork.
 #
 # Behaviour mirrors cursor-dispatcher.sh:

package/scripts/hooks/dispatch_hook.py

@@ -226,7 +226,7 @@ def _run_concern(concern: dict, envelope: dict) -> tuple[int, str, str, int]:
     Returns (rc, stderr_text, stdout_text, duration_ms).
 
     Concerns run with CWD = consumer workspace (envelope.workspace_root),
-    NOT the agent-config package root — concerns resolve `agents/state/`
+    NOT the agent-config package root — concerns resolve `agents/runtime/state/`
     and other consumer-local paths relative to CWD. The script *itself*
     lives in the package (REPO_ROOT), so we resolve it absolutely.
     """
@@ -273,11 +273,11 @@ def _write_feedback(envelope: dict, session_id: str, entries: list[dict],
     matches the dispatcher's overall posture.
     """
     # Replay mode skips feedback emission entirely so fixture replays
-    # never create per-session dirs under agents/state/.dispatcher/.
+    # never create per-session dirs under agents/runtime/state/.dispatcher/.
     if is_replay_mode():
         return
     workspace = envelope.get("workspace_root") or str(Path.cwd())
-    state_root = Path(workspace) / "agents" / "state"
+    state_root = Path(workspace) / "agents" / "runtime" / "state"
     fb_dir = feedback_dir(state_root, session_id)
     try:
         fb_dir.mkdir(parents=True, exist_ok=True)

package/scripts/hooks/gemini-dispatcher.sh

@@ -27,7 +27,7 @@
 #
 # Output — none on stdout. Gemini consumes JSON on stdout for
 # context injection / decision; we don't inject anything from this
-# layer (concerns stream their own state via agents/state/.dispatcher/).
+# layer (concerns stream their own state via agents/runtime/state/.dispatcher/).
 # SessionStart / SessionEnd are advisory in Gemini (continue/decision
 # ignored), so we always exit 0.
 

package/scripts/hooks/replay_hook.py

@@ -5,7 +5,7 @@ Reads a stdin payload fixture from `tests/fixtures/hooks/` (one file per
 event in `EVENT_VOCABULARY`), sets `AGENT_CONFIG_REPLAY=1`, and invokes
 the universal dispatcher with the platform / event / payload tuple. The
 replay flag tells `state_io` (and concerns that honour it) to skip every
-write under `agents/state/` so the replay never mutates real session
+write under `agents/runtime/state/` so the replay never mutates real session
 state.
 
 Invocation:

package/scripts/hooks/state_io.py

@@ -1,9 +1,9 @@
 """Concurrency-safe state writes for hook concerns.
 
 Per `docs/contracts/hook-architecture-v1.md` § Concurrency, every concern
-that writes under `agents/state/` MUST:
+that writes under `agents/runtime/state/` MUST:
 
-1. Acquire `fcntl.flock(LOCK_EX)` on `agents/state/.dispatcher.lock`.
+1. Acquire `fcntl.flock(LOCK_EX)` on `agents/runtime/state/.dispatcher.lock`.
 2. Write to a sibling `<dest>.tmp.<pid>` file in the same directory.
 3. `os.replace(tmp, dest)` — POSIX-atomic on the same filesystem.
 4. Release the lock.
@@ -21,7 +21,7 @@ Cross-platform notes
   holds, and torn-write risk is accepted (Windows is not a primary
   agent-config platform — Cline tracks the upstream Windows-path issue
   separately).
-- The lock file lives under `agents/state/` which is gitignored.
+- The lock file lives under `agents/runtime/state/` which is gitignored.
 - The lock is process-scoped, not session-scoped: each call opens,
   locks, writes, releases, closes. No long-lived file handles.
 """
@@ -47,7 +47,7 @@ def is_replay_mode() -> bool:
     """True when the caller signalled read-only fixture replay.
 
     Concerns and the dispatcher honour the flag by skipping side
-    effects under `agents/state/` (and any other concern-owned state
+    effects under `agents/runtime/state/` (and any other concern-owned state
     surface). See `docs/contracts/hook-architecture-v1.md` § Replay mode.
     """
     return os.environ.get(REPLAY_ENV_VAR, "").strip() == "1"
@@ -60,7 +60,7 @@ def _lock_path(state_dir: Path) -> Path:
 def atomic_write_json(target: Path, payload: Any, *, indent: int = 2) -> None:
     """Write `payload` as JSON to `target` atomically and concurrency-safely.
 
-    `target` MUST sit under an `agents/state/` directory (or any other
+    `target` MUST sit under an `agents/runtime/state/` directory (or any other
     directory the caller treats as the lock scope). The lock file is
     `<target.parent>/.dispatcher.lock`. Caller does not need to create
     the directory in advance — this function ensures it.

package/scripts/hooks_doctor.py

@@ -11,8 +11,8 @@ and adds three diagnostics the bare status table does not surface:
     `scripts/hooks/<platform>-dispatcher.sh`; flags any platform that
     has manifest bindings but no trampoline on disk.
   * **Last feedback** — for each concern, the most-recent dispatcher
-    feedback file under `agents/state/.dispatcher/*/<concern>.json`,
-    plus the per-rule state file under `agents/state/<concern>.json`
+    feedback file under `agents/runtime/state/.dispatcher/*/<concern>.json`,
+    plus the per-rule state file under `agents/runtime/state/<concern>.json`
     when one exists.
 
 This is a **read-only** report. It never installs, modifies, or runs
@@ -36,7 +36,7 @@ import dispatch_hook  # noqa: E402
 import hooks_status  # noqa: E402
 
 TRAMPOLINE_DIR = REPO_ROOT / "scripts" / "hooks"
-STATE_DIR_DEFAULT = "agents/state"
+STATE_DIR_DEFAULT = "agents/runtime/state"
 
 # Platforms whose bridge file (settings.json) invokes the universal
 # dispatcher directly — no shell trampoline required. Excluded from the
@@ -55,7 +55,7 @@ def _concern_state_file(state_dir: Path, concern: str) -> Path | None:
 
 def _latest_feedback(state_dir: Path, concern: str) -> Path | None:
     """Return the most-recent dispatcher feedback file for the concern,
-    walking `agents/state/.dispatcher/<session>/<concern>.json`."""
+    walking `agents/runtime/state/.dispatcher/<session>/<concern>.json`."""
     dispatcher_dir = state_dir / ".dispatcher"
     if not dispatcher_dir.is_dir():
         return None

package/scripts/install

@@ -183,6 +183,20 @@ if $LIST_TOOLS; then
     exit 0
 fi
 
+# road-to-global-only-install § Phase 3.3 — consumer-floor gate.
+#
+# Consumer installs are global-only (ADR-020). Explicit --scope=project
+# (and its --scope project / --scope=project / SCOPE shorthand) is the
+# maintainer-only escape hatch behind AGENT_CONFIG_DEV_MODE=1. Without
+# the env flag we refuse here so the bash orchestrator fails fast with
+# a directive error pointing at the maintainer doc — install.py's
+# Python-side _enforce_consumer_global_only still backstops the same
+# check for direct python3 scripts/install.py invocations.
+if [[ "${SCOPE:-}" == "project" && "${AGENT_CONFIG_DEV_MODE:-}" != "1" ]]; then
+    err "--scope=project is reserved for maintainers (ADR-020 — consumer installs are global-only). Set AGENT_CONFIG_DEV_MODE=1 to opt in. See docs/maintainers/dev-mode.md."
+    exit 1
+fi
+
 # Interactive --tools picker (S9). Fires only when:
 #   - --tools was not explicitly passed
 #   - --yes / -y was not passed (CI / non-interactive opt-out)
@@ -298,7 +312,10 @@ run_sync() {
     $QUIET   && args+=(--quiet)
     $MINIMAL && args+=(--minimal)
     args+=(--tools="$TOOLS")
-    bash "$INSTALL_SH" "${args[@]}"
+    # Suppress the install.sh deprecation banner when called through the
+    # orchestrator (this script). Direct `bash install.sh` invocations
+    # still see it. See ADR-016 § Distribution / Phase 6.
+    AGENT_CONFIG_FROM_ORCHESTRATOR=1 bash "$INSTALL_SH" "${args[@]}"
 }
 
 run_bridges() {

package/scripts/install-hooks.sh

@@ -98,7 +98,7 @@ echo "✅  Pre-commit hook installed."
 # lifecycle hooks) cannot fire SessionStart/Stop/PostToolUse. Git hooks
 # are the platform-agnostic lifecycle surface that fires regardless of
 # IDE — every commit, merge, checkout, and rewrite turns into a phase
-# boundary in agents/.agent-chat-history when an agent session is active.
+# boundary in agents/runtime/.agent-chat-history when an agent session is active.
 #
 # The hooks are silent no-ops when no agent session is active (the
 # chat_history.py hook-append script returns "skipped_no_sidecar" with
@@ -110,7 +110,7 @@ write_chat_history_hook() {
     local phase_tag="$2"
     cat > "$HOOKS_DIR/$name" << EOF
 #!/usr/bin/env bash
-# $name: append a phase boundary to agents/.agent-chat-history when an agent
+# $name: append a phase boundary to agents/runtime/.agent-chat-history when an agent
 # session is active. Silent no-op otherwise. Never blocks git.
 
 if [ -x ./agent-config ]; then