@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/install.sh

@@ -248,7 +248,7 @@ create_symlink() {
     local link_dir
     link_dir="$(dirname "$link_abs")"
 
-    mkdir -p "$link_dir"
+    $DRY_RUN || mkdir -p "$link_dir"
 
     # Remove existing file/symlink
     if [[ -L "$link_abs" ]] || [[ -f "$link_abs" ]]; then
@@ -336,7 +336,7 @@ sync_hybrid() {
         local target_dir
         target_dir="$(dirname "$target_file")"
 
-        mkdir -p "$target_dir"
+        $DRY_RUN || mkdir -p "$target_dir"
 
         if should_copy "$rel_path"; then
             # Remove existing symlink before copying
@@ -446,7 +446,7 @@ create_tool_symlinks() {
     local project_root="$1"
     local rules_dir="$project_root/.augment/rules"
 
-    [[ -d "$rules_dir" ]] || return
+    [[ -d "$rules_dir" ]] || return 0
 
     local -a tool_ids=()
     local -a tool_dirs=()
@@ -466,7 +466,7 @@ create_tool_symlinks() {
         local rel_prefix="${rel_prefixes[$i]}"
         local target_dir="$project_root/$dir"
 
-        mkdir -p "$target_dir"
+        $DRY_RUN || mkdir -p "$target_dir"
 
         for rule_file in "$rules_dir"/*.md; do
             [[ -f "$rule_file" ]] || continue
@@ -516,11 +516,11 @@ create_skill_symlinks() {
     local project_root="$1"
     local skills_dir="$project_root/.augment/skills"
 
-    [[ -d "$skills_dir" ]] || return
+    [[ -d "$skills_dir" ]] || return 0
     is_tool_enabled "claude-code" || { log_verbose "skip .claude/skills/ (claude-code not selected)"; return 0; }
 
     local target_dir="$project_root/.claude/skills"
-    mkdir -p "$target_dir"
+    $DRY_RUN || mkdir -p "$target_dir"
 
     local count=0
     for skill_dir in "$skills_dir"/*/; do
@@ -569,7 +569,7 @@ generate_windsurfrules() {
     local project_root="$1"
     local rules_dir="$project_root/.augment/rules"
 
-    [[ -d "$rules_dir" ]] || return
+    [[ -d "$rules_dir" ]] || return 0
     is_tool_enabled "windsurf" || { log_verbose "skip .windsurfrules (windsurf not selected)"; return 0; }
 
     local output="$project_root/.windsurfrules"
@@ -629,8 +629,8 @@ copy_if_missing() {
     local source="$1"
     local target="$2"
 
-    [[ -f "$source" ]] || return
-    [[ -f "$target" ]] && return
+    [[ -f "$source" ]] || return 0
+    [[ -f "$target" ]] && return 0
 
     if $DRY_RUN; then
         log_verbose "copy $(basename "$target") (missing)"
@@ -641,40 +641,139 @@ copy_if_missing() {
     cp "$source" "$target"
 }
 
-# Migrate legacy infra files from project root to agents/.
-# Pre-2.x layout: .agent-chat-history (+ .bak), .agent-prices.md lived at
-# the project root. They now live under agents/. Move them in place before
-# any other content sync so the updated gitignore block (which lists
-# /agents/.agent-chat-history*) and the chat-history hooks operate on the
-# already-migrated layout. Idempotent: skips silently if the target already
-# exists; never overwrites.
+# Migrate legacy infra files to their current home under agents/runtime/.
+# Three source layouts are handled per file:
+#   - pre-2.x:           <name> at project root
+#   - 2.x intermediate:  agents/<name>
+#   - current:           agents/runtime/<name>
+# Covered files: .agent-chat-history (+ .bak) and the append-only budget
+# history JSONLs. Idempotent: skips silently if the target already exists;
+# never overwrites.
+#
+# .agent-prices.md is handled separately by migrate_legacy_prices_file.
 migrate_legacy_root_infra() {
     local project_root="$1"
-    local agents_dir="$project_root/agents"
-    local items=(".agent-chat-history" ".agent-chat-history.bak" ".agent-prices.md")
+    local runtime_dir="$project_root/agents/runtime"
+    local items=(
+        ".agent-chat-history"
+        ".agent-chat-history.bak"
+        ".augment-budget-history.jsonl"
+        ".rule-budget-history.jsonl"
+    )
+
+    for name in "${items[@]}"; do
+        local target="$runtime_dir/$name"
+        local sources=("$project_root/$name" "$project_root/agents/$name")
+
+        for old in "${sources[@]}"; do
+            [[ -e "$old" ]] || continue
+
+            if [[ -e "$target" ]]; then
+                log_warn "Legacy ${old#"$project_root/"} found, but agents/runtime/$name already exists — leaving source in place"
+                continue
+            fi
+
+            if $DRY_RUN; then
+                log_verbose "would migrate ${old#"$project_root/"} → agents/runtime/$name"
+                continue
+            fi
+
+            mkdir -p "$runtime_dir"
+            mv "$old" "$target"
+            log_info "Migrated ${old#"$project_root/"} → agents/runtime/$name"
+        done
+    done
+}
+
+# Migrate the low-impact decision corpus from agents/ to agents/decisions/.
+# Pre-refactor: the .md and its .lock.yaml lived at agents/ root. They
+# now live under agents/decisions/ to separate tracked decisions from
+# volatile runtime data. Idempotent: skips silently if the target
+# already exists; never overwrites.
+migrate_legacy_low_impact_decisions() {
+    local project_root="$1"
+    local decisions_dir="$project_root/agents/decisions"
+    local items=("low-impact-decisions.md" "low-impact-decisions.lock.yaml")
 
     for name in "${items[@]}"; do
-        local old="$project_root/$name"
-        local new="$agents_dir/$name"
+        local old="$project_root/agents/$name"
+        local target="$decisions_dir/$name"
 
         [[ -e "$old" ]] || continue
 
-        if [[ -e "$new" ]]; then
-            log_warn "Legacy $name found at project root, but agents/$name already exists — leaving root copy in place"
+        if [[ -e "$target" ]]; then
+            log_warn "Legacy agents/$name found, but agents/decisions/$name already exists — leaving source in place"
             continue
         fi
 
         if $DRY_RUN; then
-            log_verbose "would migrate $name → agents/$name"
+            log_verbose "would migrate agents/$name → agents/decisions/$name"
             continue
         fi
 
-        mkdir -p "$agents_dir"
-        mv "$old" "$new"
-        log_info "Migrated $name → agents/$name"
+        mkdir -p "$decisions_dir"
+        mv "$old" "$target"
+        log_info "Migrated agents/$name → agents/decisions/$name"
     done
 }
 
+# Migrate the AI Council price cache to its current home under agents/runtime/.
+# Two source locations are handled:
+#   - pre-2.x:           .agent-prices.md at project root
+#   - 2.x intermediate:  agents/.agent-prices.md
+# Both move to agents/runtime/.agent-prices.md. Idempotent: skips silently
+# if the target already exists; never overwrites.
+migrate_legacy_prices_file() {
+    local project_root="$1"
+    local runtime_dir="$project_root/agents/runtime"
+    local target="$runtime_dir/.agent-prices.md"
+    local sources=("$project_root/.agent-prices.md" "$project_root/agents/.agent-prices.md")
+
+    for old in "${sources[@]}"; do
+        [[ -e "$old" ]] || continue
+
+        if [[ -e "$target" ]]; then
+            log_warn "Legacy ${old#"$project_root/"} found, but agents/runtime/.agent-prices.md already exists — leaving source in place"
+            continue
+        fi
+
+        if $DRY_RUN; then
+            log_verbose "would migrate ${old#"$project_root/"} → agents/runtime/.agent-prices.md"
+            continue
+        fi
+
+        mkdir -p "$runtime_dir"
+        mv "$old" "$target"
+        log_info "Migrated ${old#"$project_root/"} → agents/runtime/.agent-prices.md"
+    done
+}
+
+# Migrate the AI Council config from agents/.ai-council.yml to
+# agents/settings/.ai-council.yml. Idempotent: skips silently if the
+# target already exists; never overwrites.
+migrate_legacy_council_yml() {
+    local project_root="$1"
+    local settings_dir="$project_root/agents/settings"
+    local target="$settings_dir/.ai-council.yml"
+    local source="$project_root/agents/.ai-council.yml"
+
+    [[ -e "$source" ]] || return 0
+
+    if [[ -e "$target" ]]; then
+        log_warn "Legacy agents/.ai-council.yml found, but agents/settings/.ai-council.yml already exists — leaving source in place"
+        return 0
+    fi
+
+    if $DRY_RUN; then
+        log_verbose "would migrate agents/.ai-council.yml → agents/settings/.ai-council.yml"
+        return 0
+    fi
+
+    mkdir -p "$settings_dir"
+    mv "$source" "$target"
+    log_info "Migrated agents/.ai-council.yml → agents/settings/.ai-council.yml"
+}
+
 # Ensure .gitignore contains the managed agent-config block.
 # Delegates to scripts/sync_gitignore.py so the installer and the
 # standalone /sync-gitignore command share one source of truth
@@ -735,8 +834,26 @@ install_cli_wrapper() {
 }
 
 # --- Main ---
+# Phase 6 of monorepo-phase-3-typescript-installer (ADR-016 § Distribution):
+# direct `bash install.sh` invocations are deprecated in favor of the
+# TypeScript installer (`npx @event4u/agent-config init`). The banner only
+# fires when this script is invoked directly — the orchestrator
+# (scripts/install) and the consumer `./agent-config` wrapper set
+# AGENT_CONFIG_FROM_ORCHESTRATOR=1 to suppress the noise. Removal target:
+# the cutover release that flips the npx entry point to the TS installer.
+emit_deprecation_banner() {
+    $QUIET && return 0
+    [[ "${AGENT_CONFIG_FROM_ORCHESTRATOR:-0}" == "1" ]] && return 0
+    [[ "${AGENT_CONFIG_SUPPRESS_DEPRECATION:-0}" == "1" ]] && return 0
+    echo "  ⚠️  Direct \`bash install.sh\` is deprecated (ADR-016 § Distribution)." >&2
+    echo "      Prefer:  npx @event4u/agent-config init" >&2
+    echo "      Or:      bash scripts/install   (orchestrator, suppresses this banner)" >&2
+    echo "" >&2
+}
+
 main() {
     parse_args "$@"
+    emit_deprecation_banner
 
     # Minimal-init short-circuit (Step 7 Phase 2): skip every payload-sync
     # stage and only install the project-local `./agent-config` wrapper.
@@ -768,6 +885,9 @@ main() {
 
     # 0. Migrate legacy infra files (root → agents/) before any content sync.
     migrate_legacy_root_infra "$TARGET_DIR"
+    migrate_legacy_low_impact_decisions "$TARGET_DIR"
+    migrate_legacy_prices_file "$TARGET_DIR"
+    migrate_legacy_council_yml "$TARGET_DIR"
 
     # 0b. Resolve settings (e.g. augment.rules_use_symlinks). On first
     #     install the file does not exist yet → defaults preserved.
@@ -823,7 +943,7 @@ main() {
             if [[ "$airgap_mode" == "api" ]]; then
                 echo ""
                 echo "⚠️  airgapped environment detected — defaulting to mode: api"
-                echo "    Set defaults.member_mode: api in agents/.ai-council.yml when configuring the council."
+                echo "    Set defaults.member_mode: api in agents/settings/.ai-council.yml when configuring the council."
             fi
         fi
     elif ! $QUIET; then

package/scripts/inventory_frontmatter.py

@@ -10,7 +10,7 @@ YAML frontmatter of every file, and prints per-type:
 - sample values (up to 3) per key
 
 Output is Markdown on stdout, intended to be captured into
-`agents/docs/frontmatter-contract.md` as raw material for Phase 1 of the
+`agents/reference/docs/frontmatter-contract.md` as raw material for Phase 1 of the
 frontmatter-schema roadmap.
 
 Stdlib-only. No PyYAML — we do a simple line-based parse sufficient for

package/scripts/lint_agents_layout.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""CI guard for the `agents/` top-level layout.
+
+The `agents/` tree is the project boundary for memory, roadmaps,
+runtime artefacts, settings, audits, and policies. Flat files at the
+`agents/` root are restricted to a small, intentional whitelist —
+everything else lives in a typed subdirectory (`runtime/`, `settings/`,
+`audits/`, `roadmaps/`, `policies/`, `contexts/`, etc.).
+
+Two layout tiers:
+
+  MAINTAINER (this source repo, identified by ``.agent-src.uncompressed/``)
+      Full `agents/` tree allowed — only the flat-file whitelist is
+      enforced. Phase 4 of road-to-global-only-install keeps the
+      maintainer surface unchanged.
+
+  CONSUMER (any repo without ``.agent-src.uncompressed/``)
+      Global-only target shape: `agents/overrides/` + the bridge
+      marker `agents/.event4u-bridge.yml` are the **only** expected
+      artefacts. Anything else surfaces as a WARNING with a pointer
+      to ``agent-config settings migrate`` (exit code 0). Hard
+      violations (unknown flat files at the root) still fail.
+
+Exit codes:
+  0 — layout is clean (warnings ok in consumer mode).
+  1 — at least one UNKNOWN flat-file violation.
+
+Invocation (from project root):
+  python3 scripts/lint_agents_layout.py
+  python3 scripts/lint_agents_layout.py --quiet
+  python3 scripts/lint_agents_layout.py --strict   # warnings → errors
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+AGENTS_ROOT = Path("agents")
+
+# Intentional flat files at agents/ root. Anything not in this set is
+# UNKNOWN (linter failure). Durable records live under typed subdirs:
+# decisions/ (low-impact corpus, ADR-style records), evidence/ (durable
+# reports / metrics / council artefacts), runtime/ (volatile, gitignored).
+ALLOWED_FLAT_FILES: frozenset[str] = frozenset(
+    {
+        # Entry document — narrative pointer to the agents/ tree.
+        "index.md",
+        # D1 anchor / progress dashboard — kept at root by the
+        # roadmap-progress-sync rule so consumers see it first.
+        "roadmaps-progress.md",
+        # Empty-tree sentinel so agents/ survives a fresh checkout
+        # before any runtime artefact lands.
+        ".gitkeep",
+        # Consumer bridge marker (Phase 4 of road-to-global-only-install).
+        # Spec: docs/contracts/consumer-bridge.md (event4u-bridge/v1).
+        ".event4u-bridge.yml",
+    }
+)
+
+# Consumer-target layout: only these top-level entries are expected in
+# the global-only world. Anything else is a WARNING in consumer mode.
+CONSUMER_EXPECTED_ENTRIES: frozenset[str] = frozenset(
+    {"overrides", ".event4u-bridge.yml", ".gitkeep"},
+)
+
+MIGRATE_HINT = (
+    "Run `agent-config settings migrate` (or `npx @event4u/agent-config "
+    "migrate-to-global`) to move legacy project-scope artefacts under "
+    "`~/.event4u/agent-config/` and leave `agents/overrides/` + "
+    "`agents/.event4u-bridge.yml` as the only consumer-side files."
+)
+
+
+def is_source_repo(project_root: Path) -> bool:
+    """True when running inside the agent-config source repo.
+
+    The maintainer surface is identified by **any** of:
+      - ``.agent-src.uncompressed/`` at the workspace root (legacy / single-pack layout),
+      - ``packages/<pack>/.agent-src.uncompressed/`` (current monorepo layout — see ``AGENTS.md``),
+      - ``.agent-src/`` at the workspace root (compressed authoring tree).
+
+    Consumer repos ship none of these — they only carry the deployed
+    `.augment/`, `.claude/`, etc. plus `agents/overrides/`.
+    """
+    if (project_root / ".agent-src.uncompressed").is_dir():
+        return True
+    if (project_root / ".agent-src").is_dir():
+        return True
+    packages = project_root / "packages"
+    if packages.is_dir():
+        for sub in packages.iterdir():
+            if (sub / ".agent-src.uncompressed").is_dir():
+                return True
+    return False
+
+
+def find_violations(root: Path) -> list[str]:
+    """Return UNKNOWN flat-file violations at the agents/ root."""
+    unknown: list[str] = []
+    if not root.is_dir():
+        return unknown
+
+    for path in sorted(root.iterdir()):
+        if not path.is_file():
+            continue
+        name = path.name
+        if name in ALLOWED_FLAT_FILES:
+            continue
+        unknown.append(
+            f"{path}: flat file not in agents/ whitelist — move to a typed "
+            f"subdirectory (runtime/, evidence/, decisions/, settings/, "
+            f"audits/, roadmaps/, policies/, contexts/, …) or add to "
+            f"ALLOWED_FLAT_FILES in scripts/lint_agents_layout.py with "
+            f"rationale."
+        )
+
+    return unknown
+
+
+def find_consumer_warnings(root: Path) -> list[str]:
+    """Return WARNINGs for consumer repos that hold legacy artefacts.
+
+    Consumer-target shape (Phase 4 of road-to-global-only-install):
+    `agents/overrides/` + `agents/.event4u-bridge.yml` are the only
+    expected entries. Anything else is a soft warning — the linter
+    still exits 0, but the message points the user at the migration
+    subcommand so the legacy directory can be reclaimed.
+    """
+    warnings: list[str] = []
+    if not root.is_dir():
+        return warnings
+
+    for path in sorted(root.iterdir()):
+        if path.name in CONSUMER_EXPECTED_ENTRIES:
+            continue
+        # Flat-file UNKNOWNs are already an error — don't double-count.
+        if path.is_file() and path.name not in ALLOWED_FLAT_FILES:
+            continue
+        kind = "dir" if path.is_dir() else "file"
+        warnings.append(f"{path} ({kind}): legacy artefact outside the consumer-target shape.")
+
+    return warnings
+
+
+def main() -> int:
+    args = sys.argv[1:]
+    strict = "--strict" in args
+    quiet = "--quiet" in args
+
+    project_root = Path.cwd()
+    unknown = find_violations(AGENTS_ROOT)
+    consumer_mode = not is_source_repo(project_root)
+    warnings = find_consumer_warnings(AGENTS_ROOT) if consumer_mode else []
+
+    if unknown:
+        print("❌  agents/ layout violations (unknown flat files):\n")
+        for f in unknown:
+            print(f"  - {f}")
+        print(
+            "\nRule: scripts/lint_agents_layout.py — flat files at agents/ "
+            "root must be whitelisted. Typed subdirectories: runtime/, "
+            "evidence/, decisions/, settings/, audits/, roadmaps/, "
+            "policies/, contexts/, … ."
+        )
+        return 1
+
+    if warnings:
+        if not quiet:
+            print("⚠️  agents/ consumer-shape warnings:\n")
+            for w in warnings:
+                print(f"  - {w}")
+            print(f"\n{MIGRATE_HINT}")
+        if strict:
+            return 1
+
+    if not unknown and not warnings and not quiet:
+        print("✅  agents/ layout clean.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_agents_md.py

@@ -65,7 +65,7 @@ class Target:
 TARGETS = [
     Target(ROOT / "AGENTS.md", "package-root", 3000, 2800, template=False),
     Target(
-        ROOT / ".agent-src.uncompressed" / "templates" / "AGENTS.md",
+        ROOT / "packages" / "core" / ".agent-src.uncompressed" / "templates" / "AGENTS.md",
         "consumer-template", 2500, 2300, template=True,
     ),
 ]

package/scripts/lint_archived_skills.py

@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
-"""Lint archive notes under agents/archived-skills/.
+"""Lint archive notes under agents/evidence/archived-skills/.
 
 Enforces the contract from
 .agent-src.uncompressed/templates/skill-archive-note.md:
 
-  1. Every <slug>.md under agents/archived-skills/ has the six required
+  1. Every <slug>.md under agents/evidence/archived-skills/ has the six required
      frontmatter fields with valid values.
   2. `reason` is one of {unused, merged, superseded, deprecated}.
   3. When `reason ∈ {merged, superseded}` the `replacement` slug exists
@@ -14,7 +14,7 @@ Enforces the contract from
      its frontmatter `replaced_by:` field.
 
 Hooked into `task ci` via `task lint-archived-skills`. Passes cleanly
-against an empty agents/archived-skills/ (only README.md present).
+against an empty agents/evidence/archived-skills/ (only README.md present).
 
 Exit codes:
   0  contract holds
@@ -29,8 +29,16 @@ from pathlib import Path
 QUIET = "--quiet" in sys.argv
 
 REPO = Path(__file__).resolve().parents[1]
-ARCHIVE_DIR = REPO / "agents" / "archived-skills"
-SKILLS_DIR = REPO / ".agent-src.uncompressed" / "skills"
+# Archive notes moved under agents/evidence/ in the privilege-first
+# taxonomy refactor (commit d2ce6748).
+ARCHIVE_DIR = REPO / "agents" / "evidence" / "archived-skills"
+
+# Live skill directories live under every artefact root post-monorepo
+# Phase 4 (legacy + packages/*/.agent-src.uncompressed/skills/).
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+SKILLS_DIRS = [root / "skills" for root in artefact_roots() if (root / "skills").is_dir()]
 
 REQUIRED_FIELDS = ("slug", "archived_on", "last_seen_count", "reason", "replacement", "last_known_callers")
 VALID_REASONS = frozenset({"unused", "merged", "superseded", "deprecated"})
@@ -57,7 +65,13 @@ def archived_slugs() -> list[Path]:
 
 
 def live_skill_slugs() -> set[str]:
-    return {p.name for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists()}
+    slugs: set[str] = set()
+    for skills_dir in SKILLS_DIRS:
+        slugs.update(
+            p.name for p in skills_dir.iterdir()
+            if p.is_dir() and (p / "SKILL.md").exists()
+        )
+    return slugs
 
 
 def main() -> int:
@@ -100,15 +114,16 @@ def main() -> int:
 
         replacement = fm["replacement"]
         reason = fm["reason"]
+        skills_label = ", ".join(str(d) for d in SKILLS_DIRS) or "<no skills root>"
         if reason in {"merged", "superseded"}:
             if replacement == "none" or not replacement:
                 errors.append(f"{note.name}: reason={reason} requires a replacement slug, got 'none'")
             elif replacement not in live:
-                errors.append(f"{note.name}: replacement '{replacement}' not found under {SKILLS_DIR}")
+                errors.append(f"{note.name}: replacement '{replacement}' not found under {skills_label}")
         elif reason in {"unused", "deprecated"}:
             if replacement not in {"none", ""}:
                 if replacement not in live:
-                    errors.append(f"{note.name}: replacement '{replacement}' not found under {SKILLS_DIR}")
+                    errors.append(f"{note.name}: replacement '{replacement}' not found under {skills_label}")
 
         if fm["slug"] in live:
             errors.append(f"{note.name}: slug '{fm['slug']}' still has a live SKILL.md (zombie)")
@@ -116,17 +131,18 @@ def main() -> int:
         archived_keys.add(fm["slug"])
 
     # Cross-check: live skills must not list an archived slug as replaced_by.
-    for skill_dir in sorted(SKILLS_DIR.iterdir()):
-        skill_md = skill_dir / "SKILL.md"
-        if not skill_md.exists():
-            continue
-        text = skill_md.read_text(encoding="utf-8")
-        fm = parse_frontmatter(text)
-        if fm is None:
-            continue
-        rb = fm.get("replaced_by", "").strip()
-        if rb and rb in archived_keys:
-            errors.append(f"{skill_dir.name}/SKILL.md: replaced_by '{rb}' points at an archived slug")
+    for skills_dir in SKILLS_DIRS:
+        for skill_dir in sorted(skills_dir.iterdir()):
+            skill_md = skill_dir / "SKILL.md"
+            if not skill_md.exists():
+                continue
+            text = skill_md.read_text(encoding="utf-8")
+            fm = parse_frontmatter(text)
+            if fm is None:
+                continue
+            rb = fm.get("replaced_by", "").strip()
+            if rb and rb in archived_keys:
+                errors.append(f"{skill_dir.name}/SKILL.md: replaced_by '{rb}' points at an archived slug")
 
     if errors:
         print(f"❌  lint_archived_skills: {len(errors)} violation(s) across {len(notes)} note(s)", file=sys.stderr)