@event4u/agent-config 2.25.0 → 3.0.0

package/scripts/council_cli.py

@@ -24,15 +24,15 @@ import yaml
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
-AI_COUNCIL_FILE = REPO_ROOT / "agents" / ".ai-council.yml"
+AI_COUNCIL_FILE = REPO_ROOT / "agents" / "settings" / ".ai-council.yml"
 
 # Canonical output dirs per ai-council § "Output path convention".
 # Enforced at write-time by `_validate_council_output_path` so shell-side
 # `>` redirects and forgetful agents can't strand artefacts at agents/ root.
 COUNCIL_CANONICAL_DIRS: dict[str, str] = {
-    "responses": "agents/council-responses",
-    "sessions":  "agents/council-sessions",
-    "questions": "agents/council-questions",
+    "responses": "agents/runtime/council/responses",
+    "sessions":  "agents/runtime/council/sessions",
+    "questions": "agents/runtime/council/questions",
 }
 
 
@@ -139,7 +139,7 @@ def load_settings(
     ``load_agent_settings``. ``ai_council.*`` keys are not whitelisted,
     so the project file remains authoritative for council config.
 
-    Step-2 council-redesign overlay: when ``agents/.ai-council.yml``
+    Step-2 council-redesign overlay: when ``agents/settings/.ai-council.yml``
     exists it is the single source of truth — the validated config is
     synthesized back into ``settings['ai_council']`` and wins over any
     legacy block in ``.agent-settings.yml``. The pre-2 path stays alive
@@ -478,7 +478,7 @@ def _construct_api_member(
     """Build an api-mode client for a known provider name.
 
     ``api_key_ref`` carries the validated ``file:<path>`` / ``env:<VAR>``
-    reference from ``agents/.ai-council.yml`` and is resolved lazily here
+    reference from ``agents/settings/.ai-council.yml`` and is resolved lazily here
     so the council does not require keys for disabled providers. When
     ``api_key_ref`` is ``None`` (no new config yet, or legacy code path),
     fall back to the per-provider loaders so the pre-step-2
@@ -500,7 +500,7 @@ def _construct_api_member(
     if name == "gemini":
         if not api_key_ref:
             raise CouncilDisabledError(
-                "member 'gemini' requires api_key_ref in agents/.ai-council.yml "
+                "member 'gemini' requires api_key_ref in agents/settings/.ai-council.yml "
                 "(e.g. `env:GEMINI_API_KEY`) — no legacy fallback."
             )
         api_key = resolve_api_key(api_key_ref, scope="ai_council.members.gemini")
@@ -508,7 +508,7 @@ def _construct_api_member(
     if name == "xai":
         if not api_key_ref:
             raise CouncilDisabledError(
-                "member 'xai' requires api_key_ref in agents/.ai-council.yml "
+                "member 'xai' requires api_key_ref in agents/settings/.ai-council.yml "
                 "(e.g. `env:XAI_API_KEY`) — no legacy fallback."
             )
         api_key = resolve_api_key(api_key_ref, scope="ai_council.members.xai")
@@ -516,7 +516,7 @@ def _construct_api_member(
     if name == "perplexity":
         if not api_key_ref:
             raise CouncilDisabledError(
-                "member 'perplexity' requires api_key_ref in agents/.ai-council.yml "
+                "member 'perplexity' requires api_key_ref in agents/settings/.ai-council.yml "
                 "(e.g. `env:PERPLEXITY_API_KEY`) — no legacy fallback."
             )
         api_key = resolve_api_key(api_key_ref, scope="ai_council.members.perplexity")
@@ -794,7 +794,7 @@ def _peer_review_active(ai_cfg: dict[str, Any], args: argparse.Namespace) -> boo
     Resolution chain (highest priority first):
       1. ``--peer-review`` CLI flag — explicit opt-in.
       2. ``ai_council.peer_review.enabled: true`` in
-         ``agents/.ai-council.yml`` — opt-in via config.
+         ``agents/settings/.ai-council.yml`` — opt-in via config.
     Both default to false; peer-review is opt-in by R2 verdict.
     """
     if getattr(args, "peer_review", False):
@@ -1037,7 +1037,7 @@ def _emit_debate_estimate(
     if requested > max_rounds_cap:
         raise argparse.ArgumentTypeError(
             f"--rounds={requested} exceeds debate_max_rounds={max_rounds_cap}; "
-            f"raise the cap in agents/.ai-council.yml or lower --rounds."
+            f"raise the cap in agents/settings/.ai-council.yml or lower --rounds."
         )
     rounds = requested
     per_round_usd = sum(e.total_usd for e in estimates)
@@ -1424,7 +1424,7 @@ def _debate_refusal_cap(
 def _emit_shadow_slo_banner() -> None:
     """Pre-flight SLO banner for solo-dispatch invocations (step-9 P10).
 
-    Reads ``agents/council-shadow-log.jsonl`` and prints the 7-day rolling
+    Reads ``agents/runtime/council/shadow-log.jsonl`` and prints the 7-day rolling
     disagreement rate. ``OK``, ``WARN``, ``BREACH`` are all surfaced so the
     user can see when single-member quality is drifting. Never auto-flips
     back to full council \u2014 visibility-first, action-second (D10).
@@ -1444,7 +1444,7 @@ def _apply_solo_dispatch(
 ) -> tuple[list[ExternalAIClient], str | None]:
     """Filter ``members`` to a single solo-dispatch pick (step-9 P9).
 
-    Loads the routing chain from ``agents/.ai-council.yml`` and asks
+    Loads the routing chain from ``agents/settings/.ai-council.yml`` and asks
     :func:`select_solo_member` for the first chain entry whose member
     is runtime-present. The probe is conservative: a member counts as
     auth-valid iff ``build_members`` returned a runtime client for it
@@ -1596,7 +1596,7 @@ def cmd_run(
     # Phase 8 step 5 — opt-in cost disclosure for non-debate lenses.
     # Default mode is "off" for analysis / default (cheap enough that
     # the disclosure is friction); users opt in by setting
-    # `lenses.<name>.cost_disclosure.mode` in agents/.ai-council.yml.
+    # `lenses.<name>.cost_disclosure.mode` in agents/settings/.ai-council.yml.
     disc_mode, disc_threshold, disc_show = _resolve_cost_disclosure(
         ai_cfg, question.mode,
     )
@@ -1885,7 +1885,7 @@ def cmd_debate(
     if requested > max_rounds_cap:
         raise argparse.ArgumentTypeError(
             f"--rounds={requested} exceeds debate_max_rounds={max_rounds_cap}; "
-            f"raise the cap in agents/.ai-council.yml or lower --rounds."
+            f"raise the cap in agents/settings/.ai-council.yml or lower --rounds."
         )
     rounds = requested
 
@@ -1942,7 +1942,7 @@ def cmd_debate(
             f"❌  council:debate refused · high-end estimate "
             f"${debate_estimate.high_usd:.4f} exceeds "
             f"debate.max_cost_usd=${cap:.2f}. Lower --rounds, drop "
-            f"members, or raise the cap in agents/.ai-council.yml.\n"
+            f"members, or raise the cap in agents/settings/.ai-council.yml.\n"
         )
         return 4
 
@@ -2037,7 +2037,7 @@ def cmd_render(args: argparse.Namespace) -> int:
     Lens resolution order: explicit ``--prompt-mode`` > ``prompt_mode``
     in the payload > ``mode`` in the payload > ``None`` (default decision
     template). R4 Q4 escape hatch ``--prose-synthesis`` overrides the
-    table. ``--output`` writes to ``agents/council-sessions/`` (enforced);
+    table. ``--output`` writes to ``agents/runtime/council/sessions/`` (enforced);
     omit it for stdout.
     """
     payload = json.loads(Path(args.responses).read_text(encoding="utf-8"))
@@ -2258,7 +2258,7 @@ def _add_common_input_args(p: argparse.ArgumentParser) -> None:
                         "(anonymised) responses for blind spots before "
                         "synthesis. Adds N extra API calls. Opt-in per the "
                         "R2 verdict; also accepts ai_council.peer_review."
-                        "enabled: true in agents/.ai-council.yml.")
+                        "enabled: true in agents/settings/.ai-council.yml.")
 
 
 def cmd_shadow_report(args: argparse.Namespace) -> int:
@@ -2405,7 +2405,7 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Required to actually start the debate.")
     p_deb.add_argument("--rounds", type=int, default=None,
                        help="Number of debate rounds (default 2). Capped by "
-                            "ai_council.debate_max_rounds in agents/.ai-council.yml.")
+                            "ai_council.debate_max_rounds in agents/settings/.ai-council.yml.")
     p_deb.add_argument("--auto-continue", action="store_true",
                        default=False, dest="auto_continue",
                        help="Skip the between-round y/N prompt. The hard cap "
@@ -2441,7 +2441,7 @@ def build_parser() -> argparse.ArgumentParser:
                             "to the `mode` recorded in the responses JSON.")
     p_ren.add_argument("--output", default=None,
                        help="Write the rendered markdown to a file under "
-                            "agents/council-sessions/ (enforced). Omit for "
+                            "agents/runtime/council/sessions/ (enforced). Omit for "
                             "stdout. Prefer this over shell redirects so "
                             "the canonical-path check fires at write-time.")
     _add_prose_synthesis_arg(p_ren)
@@ -2483,12 +2483,12 @@ def build_parser() -> argparse.ArgumentParser:
 
     p_sha = sub.add_parser(
         "shadow-report",
-        help="Read agents/council-shadow-log.jsonl and print the 7-day "
+        help="Read agents/runtime/council/shadow-log.jsonl and print the 7-day "
              "rolling disagreement rate + SLO status (step-9 P10).",
     )
     p_sha.add_argument("--log", default=None,
                        help="Path to the shadow log (default: "
-                            "agents/council-shadow-log.jsonl).")
+                            "agents/runtime/council/shadow-log.jsonl).")
     p_sha.add_argument("--window-days", type=int, default=7,
                        help="Rolling window in days (default: 7).")
 

package/scripts/council_prune.py

@@ -4,9 +4,9 @@
 Deletes council files older than `ai_council.session_retention_days`
 (default 7) across all four artefact directories:
 
-  - agents/council-sessions/   (timestamp subdirs + root files)
-  - agents/council-questions/  (mtime-based)
-  - agents/council-responses/  (mtime-based)
+  - agents/runtime/council/sessions/   (timestamp subdirs + root files)
+  - agents/runtime/council/questions/  (mtime-based)
+  - agents/runtime/council/responses/  (mtime-based)
 
 Same logic as the auto-prune that runs on every `council save()`,
 exposed as a Task target so the user can sweep on demand.

package/scripts/extract_audit_patterns.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Mine repeated phase patterns from ``agents/state/audit/*.jsonl``.
+"""Mine repeated phase patterns from ``agents/runtime/state/audit/*.jsonl``.
 
 Consumer side of `audit-log-v1` (see
 `docs/contracts/audit-log-v1.md`). Reads append-only JSONL audit
@@ -46,7 +46,7 @@ from pathlib import Path
 from typing import Iterable
 
 ROOT = Path(__file__).resolve().parent.parent
-DEFAULT_AUDIT_DIR = ROOT / "agents" / "state" / "audit"
+DEFAULT_AUDIT_DIR = ROOT / "agents" / "runtime" / "state" / "audit"
 SCHEMA_VERSION = 1
 
 

package/scripts/gen_discovery_baseline.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Generate agents/evidence/notes/discovery-baseline.md for Phase 0.1."""
+from __future__ import annotations
+
+import datetime as _dt
+import pathlib
+import re
+import sys
+from collections import Counter
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+SRC = ROOT / ".agent-src.uncompressed"
+
+
+def _frontmatter(path: pathlib.Path) -> dict[str, str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    m = re.match(r"^---\n(.*?)\n---\n", text, re.DOTALL)
+    if not m:
+        return {}
+    out: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        if ":" in line and not line.startswith(" "):
+            k, _, v = line.partition(":")
+            out[k.strip()] = v.strip().strip('"').strip("'")
+    return out
+
+
+def main() -> int:
+    skills = sorted((SRC / "skills").rglob("SKILL.md"))
+    rules = sorted((SRC / "rules").rglob("*.md"))
+    commands = sorted((SRC / "commands").rglob("*.md"))
+    templates = sorted((SRC / "templates").rglob("*")) if (SRC / "templates").exists() else []
+    templates = [p for p in templates if p.is_file()]
+
+    domains: Counter[str] = Counter()
+    no_domain = 0
+    for s in skills:
+        fm = _frontmatter(s)
+        d = fm.get("domain")
+        if d:
+            domains[d] += 1
+        else:
+            no_domain += 1
+
+    out = []
+    out.append("# Discovery Baseline — Inventory (Phase 0.1)\n")
+    out.append(
+        f"> Generated by `scripts/gen_discovery_baseline.py` on "
+        f"{_dt.datetime.now(_dt.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}.\n"
+    )
+    out.append(
+        "> Frozen reference for the Phase 2 scanner — the `no domain` tally below must match the\n"
+        "> first scanner run's `unassigned[]` count within ±5% (Phase 2.4 acceptance).\n"
+    )
+
+    out.append("## Counts by category\n")
+    out.append("| Category | Path | Count |")
+    out.append("|---|---|---|")
+    out.append(f"| Skills | `.agent-src.uncompressed/skills/*/SKILL.md` | {len(skills)} |")
+    out.append(f"| Rules | `.agent-src.uncompressed/rules/**/*.md` | {len(rules)} |")
+    out.append(f"| Commands | `.agent-src.uncompressed/commands/**/*.md` | {len(commands)} |")
+    out.append(f"| Templates | `.agent-src.uncompressed/templates/**/*` | {len(templates)} |")
+    out.append("")
+
+    out.append("## Distinct `domain:` values (skills)\n")
+    for d, n in domains.most_common():
+        out.append(f"- `{d}` — {n} skill(s)")
+    out.append("")
+
+    out.append("## Skills without `domain:` (Phase 0.1 baseline)\n")
+    out.append(
+        f"- Count: **{no_domain}** (target for Phase 2.4 `unassigned[]` tally ±5%)"
+    )
+    out.append("")
+
+    out.append("## Sample frontmatter keys (first 10 skills)\n")
+    out.append("| File | name | source | domain | other keys |")
+    out.append("|---|---|---|---|---|")
+    interesting = {"status", "tier", "recommended_for_user_types", "cluster", "skills"}
+    for s in skills[:10]:
+        fm = _frontmatter(s)
+        other = ",".join(sorted(k for k in fm if k in interesting))
+        rel = s.relative_to(SRC)
+        out.append(
+            f"| `{rel}` | {fm.get('name','')} | {fm.get('source','')} | "
+            f"{fm.get('domain','')} | {other} |"
+        )
+    out.append("")
+
+    out.append("## Sample rules (first 10)\n")
+    out.append("| File | type | tier | source |")
+    out.append("|---|---|---|---|")
+    for r in rules[:10]:
+        fm = _frontmatter(r)
+        rel = r.relative_to(SRC)
+        out.append(
+            f"| `{rel}` | {fm.get('type','')} | {fm.get('tier','')} | {fm.get('source','')} |"
+        )
+    out.append("")
+
+    out.append("## Sample commands (first 10)\n")
+    out.append("| File | name | tier | cluster |")
+    out.append("|---|---|---|---|")
+    for c in commands[:10]:
+        fm = _frontmatter(c)
+        rel = c.relative_to(SRC)
+        out.append(
+            f"| `{rel}` | {fm.get('name','')} | {fm.get('tier','')} | {fm.get('cluster','')} |"
+        )
+    out.append("")
+
+    out.append("## Notes\n")
+    out.append("- Every skill carries `domain:` today — Phase 4 mapping uses it as primary signal.")
+    out.append("- Rules use `type` (always | auto) + `tier` (safety-floor | kernel | …); no `domain:` today.")
+    out.append("- Commands use `tier` + `cluster`; no `domain:` today.")
+    out.append("- Templates have no consistent frontmatter; Phase 4 quarantines them in `unassigned-artefacts.yml`.")
+    out.append("")
+
+    dest = ROOT / "agents" / "notes" / "discovery-baseline.md"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text("\n".join(out), encoding="utf-8")
+    print(f"wrote {dest} — {len(out)} lines")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/generate_ownership_matrix.py

@@ -4,7 +4,7 @@
 Produces:
 
   * docs/contracts/file-ownership-matrix.json (machine, internal-locked)
-  * agents/contexts/structural/file-ownership-matrix.md (human-readable)
+  * agents/settings/contexts/structural/file-ownership-matrix.md (human-readable)
 
 Walks `.agent-src.uncompressed/{rules,skills,commands,contexts,personas}/`,
 parses frontmatter for `load_context:` / `load_context_eager:`, scans

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

package/scripts/install.py

@@ -1009,7 +1009,7 @@ def ensure_augment_user_hooks(package_root: Path, force: bool) -> list[dict[str,
 # scripts/hook_manifest.yaml to resolve which concerns fire on each
 # (platform, event) tuple. Mirrors AUGMENT_DISPATCHER_BINDINGS so each
 # concern fires on the same logical surface across platforms — the
-# contract from agents/contexts/hardening-pattern.md § Cross-platform
+# contract from agents/settings/contexts/hardening-pattern.md § Cross-platform
 # parity.
 CLAUDE_DISPATCHER_BINDINGS = (
     ("session_start",      "SessionStart"),
@@ -1074,7 +1074,7 @@ def ensure_claude_bridge(project_root: Path, force: bool) -> list[dict[str, Any]
 # Native event names per https://cursor.com/docs/reference/third-party-hooks
 # (camelCase). UserPromptSubmit lives at `beforeSubmitPrompt`. Stop is
 # IDE-only — CLI-only Cursor users get the rule-only checkpoint
-# fallback per agents/contexts/chat-history-platform-hooks.md.
+# fallback per agents/settings/contexts/chat-history-platform-hooks.md.
 CURSOR_DISPATCHER_BINDINGS = (
     ("session_start",       "sessionStart"),
     ("session_end",         "sessionEnd"),
@@ -1335,7 +1335,7 @@ def ensure_windsurf_bridge(project_root: Path, force: bool) -> list[dict[str, An
     scope. Idempotent via deep_merge — rerunning replaces hook arrays
     rather than appending duplicates. `show_output: false` keeps post
     hooks silent (per Windsurf docs); concerns stream their own output
-    via agents/state/.dispatcher/.
+    via agents/runtime/state/.dispatcher/.
     """
     hooks: dict[str, list] = {}
     for ac_event, native in WINDSURF_DISPATCHER_BINDINGS: