@event4u/agent-config 5.6.1 → 5.8.0

package/scripts/install.py

@@ -12,13 +12,15 @@ format in `.agent-settings.yml`, leaves a one-shot backup as
 exactly once; subsequent runs are idempotent.
 
 Usage:
-  python3 scripts/install.py                     # defaults: cost_profile=balanced
-  python3 scripts/install.py --profile=minimal   # set cost_profile=minimal (kernel only)
-  python3 scripts/install.py --force             # overwrite existing files
+  python3 scripts/install.py                     # defaults: rule_loading_tier=balanced
+  python3 scripts/install.py --profile=minimal   # set rule_loading_tier=minimal (kernel only)
+  python3 scripts/install.py --force             # accepted (no-op): installs always overwrite
   python3 scripts/install.py --skip-bridges      # only create .agent-settings.yml
   python3 scripts/install.py --project <dir>     # override project root
 
-Idempotent — safe to run multiple times. Never overwrites files without --force.
+Idempotent — safe to run multiple times. A run always refreshes every
+deployed file with the current package content; user configuration
+(.agent-settings.yml) is merged by the settings layer, never clobbered.
 Zero dependencies — standard library only.
 """
 
@@ -48,24 +50,40 @@ except ImportError:  # pragma: no cover — alt sys.path layout
 
 DEFAULT_PROFILE = "balanced"
 SUPPORTED_PROFILES = ("minimal", "balanced", "full")
-COST_PROFILE_PLACEHOLDER = "__COST_PROFILE__"
+RULE_LOADING_TIER_PLACEHOLDER = "__RULE_LOADING_TIER__"
 USER_TYPE_PLACEHOLDER = "__USER_TYPE__"
 USER_TYPES_DIR = "user-types"
 
-# Env-var equivalent of --force for CI / scripted installs (P3.4).
-# When set to "1" the install run treats every conflict as
-# force-overwrite; never enabled by default to keep destructive writes
-# explicit.
-ALLOW_OVERWRITE_ENV = "AGENT_CONFIG_ALLOW_OVERWRITE"
-
 SETTINGS_FILE = ".agent-settings.yml"
 LEGACY_SETTINGS_FILE = ".agent-settings"
 LEGACY_BACKUP_FILE = ".agent-settings.backup.key-value"
 
+# Canonical project settings live in the settings layer (agents/settings/),
+# not at the repo root (ADR-038). The repo-root .agent-settings.yml is a
+# back-compat read-fallback that install migrates into the canonical
+# location. Kept inline (no package import) — install.py runs standalone.
+SETTINGS_SUBDIR = ("agents", "settings")
+
+
+def _canonical_settings_target(project_root: Path) -> Path:
+    """Canonical write target: <root>/agents/settings/.agent-settings.yml."""
+    return project_root.joinpath(*SETTINGS_SUBDIR, SETTINGS_FILE)
+
+
+def _resolve_settings_read(project_root: Path) -> Path:
+    """Canonical if present, else legacy repo-root file if present, else canonical."""
+    canonical = _canonical_settings_target(project_root)
+    if canonical.exists():
+        return canonical
+    legacy = project_root / SETTINGS_FILE
+    if legacy.exists():
+        return legacy
+    return canonical
+
 # Maps legacy flat keys (.agent-settings, key=value) to the new dotted YAML
 # paths in .agent-settings.yml. Applied once during auto-migration.
 LEGACY_RENAME_MAP = {
-    "cost_profile": "cost_profile",
+    "cost_profile": "rule_loading_tier",
     "ide": "personal.ide",
     "open_edited_files": "personal.open_edited_files",
     "user_name": "personal.user_name",
@@ -190,222 +208,38 @@ def detect_package_type_for_project(project_root: Path, package_root: Path) -> s
     return detect_package_type(package_root)
 
 
-# --- Conflict detection (P3.1 / P3.3) ---
-
-class ConflictAbort(SystemExit):
-    """Raised when a conflict resolution chose 'abort'.
-
-    Inherits ``SystemExit`` so an unhandled abort terminates the
-    install with a non-zero exit code without an opaque traceback.
-    """
-
-    def __init__(self, message: str):
-        super().__init__(1)
-        self.message = message
-
-
-class ConflictPolicy:
-    """Per-install conflict resolution policy (P3.1).
-
-    Aggregates the inputs the resolver needs to decide whether to
-    overwrite a target that exists on disk:
-
-    * ``force``         — true when ``--force`` was passed OR the
-      ``AGENT_CONFIG_ALLOW_OVERWRITE=1`` env-var is set (P3.4).
-    * ``interactive``   — true when stdin AND stdout are TTYs; the
-      only context where the 3-option prompt is meaningful.
-    * ``known_paths``   — absolute path strings recorded as ours by
-      the project-scope manifest (``files[]`` entries). A target at a
-      known path is **not** a foreign collision — we own it and the
-      existing skip/force behaviour applies.
-    * ``known_pointers``— ``(file_label, json_pointer)`` pairs we
-      previously merged into shared JSON files (P3.3). A pointer in
-      this set is ours; one not in it that exists in the target is a
-      foreign merge collision.
-    """
-
-    __slots__ = ("force", "interactive", "known_paths", "known_pointers")
-
-    def __init__(
-        self,
-        *,
-        force: bool,
-        interactive: bool,
-        known_paths: set[str],
-        known_pointers: set[tuple[str, str]],
-    ) -> None:
-        self.force = force
-        self.interactive = interactive
-        self.known_paths = known_paths
-        self.known_pointers = known_pointers
-
-
-# Module-level singleton: configured once in main() (after --force +
-# env-var resolution), consulted by every writer. When ``None`` the
-# install runs in **legacy mode**: writers honor their local ``force``
-# flag and skip-otherwise, no foreign-pointer detection. Set only by
-# :func:`main` after loading the manifest so test callers that exercise
-# writers directly keep the pre-P3 contract.
-_CONFLICT_POLICY: Optional[ConflictPolicy] = None
-
-
-def _conflict_policy_active() -> bool:
-    return _CONFLICT_POLICY is not None
-
-
-def _get_conflict_policy() -> ConflictPolicy:
-    if _CONFLICT_POLICY is None:
-        # Legacy-mode fallback: no manifest loaded, no foreign detection
-        # surface. ``force=False`` here so the local ``force_hint`` from
-        # the caller is the only signal; ``known_*`` stay empty.
-        return ConflictPolicy(
-            force=False, interactive=False,
-            known_paths=set(), known_pointers=set(),
-        )
-    return _CONFLICT_POLICY
-
-
-def _set_conflict_policy(policy: Optional[ConflictPolicy]) -> None:
-    global _CONFLICT_POLICY
-    _CONFLICT_POLICY = policy
-
-
-def _allow_overwrite_env() -> bool:
-    return os.environ.get(ALLOW_OVERWRITE_ENV) == "1"
+# --- Conflict resolution ---
+#
+# A setup deploys our own files into our own layout. Every path the
+# installer writes comes from our source tree, so a deliberate run
+# always lays down the current package content — there is no "foreign"
+# file to protect (a path missing from the manifest is simply our own
+# file from an older install). User configuration (.agent-settings.yml)
+# is merged by the settings layer, never clobbered here.
 
 
 def _is_interactive() -> bool:
+    """True when stdin AND stdout are TTYs (interactive prompts are safe)."""
     try:
         return sys.stdin.isatty() and sys.stdout.isatty()
     except (AttributeError, ValueError):  # pragma: no cover — closed streams
         return False
 
 
-def _load_conflict_policy(project_root: Path, force: bool) -> ConflictPolicy:
-    """Build a :class:`ConflictPolicy` from the on-disk manifest.
-
-    Reads ``agents/installed-tools.lock`` once and folds every recorded
-    ``files[].path`` into ``known_paths`` and every
-    ``merged_keys[].{file, json_pointer}`` into ``known_pointers``. The
-    manifest is the only source of truth for "this is ours"; if it's
-    missing both sets stay empty and every existing target is treated
-    as foreign.
-    """
-    known_paths: set[str] = set()
-    known_pointers: set[tuple[str, str]] = set()
-    try:
-        tools_mod = _load_installed_tools_module()
-        target = tools_mod.manifest_path(project_root)
-        existing = tools_mod.read_manifest(target) or {}
-        for tool in existing.get("tools", []) or []:
-            for entry in tool.get("files", []) or []:
-                path_val = entry.get("path")
-                if isinstance(path_val, str) and path_val:
-                    # Manifest paths may be absolute (production writers
-                    # use ``str(Path)`` for ``files[].path``) or relative
-                    # (portable manifests). Writers always pass absolute
-                    # ``Path`` objects to ``_resolve_file_conflict``, so
-                    # normalise here against ``project_root`` to keep the
-                    # known-path silent-skip branch reachable.
-                    p = Path(path_val)
-                    if not p.is_absolute():
-                        p = (project_root / p).resolve()
-                    known_paths.add(str(p))
-            for entry in tool.get("merged_keys", []) or []:
-                file_label = entry.get("file")
-                pointer = entry.get("json_pointer")
-                if isinstance(file_label, str) and isinstance(pointer, str):
-                    known_pointers.add((file_label, pointer))
-    except Exception:  # pragma: no cover — fail-open on corrupt manifest
-        # Don't block the install if the manifest is malformed; just
-        # report nothing as ours so foreign-file detection stays strict.
-        pass
-    return ConflictPolicy(
-        force=force or _allow_overwrite_env(),
-        interactive=_is_interactive(),
-        known_paths=known_paths,
-        known_pointers=known_pointers,
-    )
-
-
-def prompt_file_conflict_choice(path: Path) -> str:
-    """3-option resolution prompt for a foreign file at ``path``.
-
-    Returns ``"force"`` / ``"skip"`` / ``"abort"``. Mirrors
-    :func:`prompt_collision_choice` (loops on invalid input, aborts on
-    EOF or 3 invalid replies). Only called when the policy is
-    interactive AND ``--force`` was not specified.
-    """
-    print()
-    warn(f"Foreign file at {path}")
-    info("This path exists but is not recorded as ours in the manifest.")
-    info("Choose how to handle the conflict:")
-    print("  1) Force   — overwrite the file with our content")
-    print("  2) Skip    — leave the file untouched, continue install")
-    print("  3) Abort   — stop the install, exit non-zero")
-    print()
-    attempts = 0
-    while attempts < 3:
-        try:
-            reply = _read_line("Choose [1/2/3]: ")
-        except EOFError:
-            fail(f"File-conflict prompt aborted (EOF on stdin) for {path}")
-        if reply in ("1", "force", "f"):
-            return "force"
-        if reply in ("2", "skip", "s"):
-            return "skip"
-        if reply in ("3", "abort", "a"):
-            return "abort"
-        attempts += 1
-        warn(f"Invalid choice '{reply}'. Enter 1, 2, or 3.")
-    fail(f"File-conflict prompt aborted (3 invalid replies) for {path}")
-    return "abort"  # unreachable
-
-
 def _resolve_file_conflict(target: Path, *, force_hint: bool) -> str:
-    """Decide what to do when ``target`` already exists on disk.
-
-    Returns ``"write"`` (proceed with overwrite), ``"skip"`` (leave the
-    target alone), or raises :class:`ConflictAbort`. ``force_hint`` is
-    the caller's local ``force`` flag — typically the install-level
-    ``--force``; we OR it with the global policy's ``force`` to honor
-    ``AGENT_CONFIG_ALLOW_OVERWRITE=1`` in callers that have not yet
-    been refactored to read the policy directly.
-
-    Decision matrix:
-
-    * target does not exist          → ``"write"``
-    * target IS in ``known_paths``   → ``"write"`` if force else ``"skip"``
-      (legacy behaviour — we own it, skip silently without --force)
-    * target NOT in ``known_paths`` (foreign):
-        * force                       → ``"write"`` (overwrite)
-        * interactive                 → prompt → translate to write/skip/abort
-        * non-interactive             → raise ``ConflictAbort``
+    """Whole-file deploy is always an overwrite of OUR own content.
+
+    Every ``target`` reaching this function comes from
+    :func:`_copy_dir_dereferencing_symlinks` — a file we ship being
+    written into our own layout. A setup the user deliberately ran
+    applies the latest package content unconditionally, so there is no
+    "skip" or "abort": the user runs the installer because they want it
+    applied. ``force_hint`` is retained for call-site stability but no
+    longer gates the write.
     """
-    if not target.exists():
-        return "write"
-    if not _conflict_policy_active():
-        # Legacy mode (no manifest loaded): preserve the pre-P3 contract
-        # — force overwrites, otherwise skip. No prompt, no abort.
-        return "write" if force_hint else "skip"
-    policy = _get_conflict_policy()
-    effective_force = force_hint or policy.force
-    if str(target) in policy.known_paths:
-        return "write" if effective_force else "skip"
-    if effective_force:
-        return "write"
-    if policy.interactive:
-        choice = prompt_file_conflict_choice(target)
-        if choice == "force":
-            return "write"
-        if choice == "skip":
-            return "skip"
-        raise ConflictAbort(f"User aborted on foreign file at {target}")
-    raise ConflictAbort(
-        f"Foreign file at {target}: refusing to overwrite. "
-        f"Re-run with --force or set {ALLOW_OVERWRITE_ENV}=1 to allow. "
-        f"Run `agent-config doctor` to inspect orphaned files first."
-    )
+    del force_hint  # deploys always overwrite; the flag never gates a write
+    del target  # existence no longer changes the decision
+    return "write"
 
 
 # --- File utilities ---
@@ -447,143 +281,24 @@ def deep_merge(base: dict, overlay: dict) -> dict:
     return result
 
 
-def _pointer_target_exists(doc: dict, pointer: str) -> bool:
-    """Return True when ``pointer`` resolves to an existing key in ``doc``.
-
-    Walks the RFC-6901 segments without descending into lists (per the
-    array-index ban in :mod:`scripts._lib.json_pointers`). Missing
-    intermediate segments short-circuit to False.
-    """
-    if not pointer.startswith("/"):
-        return False
-    cursor: Any = doc
-    segments = pointer.split("/")[1:]
-    segments = [s.replace("~1", "/").replace("~0", "~") for s in segments]
-    for seg in segments[:-1]:
-        if not isinstance(cursor, dict) or seg not in cursor:
-            return False
-        cursor = cursor[seg]
-    if not isinstance(cursor, dict):
-        return False
-    return segments[-1] in cursor
-
-
-def _detect_foreign_pointers(
-    existing: dict,
-    overlay_entries: list[dict[str, Any]],
-    label: str,
-    policy: ConflictPolicy,
-) -> list[str]:
-    """Return overlay pointers that exist in ``existing`` but aren't ours.
-
-    P3.3 — pointer-level foreign-merge detection. A pointer is foreign
-    when it would overwrite a value already on disk that the manifest
-    does NOT record as ours (``(label, pointer) not in known_pointers``).
-    Returns the list of foreign pointer strings (sorted, deduped) for
-    use in the conflict-resolution prompt. In legacy mode (no manifest
-    loaded) the function returns an empty list so callers fall back to
-    the pre-P3 update flow.
-    """
-    if not _conflict_policy_active():
-        return []
-    foreign: list[str] = []
-    seen: set[str] = set()
-    for entry in overlay_entries:
-        pointer = entry.get("json_pointer")
-        if not isinstance(pointer, str) or pointer in seen:
-            continue
-        seen.add(pointer)
-        if not _pointer_target_exists(existing, pointer):
-            continue
-        if (label, pointer) in policy.known_pointers:
-            continue
-        foreign.append(pointer)
-    foreign.sort()
-    return foreign
-
-
-def prompt_json_conflict_choice(path: Path, foreign: list[str]) -> str:
-    """3-option resolution prompt for foreign JSON pointers at ``path``.
-
-    Returns ``"force"`` / ``"skip"`` / ``"abort"``. Shows the foreign
-    pointer list so the user knows what will be overwritten.
-    """
-    print()
-    warn(f"Foreign JSON keys at {path}")
-    info("The following pointers exist in the file but are not recorded as ours:")
-    for pointer in foreign[:10]:
-        print(f"      {pointer}")
-    if len(foreign) > 10:
-        print(f"      ... and {len(foreign) - 10} more")
-    info("Choose how to handle the conflict:")
-    print("  1) Force   — overwrite the listed pointers with our values")
-    print("  2) Skip    — leave the file untouched, continue install")
-    print("  3) Abort   — stop the install, exit non-zero")
-    print()
-    attempts = 0
-    while attempts < 3:
-        try:
-            reply = _read_line("Choose [1/2/3]: ")
-        except EOFError:
-            fail(f"JSON-conflict prompt aborted (EOF on stdin) for {path}")
-        if reply in ("1", "force", "f"):
-            return "force"
-        if reply in ("2", "skip", "s"):
-            return "skip"
-        if reply in ("3", "abort", "a"):
-            return "abort"
-        attempts += 1
-        warn(f"Invalid choice '{reply}'. Enter 1, 2, or 3.")
-    fail(f"JSON-conflict prompt aborted (3 invalid replies) for {path}")
-    return "abort"  # unreachable
-
-
-def _resolve_json_conflict(
-    path: Path, label: str, foreign: list[str], *, force_hint: bool,
-) -> str:
-    """Decide what to do when ``label`` has foreign pointers (P3.3).
-
-    Returns ``"write"`` or ``"skip"``; raises :class:`ConflictAbort`.
-    Same resolution matrix as :func:`_resolve_file_conflict` but with a
-    pointer-aware prompt.
-    """
-    policy = _get_conflict_policy()
-    effective_force = force_hint or policy.force
-    if effective_force:
-        return "write"
-    if policy.interactive:
-        choice = prompt_json_conflict_choice(path, foreign)
-        if choice == "force":
-            return "write"
-        if choice == "skip":
-            return "skip"
-        raise ConflictAbort(f"User aborted on foreign JSON pointers at {path}")
-    raise ConflictAbort(
-        f"Foreign JSON pointers at {path}: refusing to overwrite "
-        f"({len(foreign)} key(s)). Re-run with --force or set "
-        f"{ALLOW_OVERWRITE_ENV}=1 to allow. "
-        f"Run `agent-config doctor` to inspect orphaned pointers first."
-    )
-
-
 def merge_json_file(
     path: Path, new_data: dict, force: bool, label: str,
 ) -> list[dict[str, Any]]:
     """Merge ``new_data`` into ``path``; return v2 ``merged_keys[]`` entries.
 
-    P1.5 + P3.2 + P3.3 of road-to-multi-package-coexistence: every JSON
-    pointer the install writes lands in the manifest so uninstall can
-    subtract it cleanly. The merge uses leaf-level pointer-replace
-    semantics (``deep_merge`` recurses into dicts, replaces at leaves)
-    so sibling keys owned by neighbour packages survive. Before any
-    write that would overwrite a pre-existing pointer NOT recorded as
-    ours, the conflict policy is consulted (force / interactive prompt
-    / non-interactive abort).
-
-    Returns the v2 entries on a successful create / update; returns
-    ``[]`` when the file was already in sync or the update was
-    suppressed without ``--force`` / on a skip choice.
+    P1.5 of road-to-multi-package-coexistence: every JSON pointer the
+    install writes lands in the manifest so uninstall can subtract it
+    cleanly. The merge uses leaf-level pointer-replace semantics
+    (``deep_merge`` recurses into dicts, replaces at leaves) so sibling
+    keys owned by neighbour packages survive untouched — our overlay
+    only ever carries our own keys. A deliberate setup always applies
+    those keys (no ``--force`` gate, no abort); ``force`` is retained
+    for call-site compatibility only.
+
+    Returns the v2 entries on a create / update; ``[]`` when the file
+    was already in sync.
     """
+    del force  # our keys are always applied; the flag never gates a write
     new_entries = build_merge_entries(label, new_data)
 
     if not path.exists():
@@ -598,24 +313,6 @@ def merge_json_file(
         skip(f"{label} already configured")
         return new_entries
 
-    policy = _get_conflict_policy()
-    foreign = _detect_foreign_pointers(existing, new_entries, label, policy)
-
-    if foreign:
-        # Foreign-pointer collision: ask the policy. On "write" we fall
-        # through and let deep_merge produce the leaf-level pointer-
-        # replace; on "skip" we bail without changing the file.
-        decision = _resolve_json_conflict(path, label, foreign, force_hint=force)
-        if decision == "skip":
-            skip(f"{label} has foreign keys, skipped")
-            return []
-    elif not (force or policy.force):
-        # No foreign collision but file needs an update — preserve the
-        # legacy "needs --force" contract so existing test expectations
-        # and the project-bridge flow stay intact.
-        skip(f"{label} exists, needs update (use --force)")
-        return []
-
     write_json_file(path, merged)
     success(f"{label} updated")
     return new_entries
@@ -858,7 +555,7 @@ def _validate_user_type(package_root: Path, value: str) -> str:
 def _inject_packs(body: str, packs: "list[str]") -> str:
     """Insert a top-level ``packs:`` block into a rendered settings body.
 
-    Inserted directly after the ``cost_profile:`` line so the active pack
+    Inserted directly after the ``rule_loading_tier:`` line so the active pack
     selection sits beside the other install-time knobs. No-op when ``packs``
     is empty — non-pack installs stay byte-identical to the template render.
     """
@@ -870,13 +567,13 @@ def _inject_packs(body: str, packs: "list[str]") -> str:
     inserted = False
     for line in lines:
         out.append(line)
-        if not inserted and line.startswith("cost_profile:"):
+        if not inserted and line.startswith("rule_loading_tier:"):
             if not line.endswith("\n"):
                 out[-1] = line + "\n"
             out.append(block)
             inserted = True
     if not inserted:
-        # No cost_profile anchor (unexpected) — append at the end so the
+        # No rule_loading_tier anchor (unexpected) — append at the end so the
         # selection is still recorded rather than silently dropped.
         if out and not out[-1].endswith("\n"):
             out[-1] = out[-1] + "\n"
@@ -892,7 +589,7 @@ def ensure_agent_settings(
     user_type: str = "",
     packs: "list[str] | None" = None,
 ) -> None:
-    target = project_root / SETTINGS_FILE
+    target = _canonical_settings_target(project_root)
     profile_source = package_root / "config" / "profiles" / f"{profile}.ini"
     template_source = package_root / "config" / "agent-settings.template.yml"
 
@@ -902,21 +599,32 @@ def ensure_agent_settings(
         fail(f"Missing settings template: {template_source}")
 
     template = template_source.read_text(encoding="utf-8")
-    if COST_PROFILE_PLACEHOLDER not in template:
-        fail(f"Template is missing placeholder {COST_PROFILE_PLACEHOLDER}")
+    if RULE_LOADING_TIER_PLACEHOLDER not in template:
+        fail(f"Template is missing placeholder {RULE_LOADING_TIER_PLACEHOLDER}")
     if USER_TYPE_PLACEHOLDER not in template:
         fail(f"Template is missing placeholder {USER_TYPE_PLACEHOLDER}")
     profile_values = _parse_profile_ini(profile_source)
-    if profile_values.get("cost_profile") != profile:
+    if profile_values.get("rule_loading_tier") != profile:
         fail(
-            f"Profile preset {profile_source.name} has cost_profile="
-            f"{profile_values.get('cost_profile')!r} but --profile={profile}"
+            f"Profile preset {profile_source.name} has rule_loading_tier="
+            f"{profile_values.get('rule_loading_tier')!r} but --profile={profile}"
         )
     # Inject runtime-only values (not part of the .ini profile presets).
     profile_values["user_type"] = _validate_user_type(package_root, user_type)
     template_body = _render_template(template, profile_values)
     template_body = _inject_packs(template_body, packs or [])
 
+    # ADR-038: relocate an existing repo-root .agent-settings.yml into the
+    # canonical agents/settings/ location, preserving the developer's content
+    # (never clobber an already-canonical file).
+    legacy_root = project_root / SETTINGS_FILE
+    if legacy_root.is_file() and not target.exists():
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(legacy_root.read_text(encoding="utf-8"), encoding="utf-8")
+        legacy_root.unlink()
+        success(f"Migrated {SETTINGS_FILE} → agents/settings/{SETTINGS_FILE} (ADR-038)")
+        return
+
     legacy_target = project_root / LEGACY_SETTINGS_FILE
     if legacy_target.is_file() and target.exists():
         warn(
@@ -936,10 +644,11 @@ def ensure_agent_settings(
         skip(f"{SETTINGS_FILE} already exists")
         return
 
+    target.parent.mkdir(parents=True, exist_ok=True)
     write_file(target, template_body)
     user_type_value = profile_values.get("user_type", "")
     suffix = f", user_type={user_type_value}" if user_type_value else ""
-    success(f"{SETTINGS_FILE} created (cost_profile={profile}{suffix})")
+    success(f"{SETTINGS_FILE} created (rule_loading_tier={profile}{suffix})")
 
 
 def ensure_vscode_bridge(project_root: Path, package_type: str, force: bool) -> None:
@@ -2453,6 +2162,41 @@ def _enforce_consumer_global_only(scope: str) -> None:
     )
 
 
+def _enforce_not_source_repo(scope: str, project_root: Path) -> None:
+    """Refuse a non-global install into the agent-config source repo.
+
+    Python-side mirror of the bash orchestrator's "Source-repo guard"
+    (``scripts/install``). The bash guard only covers the headless
+    ``init`` front door; the wizard reaches the apply engine directly via
+    ``install.py --apply-payload`` (and maintainers can call
+    ``python3 scripts/install.py``), so without this the GUI path could
+    write the ``.augment/`` / ``.claude/`` / ``.cursor/`` projection trees
+    back into the checkout. Both front doors converge on ``main()`` here, so
+    this is the single chokepoint that makes the floor uniform.
+
+    ``--global`` only writes user-scope paths and never the source tree, so
+    it is exempt. Unlike :func:`_enforce_consumer_global_only`, dev-mode does
+    NOT lift this guard — dogfooding bridges into the source tree is an
+    explicit action gated by its own ``AGENT_CONFIG_ALLOW_SELF_INSTALL=1``
+    override (same flag the bash guard honours).
+    """
+    if scope == "global":
+        return
+    if os.environ.get("AGENT_CONFIG_ALLOW_SELF_INSTALL") == "1":
+        return
+    is_source, signature = _is_agent_config_source_repo(project_root)
+    if not is_source:
+        return
+    fail(
+        "Refusing to install agent-config into its own source checkout "
+        f"(detected: {signature}). The source repo is global-only — a "
+        "project-scope install would recreate the .augment/ .claude/ .cursor/ "
+        "projection trees in the repo (double token cost). Run `task sync` to "
+        "regenerate them from .agent-src.uncondensed/ instead, or set "
+        "AGENT_CONFIG_ALLOW_SELF_INSTALL=1 to force."
+    )
+
+
 # --- road-to-global-only-install § Phase 2.2 — three-layer settings reader ---
 #
 # Merge order (per ADR-020 / D9):
@@ -2499,11 +2243,11 @@ def _load_yaml_doc(path: Path) -> dict:
 def _load_default_settings(package_root: Path) -> dict:
     """Parse the rendered settings template into a defaults dict.
 
-    The template carries ``__COST_PROFILE__`` / ``__USER_TYPE__``
+    The template carries ``__RULE_LOADING_TIER__`` / ``__USER_TYPE__``
     placeholders that PyYAML cannot parse as scalars. We substitute the
     most permissive defaults (``balanced`` + empty user_type) before
     parsing — the resulting tree is the *defaults* layer of the merge,
-    and downstream layers overwrite cost_profile / user_type as needed.
+    and downstream layers overwrite rule_loading_tier / user_type as needed.
     """
     template_source = package_root / "config" / "agent-settings.template.yml"
     if not template_source.exists():
@@ -2512,7 +2256,7 @@ def _load_default_settings(package_root: Path) -> dict:
         text = template_source.read_text(encoding="utf-8")
     except OSError:
         return {}
-    rendered = text.replace(COST_PROFILE_PLACEHOLDER, DEFAULT_PROFILE).replace(
+    rendered = text.replace(RULE_LOADING_TIER_PLACEHOLDER, DEFAULT_PROFILE).replace(
         USER_TYPE_PLACEHOLDER, ""
     )
     try:
@@ -2544,7 +2288,7 @@ def read_layered_settings(
     merged = _load_default_settings(package_root)
     merged = deep_merge(merged, _load_yaml_doc(GLOBAL_AGENT_SETTINGS_PATH))
     if project_root is not None:
-        project_file = project_root / SETTINGS_FILE
+        project_file = _resolve_settings_read(project_root)
         merged = deep_merge(merged, _load_yaml_doc(project_file))
     return merged
 
@@ -2679,7 +2423,7 @@ def detect_scope(cwd: Path) -> tuple[str, str]:
     ``.git/`` is explicitly NOT a signal — monorepos, dotfile managers,
     and non-Git workspaces all break it. Pure function; no side effects.
     """
-    if (cwd / SETTINGS_FILE).exists():
+    if _resolve_settings_read(cwd).exists():
         return "project", f"existing {SETTINGS_FILE}"
 
     has_manifest = next(
@@ -3840,8 +3584,6 @@ def install_global(
                 print(f"      {tool_id:<15} → no user-scope convention; use `agent-config export --tool={tool_id}`")
             else:
                 print(f"      {tool_id:<15} → no global-scope content yet (project-scope install supported)")
-        if not force and any(s > 0 for _, s, _, _ in deploy_results.values()):
-            info("  Re-run with --force to overwrite existing files.")
 
     # Refresh the project-scope manifest when running inside a project tree
     # (ADR-008 Phase 3.2). Outside a project (e.g. plain `~/`) there is no
@@ -3851,7 +3593,7 @@ def install_global(
     # `.agent-settings.yml` and the manifest would be untracked noise.
     if (
         project_root is not None
-        and (project_root / SETTINGS_FILE).exists()
+        and _resolve_settings_read(project_root).exists()
         and not (project_root / ".agent-src.uncondensed").is_dir()
     ):
         # Collect deployed/marker paths per tool so the manifest records
@@ -3934,7 +3676,7 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
     parser.add_argument(
         "--profile",
         default=DEFAULT_PROFILE,
-        help=f"cost_profile value ({'|'.join(SUPPORTED_PROFILES)}, default: {DEFAULT_PROFILE})",
+        help=f"rule_loading_tier value ({'|'.join(SUPPORTED_PROFILES)}, default: {DEFAULT_PROFILE})",
     )
     parser.add_argument(
         "--user-type",
@@ -3947,7 +3689,7 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
             "surfaces). Written to personal.user_type in .agent-settings.yml."
         ),
     )
-    parser.add_argument("--force", action="store_true", help="overwrite existing files")
+    parser.add_argument("--force", action="store_true", help="accepted for back-compat (no-op): installs always overwrite deployed files")
     parser.add_argument("--skip-bridges", action="store_true", help="only create .agent-settings.yml")
     parser.add_argument(
         "--augment-user-hooks",
@@ -4316,7 +4058,7 @@ def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
     # the source of truth per ADR-020 § D2; a fresh `--minimal` run
     # without user_type does not write a project-local settings file.
     if user_type:
-        settings_dst = target_root / SETTINGS_FILE
+        settings_dst = _canonical_settings_target(target_root)
         if settings_dst.exists() and not force:
             skip(f"{SETTINGS_FILE} already exists (use --force to overwrite)")
         else:
@@ -4325,6 +4067,7 @@ def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
                 "personal:\n"
                 f"  user_type: {user_type}\n"
             )
+            settings_dst.parent.mkdir(parents=True, exist_ok=True)
             settings_dst.write_text(body, encoding="utf-8")
             success(f"Wrote {SETTINGS_FILE} (user_type={user_type})")
 
@@ -4617,13 +4360,23 @@ def _kill_stale_wizard_server() -> None:
     print("(Stopped the previous wizard server.)")
 
 
-def _wizard_spawn(project_root: Path) -> int:
+def _wizard_spawn(project_root: Path, *, pass_project_root: bool = True) -> int:
     """Spawn the wizard, await readiness, hand off to the child.
 
     Returns the child's exit code on clean shutdown, 0 on
     readiness-timeout (install itself succeeded; wizard is best-effort).
     Never raises into the parent — every error surfaces as a printed
     fallback line and a 0 return.
+
+    ``pass_project_root`` forwards ``--project-root`` to the child so the
+    wizard's write root is the consumer project. Set it ``False`` on the
+    global install path: ``--project-root`` would override the write root
+    to the project (project mode), so the wizard would neither read nor
+    write the **global** ``~/.event4u/agent-config/settings/.agent-user.yml``
+    (the saved identity) — and writing global content into the project
+    tree violates ADR-020. Omitting it lets ``resolveWriteRoot`` pick the
+    global root, so a returning user's name/language pre-fill from the
+    saved identity instead of the OS account.
     """
     # Always start fresh: stop any server left running by a prior init.
     _kill_stale_wizard_server()
@@ -4641,7 +4394,9 @@ def _wizard_spawn(project_root: Path) -> int:
     # charge of the user-facing URL print (Tier 2 § 8 ordering) — the dead
     # `gui` subcommand + AGENT_CONFIG_GUI_NO_OPEN env were retired in
     # road-to-single-install-source-of-truth § Phase 4.
-    cmd = ["node", str(cli), "install", "--no-open", "--project-root", str(project_root)]
+    cmd = ["node", str(cli), "install", "--no-open"]
+    if pass_project_root:
+        cmd += ["--project-root", str(project_root)]
     env = os.environ.copy()
 
     try:
@@ -4733,6 +4488,17 @@ def _wizard_await_ready(
 
     print()
     print(f"Setup wizard ready: {matched_url}")
+    # Actually open the browser. The child is spawned with --no-open so the
+    # Python parent owns the URL print (ordering); it must also own the
+    # open, or the wizard never surfaces and the user is left staring at a
+    # URL. Best-effort: webbrowser.open returns False on a headless host
+    # (no DISPLAY / no default handler) — we keep the printed URL as the
+    # fallback and never raise into the install flow.
+    try:
+        import webbrowser
+        webbrowser.open(matched_url)
+    except Exception:  # noqa: BLE001 - opening is best-effort, never fatal
+        pass
     print("(Wizard runs in the background; close the tab or press Ctrl-C to stop.)")
     try:
         return child.wait()
@@ -4862,9 +4628,10 @@ def main(argv: list[str]) -> int:
             # commit, not by install.py.
             settings = payload.get("settings") or {}
             if isinstance(settings, dict):
-                cost_profile = settings.get("cost_profile")
-                if isinstance(cost_profile, str) and cost_profile:
-                    opts.profile = cost_profile
+                # Legacy fallback: pre-untangle installs carry cost_profile.
+                rule_loading_tier = settings.get("rule_loading_tier") or settings.get("cost_profile")
+                if isinstance(rule_loading_tier, str) and rule_loading_tier:
+                    opts.profile = rule_loading_tier
                 personal = settings.get("personal")
                 if isinstance(personal, dict):
                     user_type = personal.get("user_type")
@@ -4960,6 +4727,7 @@ def main(argv: list[str]) -> int:
     custom_path: Path | None = Path(opts.custom_path).resolve() if opts.custom_path else None
     scope = _resolve_scope(opts, detected, detect_reason, custom_path)
     _enforce_consumer_global_only(scope)
+    _enforce_not_source_repo(scope, detect_root)
 
     # Scope validation runs before filesystem / package detection so
     # --tools=X / --scope conflicts fail fast with a directive error
@@ -4968,48 +4736,51 @@ def main(argv: list[str]) -> int:
     tools_was_all = _tools_was_all(opts.tools)
     parsed_tools = _validate_scope(parsed_tools, scope, tools_was_all)
 
-    # Conflict policy: load known paths/pointers from the manifest once
-    # so every writer can ask "is this ours?" before clobbering (P3.1 /
-    # P3.3). Built from the project-scope manifest because that's the
-    # only on-disk source of truth across both install scopes.
-    policy_root = detect_root if scope == "global" else (
-        custom_path or Path(opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()).resolve()
-    )
-    _set_conflict_policy(_load_conflict_policy(policy_root, opts.force))
+    # When the install hands off to the browser wizard, the run is
+    # zero-terminal-interaction by contract ("run the command, it installs,
+    # then the wizard opens for packages + settings"): the legacy migration
+    # runs without the [Y/n] gate (the wizard recreates fresh config), and
+    # the GUI is the settings + package surface. Gate is the single source
+    # of truth (TTY / CI / --no-ui / explicit --tools).
+    wizard_handoff = _wizard_should_launch(opts)[0]
 
-    try:
-        if scope == "global":
-            # First-run hook: when legacy artefacts live in the project tree,
-            # prompt before laying down the global surface so the user is
-            # not left with a dual-stack install. Delegates to the unified
-            # `agent-config migrate` (see docs/contracts/migrate-command.md).
-            artefacts = _detect_legacy_for_migration(detect_root)
-            if artefacts and _prompt_migrate_to_global(detect_root, artefacts):
-                rc = _run_migrate_to_global(detect_root)
-                if rc != 0:
-                    return rc
-            # Pass detect_root so the manifest refresh runs when --global is
-            # invoked from within a project tree (ADR-008 Phase 3.2).
-            rc = install_global(parsed_tools, opts.force, project_root=detect_root)
-            _emit_progress_terminal(rc)
-            return rc
-
-        project_root = custom_path or Path(opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()).resolve()
-        is_first_run = not (project_root / SETTINGS_FILE).exists()
-        rc = _main_project_install(opts, project_root, parsed_tools, is_first_run)
-        # Interactive post-install prompt (step-12 Phase 3, forward-compatible
-        # stub). Runs only after a successful install so the local config
-        # never ships ahead of the bridge files it parameterizes.
-        if rc == 0 and getattr(opts, "interactive", False):
-            run_interactive_init(project_root, opts.force)
+    if scope == "global":
+        # First-run hook: sweep legacy project-local artefacts via the
+        # unified `agent-config migrate` before laying down the global
+        # surface (see docs/contracts/migrate-command.md). On the
+        # wizard-handoff path this runs without the [Y/n] gate; the
+        # terminal prompt only fires when no wizard will launch.
+        artefacts = _detect_legacy_for_migration(detect_root)
+        if artefacts and (wizard_handoff or _prompt_migrate_to_global(detect_root, artefacts)):
+            rc = _run_migrate_to_global(detect_root)
+            if rc != 0:
+                return rc
+        # Pass detect_root so the manifest refresh runs when --global is
+        # invoked from within a project tree (ADR-008 Phase 3.2).
+        rc = install_global(parsed_tools, opts.force, project_root=detect_root)
         _emit_progress_terminal(rc)
+        # Browser-wizard parity with the project path: an interactive global
+        # install (init / global / upgrade / refresh --global) hands off to
+        # the GUI instead of the terminal. No --project-root → the wizard
+        # resolves the GLOBAL write root, so it reads/writes
+        # ~/.event4u/agent-config (saved identity → name/language pre-fill)
+        # and never lands global content in the project tree (ADR-020).
+        # Best-effort: install already succeeded, so a wizard boot failure
+        # returns 0.
+        if rc == 0 and wizard_handoff:
+            return _wizard_spawn(detect_root, pass_project_root=False)
         return rc
-    except ConflictAbort as exc:
-        warn(exc.message)
-        _emit_progress({"type": "error", "code": "E_CONFLICT_UNRESOLVED", "message": exc.message})
-        return 1
-    finally:
-        _set_conflict_policy(None)
+
+    project_root = custom_path or Path(opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()).resolve()
+    is_first_run = not (project_root / SETTINGS_FILE).exists()
+    rc = _main_project_install(opts, project_root, parsed_tools, is_first_run)
+    # Interactive post-install prompt (step-12 Phase 3, forward-compatible
+    # stub). Runs only after a successful install so the local config
+    # never ships ahead of the bridge files it parameterizes.
+    if rc == 0 and getattr(opts, "interactive", False):
+        run_interactive_init(project_root, opts.force)
+    _emit_progress_terminal(rc)
+    return rc
 
 
 def _propose_modules_config(project_root: Path, is_first_run: bool) -> None:
@@ -5079,8 +4850,7 @@ def _main_project_install(
 ) -> int:
     """Project-scope install body extracted from :func:`main`.
 
-    Kept as a private helper so ``main()`` can wrap the entire install
-    in a ``try/except ConflictAbort`` without rewriting indentation.
+    Kept as a private helper so ``main()`` stays a thin scope dispatcher.
     """
     if opts.package:
         package_root = Path(opts.package).resolve()