@event4u/agent-config 5.8.0 → 5.10.0

package/scripts/_cli/cmd_doctor.py

@@ -23,8 +23,16 @@ mcp-mode · mcp-beta-readiness · offline-readiness · python-runtime ·
 tier-usage-readiness · council-cli · unsupported-combos ·
 wizard-state.
 Each emits a structured ``{id, status, message, remedy}`` record with
-``status`` ∈ ``ok`` / ``warn`` / ``fail`` (rendered ``✅`` / ``⚠️`` /
-``❌``). ``--check <id>`` runs a single check.
+``status`` ∈ ``ok`` / ``warn`` / ``fail`` / ``skipped`` (rendered
+``✅`` / ``⚠️`` / ``❌`` / ``⏭️``). ``--check <id>`` runs a single check.
+
+Checks are split by scope (:data:`GLOBAL_CHECK_IDS` vs
+:data:`MANIFEST_REQUIRED_CHECK_IDS`) so an ADR-020 global-only consumer
+(bridge marker present, no ``agents/installed-tools.lock``) gets a
+green-capable report instead of a hard bail: the global checks run, the
+manifest-required checks report ``skipped``, and ``bridge-drift`` returns
+a scope-aware "drift not applicable" verdict. See :func:`main` for the
+no-manifest branch and exit-code contract.
 
 Repair affordances: ``--repair wizard-state`` resets a malformed or
 orphaned ``state/wizard-state.json`` under the user-global root (the
@@ -455,6 +463,41 @@ CHECK_IDS = (
     "wizard-state",
 )
 
+#: Checks that need only the project root (or no input at all) and run
+#: regardless of whether a project lockfile exists. Under ADR-020
+#: global-only (bridge marker present, no ``installed-tools.lock``) these
+#: still produce a real verdict. ``scope`` lives here because
+#: :func:`_check_scope` reads only ``project_root`` — the roadmap prose
+#: that grouped it with the manifest checks predates this code reality
+#: (AI council, claude-sonnet-4-5 + gpt-4o, design lens, 2026-06-02).
+GLOBAL_CHECK_IDS: frozenset[str] = frozenset({
+    "scope",
+    "global-binary",
+    "mcp-mode",
+    "mcp-beta-readiness",
+    "offline-readiness",
+    "python-runtime",
+    "tier-usage-readiness",
+    "council-cli",
+    "wizard-state",
+})
+
+#: Checks that genuinely cannot run without the project manifest. Without
+#: a lockfile they report ``skipped`` rather than a misleading verdict.
+#: ``bridge-drift`` is deliberately **not** here: it is scope-aware —
+#: a manifest-derived drift roll-up when the lockfile exists, and a
+#: "drift not applicable (global-only consumer)" verdict when it does
+#: not (computed in :func:`_check_bridge_drift_no_manifest`, keeping
+#: :func:`_check_bridge_drift` a pure roll-up per the council's SRP point).
+MANIFEST_REQUIRED_CHECK_IDS: frozenset[str] = frozenset({
+    "manifest-integrity",
+    "lockfile-freshness",
+    "unsupported-combos",
+})
+
+#: Project-root-relative path of the ADR-020 global-only consumer marker.
+BRIDGE_MARKER_RELATIVE = "agents/.event4u-bridge.yml"
+
 #: Repair targets that ``--repair <id>`` accepts. Each id maps to a
 #: function in :func:`_run_repair` that resets the named artefact and
 #: returns an exit code. Additive set: introduce by adding a new id
@@ -476,7 +519,7 @@ MCP_BETA_GATES: tuple[tuple[str, str], ...] = (
 
 #: Visible status → glyph map. ``warn`` keeps a trailing space so the
 #: rendered output stays in a single visual column with the other glyphs.
-STATUS_SYMBOLS = {"ok": "✅", "warn": "⚠️ ", "fail": "❌"}
+STATUS_SYMBOLS = {"ok": "✅", "warn": "⚠️ ", "fail": "❌", "skipped": "⏭️ "}
 
 #: Minimum Python interpreter the CLI targets. Bumped in lockstep with
 #: ``from __future__ import annotations`` + PEP-604 syntax usage.
@@ -1159,6 +1202,131 @@ def _run_checks(
     return out
 
 
+def _skipped_manifest_check(check_id: str) -> dict[str, Any]:
+    """A ``skipped`` verdict for a manifest-required check with no lockfile.
+
+    Explicit machine-readable record (not omitted, not ``null``) so the
+    ``--json`` ``checks`` array keeps a stable shape for a global-only
+    consumer — a council convergence point (2026-06-02).
+    """
+    return {
+        "id": check_id, "status": "skipped",
+        "message": "requires a project lockfile (agents/installed-tools.lock)",
+        "remedy": "run `agent-config init` to create a project lockfile, "
+                  "then re-run this check",
+    }
+
+
+def _check_bridge_drift_no_manifest(bridge_present: bool) -> dict[str, Any]:
+    """Scope-aware ``bridge-drift`` verdict when no project manifest exists.
+
+    Kept out of :func:`_check_bridge_drift` (which stays a pure
+    manifest-derived roll-up) per the council's single-responsibility
+    point. A global-only consumer has no distributed tools to drift, so
+    a bridge-present repo reports ``ok`` ("not applicable"); a repo with
+    neither lockfile nor bridge marker reports ``skipped``.
+    """
+    if bridge_present:
+        return {
+            "id": "bridge-drift", "status": "ok",
+            "message": "no project lockfile → distributed-tool drift not "
+                       "applicable (global-only consumer)",
+            "remedy": "",
+        }
+    return {
+        "id": "bridge-drift", "status": "skipped",
+        "message": "no project lockfile and no bridge marker → drift check "
+                   "not applicable",
+        "remedy": "run `agent-config init` (project install) or "
+                  "`agent-config refresh --project` (global-only consumer)",
+    }
+
+
+def _run_checks_no_manifest(
+    project_root: Path,
+    bridge_present: bool,
+    only: str | None = None,
+) -> list[dict[str, Any]]:
+    """Run the registry with no project manifest available.
+
+    Mirrors :func:`_run_checks` and preserves :data:`CHECK_IDS` order.
+    Global checks (:data:`GLOBAL_CHECK_IDS`) run unchanged; manifest-required
+    checks (:data:`MANIFEST_REQUIRED_CHECK_IDS`) report ``skipped``;
+    ``bridge-drift`` gets the scope-aware no-manifest verdict.
+    """
+    runners: dict[str, Any] = {
+        "scope": lambda: _check_scope(project_root),
+        "global-binary": lambda: _check_global_binary(project_root),
+        "manifest-integrity": lambda: _skipped_manifest_check("manifest-integrity"),
+        "lockfile-freshness": lambda: _skipped_manifest_check("lockfile-freshness"),
+        "bridge-drift": lambda: _check_bridge_drift_no_manifest(bridge_present),
+        "mcp-mode": lambda: _check_mcp_mode(project_root),
+        "mcp-beta-readiness": lambda: _check_mcp_beta_readiness(project_root),
+        "offline-readiness": lambda: _check_offline_readiness(),
+        "python-runtime": lambda: _check_python_runtime(),
+        "tier-usage-readiness": lambda: _check_tier_usage_readiness(project_root),
+        "council-cli": lambda: _check_council_cli(project_root),
+        "unsupported-combos": lambda: _skipped_manifest_check("unsupported-combos"),
+        "wizard-state": _check_wizard_state,
+    }
+    out: list[dict[str, Any]] = []
+    for cid in CHECK_IDS:
+        if only is not None and cid != only:
+            continue
+        out.append(runners[cid]())
+    return out
+
+
+def _run_no_manifest(
+    opts: argparse.Namespace,
+    project_root: Path,
+    origin: str,
+    bridge_present: bool,
+) -> int:
+    """Handle the no-project-lockfile path without the old hard bail.
+
+    Exit-code contract (council-defined, 2026-06-02):
+
+    * ``0`` — bare report for a recognised global-only consumer
+      (bridge marker present), or a single global ``--check`` that passed.
+    * ``1`` — a runnable health check requested via ``--check`` failed.
+    * ``2`` — a requested ``--check`` cannot run (manifest-required check
+      with no lockfile, or ``bridge-drift`` with neither lockfile nor
+      bridge marker), or a bare report in an **uninitialised** repo
+      (neither lockfile nor bridge marker) — preserves the spirit of the
+      pre-existing "run init" signal while still printing a real report.
+    """
+    checks = _run_checks_no_manifest(project_root, bridge_present, only=opts.check)
+    fail_check = any(c["status"] == "fail" for c in checks)
+    skipped_requested = opts.check is not None and any(
+        c["id"] == opts.check and c["status"] == "skipped" for c in checks
+    )
+
+    if opts.json:
+        _emit_json(project_root, [], [], [], [], checks=checks, origin=origin)
+    elif opts.check is None:
+        print(f"  📍  project_root: {project_root} (origin: {origin})")
+        if bridge_present:
+            print("  ℹ️   global-only consumer: bridge marker present, no "
+                  "project lockfile (expected under ADR-020)")
+            print("      project-manifest checks are skipped — they apply only "
+                  "to project-local distributed tools")
+        else:
+            print("  ⚠️   no project lockfile and no bridge marker at "
+                  f"{project_root}", file=sys.stderr)
+            print("      run `agent-config init` (project install) or "
+                  "`agent-config refresh --project` (global-only consumer)",
+                  file=sys.stderr)
+        _emit_checks_text(checks)
+    else:
+        _emit_checks_text(checks)
+
+    if opts.check is not None:
+        if skipped_requested:
+            return 2
+        return 1 if fail_check else 0
+    return 0 if bridge_present else 2
+
 
 def _emit_json(
     project_root: Path,
@@ -1371,17 +1539,12 @@ def main(argv: list[str] | None = None) -> int:
     manifest_pth = installed_tools.manifest_path(project_root)
     manifest = installed_tools.read_manifest(manifest_pth)
     if manifest is None:
-        print(
-            f"❌  doctor: no project lockfile at {manifest_pth}",
-            file=sys.stderr,
-        )
-        print(
-            f"    project_root: {project_root} (origin: {origin})",
-            file=sys.stderr,
-        )
-        print("    run `./agent-config init` to create one",
-              file=sys.stderr)
-        return 2
+        # No project lockfile. Under ADR-020 global-only this is a
+        # legitimate state, not an error — run the lockfile-independent
+        # checks and report consumer state instead of a hard bail. The
+        # per-scope split + exit-code contract live in _run_no_manifest.
+        bridge_present = (project_root / BRIDGE_MARKER_RELATIVE).is_file()
+        return _run_no_manifest(opts, project_root, origin, bridge_present)
 
     records, known = _collect_manifest_entries(project_root, manifest)
     missing, modified, tag_drift = _classify(records)

package/scripts/_dispatch.bash

@@ -782,6 +782,16 @@ cmd_council() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 "$script" "$sub" "$@"
 }
 
+# `use --profile=<id>` — switch the active experience/profile. Writes
+# profile.id into the canonical .agent-settings.yml; the explicit
+# profile-switch seam named by ADR-040 (road-to-6.0.0-a Step 8).
+cmd_use() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/profile_use.py")" || return 1
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 "$script" "$@"
+}
+
 # `agent-config update` — flip the agent_config_version pin in
 # .agent-settings.yml. See scripts/_cli/cmd_update.py (P3.1 of
 # road-to-portable-runtime-and-update-check.md).
@@ -928,6 +938,7 @@ main() {
     mcp:check)               cmd_mcp_check "$@" ;;
     mcp:setup)               cmd_mcp_setup "$@" ;;
     mcp:run)                 cmd_mcp_run "$@" ;;
+    use)                     cmd_use "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     hooks:install)           cmd_hooks_install "$@" ;;

package/scripts/ai-video/lib/probe-audio.sh

@@ -36,6 +36,14 @@
 #   2  usage / file missing
 #   3  required tool missing (ffprobe / ffmpeg)
 #   4  no audio stream in the file
+#
+# Runtime requirements (trust boundary — AI-council note 2026-06-02):
+#   - ffmpeg + ffprobe on PATH (enforced, exit 3).
+#   - POSIX awk. Both GNU awk (CI/Linux) and BSD awk (macOS) are supported;
+#     the window arrays are passed via ENVIRON, not -v, because BSD awk
+#     rejects literal newlines in a -v value. The honesty invariant
+#     (interval <=> warning) is regression-guarded by
+#     tests/test_probe_audio.py::test_corpus_sweep_honesty_invariant.
 
 set -euo pipefail
 
@@ -99,7 +107,9 @@ sil_bounds="$(ffmpeg -hide_banner -nostats -i "${song}" \
       /silence_start/ { for(i=1;i<=NF;i++) if($i=="silence_start:") s=$(i+1) }
       /silence_end/   { for(i=1;i<=NF;i++) if($i=="silence_end:")   { e=$(i+1); printf "%.3f\n", (s+e)/2 } }
     ' 2>/dev/null || true)"
-n_sil="$(printf '%s' "${sil_bounds}" | sed '/^$/d' | wc -l | tr -d ' ')"
+# Trailing \n so `wc -l` counts the last line: command substitution strips
+# the trailing newline, and two boundaries without it count as one.
+n_sil="$(printf '%s\n' "${sil_bounds}" | sed '/^$/d' | wc -l | tr -d ' ')"
 
 # --- 4. choose method + build section boundaries ------------------------
 # A method needs >= 3 sections (>= 2 internal boundaries) to count as
@@ -125,7 +135,7 @@ if [ -z "${method}" ]; then
             prev=en[k]
           }
         }')"
-  n_rms="$(printf '%s' "${rms_bounds}" | sed '/^$/d' | wc -l | tr -d ' ')"
+  n_rms="$(printf '%s\n' "${rms_bounds}" | sed '/^$/d' | wc -l | tr -d ' ')"
   if [ "${n_rms}" -ge 2 ]; then
     method="rms"
     boundaries="$(printf '%s\n' "${rms_bounds}" | sed '/^$/d' | sort -n | uniq)"
@@ -145,10 +155,15 @@ fi
 # = mean of the RMS windows whose start falls inside it.
 printf '%s' "${boundaries}" \
   | sed '/^$/d' \
-  | awk -v d="${duration}" -v method="${method}" -v warning="${warning}" \
-        -v wins="$(printf '%b' "${win_starts}")" -v ens="$(printf '%b' "${win_energy}")" '
+  | _PROBE_WINS="$(printf '%b' "${win_starts}")" _PROBE_ENS="$(printf '%b' "${win_energy}")" \
+    awk -v d="${duration}" -v method="${method}" -v warning="${warning}" '
     BEGIN {
-      nw=split(wins, ws, "\n"); split(ens, es, "\n")
+      # Read the window arrays from the environment, not -v: BSD awk (macOS)
+      # rejects literal newlines inside a -v value ("newline in string"),
+      # while GNU awk (CI/Linux) tolerates them. ENVIRON is POSIX and
+      # portable across both. (Surfaced 2026-06-02 once ffmpeg landed on a
+      # macOS authoring host — CI on gawk never hit it.)
+      nw=split(ENVIRON["_PROBE_WINS"], ws, "\n"); split(ENVIRON["_PROBE_ENS"], es, "\n")
       # build edges
       ne=0; edges[ne++]=0
     }

package/scripts/check_release_published.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+Release-published drift gate.
+
+Catches the "release merged to main but never tagged/published" failure
+mode — where ``main``'s ``package.json`` claims a version that has no
+matching git tag, and npm's ``latest`` therefore lags behind main. This
+is the backstop that would have surfaced the 5.8.0-stuck-on-5.7.0 state
+the moment it happened, instead of weeks later.
+
+Two independent invariants:
+
+  1. **Tag invariant** (always checkable, no network): the version in
+     ``package.json`` MUST have a matching git tag (local or remote).
+  2. **npm invariant** (``--check-npm``, network): ``npm view <pkg>
+     dist-tags.latest`` MUST equal the ``package.json`` version.
+
+Scope guard: this only makes sense on the release trunk. Off ``main``
+(e.g. a feature branch, or a ``release/X.Y.Z`` branch mid-flight where
+the bump legitimately precedes the tag) the gate **no-ops** unless
+``--strict`` is combined with an explicit on-main signal. The daily
+scheduled workflow runs ``--strict --check-npm`` on ``main``; the local
+``task check-release-published`` runs the tag invariant only.
+
+Exit codes: 0 = pass / no-op · 1 = drift detected · 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$")
+REPO_ROOT = Path(__file__).resolve().parent.parent
+PACKAGE_JSON = REPO_ROOT / "package.json"
+MAIN_BRANCH = "main"
+
+
+def _git(*args: str) -> tuple[int, str]:
+    proc = subprocess.run(["git", *args], capture_output=True, text=True, check=False)
+    return proc.returncode, (proc.stdout or "").strip()
+
+
+def _package_version() -> str:
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    return str(data["version"])
+
+
+def _package_name() -> str:
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    return str(data["name"])
+
+
+def _tag_exists(tag: str) -> bool:
+    rc, out = _git("tag", "-l", tag)
+    if rc == 0 and tag in out.splitlines():
+        return True
+    rc, _ = _git("ls-remote", "--exit-code", "--tags", "origin", tag)
+    return rc == 0
+
+
+def _on_main() -> bool:
+    # Local checkout, CI push ref, or CI scheduled ref all map to main.
+    ref = os.environ.get("GITHUB_REF", "")
+    if ref in ("refs/heads/main", "refs/heads/master"):
+        return True
+    rc, head = _git("rev-parse", "--abbrev-ref", "HEAD")
+    return rc == 0 and head == MAIN_BRANCH
+
+
+def _npm_latest(pkg: str) -> str | None:
+    proc = subprocess.run(
+        ["npm", "view", pkg, "dist-tags.latest"],
+        capture_output=True, text=True, check=False,
+    )
+    if proc.returncode != 0:
+        return None
+    return (proc.stdout or "").strip() or None
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Release-published drift gate.")
+    ap.add_argument("--strict", action="store_true",
+                    help="Fail on drift (default: informational, exit 0).")
+    ap.add_argument("--check-npm", action="store_true",
+                    help="Also assert npm dist-tags.latest == package.json version (network).")
+    ap.add_argument("--require-main", action="store_true",
+                    help="Only enforce when on main; no-op elsewhere (default for scheduled).")
+    args = ap.parse_args(argv)
+
+    try:
+        version = _package_version()
+    except (OSError, KeyError, json.JSONDecodeError) as exc:
+        print(f"❌  cannot read package.json version: {exc}", file=sys.stderr)
+        return 3
+    if not SEMVER_RE.match(version):
+        print(f"❌  package.json version is not semver: {version!r}", file=sys.stderr)
+        return 3
+
+    if args.require_main and not _on_main():
+        print(f"ℹ️  not on {MAIN_BRANCH} — release-published gate skipped.")
+        return 0
+
+    problems: list[str] = []
+
+    if not _tag_exists(version):
+        problems.append(
+            f"package.json is {version} but no git tag {version} exists "
+            f"(local or origin) — the release was bumped/merged but never "
+            f"tagged. Complete it: tag the release-merge commit and push "
+            f"(triggers publish-npm.yml), e.g. `git tag {version} && git "
+            f"push origin {version}`."
+        )
+
+    if args.check_npm:
+        pkg = _package_name()
+        latest = _npm_latest(pkg)
+        if latest is None:
+            print(f"⚠️  could not read npm dist-tags.latest for {pkg} "
+                  f"(network/registry) — npm invariant not checked.", file=sys.stderr)
+        elif latest != version:
+            problems.append(
+                f"npm {pkg}@latest is {latest} but package.json is {version} "
+                f"— the published release lags main. Check publish-npm.yml "
+                f"for tag {version}, or re-dispatch it."
+            )
+
+    if not problems:
+        suffix = " + npm" if args.check_npm else ""
+        print(f"✅  release-published: {version} is tagged{suffix} and in sync.")
+        return 0
+
+    header = "❌  Release-published drift:" if args.strict else "⚠️  Release-published drift (warn-only):"
+    print(header, file=sys.stderr)
+    for p in problems:
+        print(f"  - {p}", file=sys.stderr)
+    return 1 if args.strict else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/profile_use.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""`agent-config use --profile=<id>` — switch the active experience.
+
+The explicit profile-switch entry point named by the Execution-Model ADR
+(`docs/decisions/ADR-040-execution-model-projection-time-filtering.md`) and
+wired in `road-to-6.0.0-a-positioning-and-validation` Phase 2 / Step 8.
+
+In 6.0.0-A this writes `profile.id` into the canonical project
+`.agent-settings.yml` and prints what changed — it does **NOT** narrow what
+gets projected into the tool trees. Pack-scoped surfacing (projection-time
+filtering) activates in 6.0.0-B behind a staged, opt-in rollout. This command
+is the stable seam that 6.0.0-B hooks projection into.
+
+Comment-preserving: the canonical settings file is hand-editable and richly
+commented, so the write is a surgical text edit of the `profile:` block, not a
+yaml round-trip that would strip comments.
+
+CLI:
+    agent-config use --profile=<id>
+    agent-config use --profile <id>
+
+Valid ids (the six seed profiles, docs/contracts/profile-system.md):
+    developer · content_creator · founder · agency · finance · ops
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_settings import (  # noqa: E402
+    canonical_settings_write_path,
+    find_project_root,
+)
+
+VALID_PROFILES = (
+    "developer",
+    "content_creator",
+    "founder",
+    "agency",
+    "finance",
+    "ops",
+)
+
+# Matches a top-level `profile:` block and the `id:` leaf under it. The id
+# value may be bare, single-, or double-quoted; we only rewrite the value.
+_PROFILE_ID_RE = re.compile(
+    r"(?m)^(?P<head>profile:[ \t]*\n(?:[ \t]+#[^\n]*\n|[ \t]*\n)*"
+    r"[ \t]+id:[ \t]*)(?P<val>[^\n#]*)",
+)
+
+
+def _resolve_write_path() -> Path:
+    cwd = Path.cwd()
+    root = find_project_root(cwd) or cwd
+    return canonical_settings_write_path(root)
+
+
+def _set_profile_id(text: str, profile_id: str) -> tuple[str, str | None]:
+    """Return (new_text, previous_id). Append a block if none exists."""
+    m = _PROFILE_ID_RE.search(text)
+    if m:
+        previous = m.group("val").strip().strip("'\"") or None
+        new_text = text[: m.start("val")] + profile_id + text[m.end("val") :]
+        return new_text, previous
+    # No profile block — append one. Keep a single trailing newline.
+    block = f"\n# --- Profile (experience) ---\nprofile:\n  id: {profile_id}\n"
+    sep = "" if text.endswith("\n") else "\n"
+    return text + sep + block, None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config use",
+        description="Switch the active experience/profile (writes profile.id).",
+    )
+    parser.add_argument(
+        "--profile",
+        metavar="ID",
+        help=f"Experience to switch to. One of: {', '.join(VALID_PROFILES)}.",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.profile:
+        print(
+            "❌  `use` requires --profile=<id>. Valid: "
+            + " · ".join(VALID_PROFILES),
+            file=sys.stderr,
+        )
+        return 2
+
+    profile_id = args.profile.strip()
+    if profile_id not in VALID_PROFILES:
+        print(
+            f"❌  unknown profile `{profile_id}`. Valid: "
+            + " · ".join(VALID_PROFILES),
+            file=sys.stderr,
+        )
+        return 2
+
+    path = _resolve_write_path()
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    new_text, previous = _set_profile_id(text, profile_id)
+
+    if previous == profile_id and path.exists():
+        print(f"✅  Already on experience `{profile_id}` — no change ({path}).")
+        return 0
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(new_text, encoding="utf-8")
+
+    arrow = f"`{previous}` → `{profile_id}`" if previous else f"`{profile_id}`"
+    print(f"✅  Experience set to {arrow} in {path}.")
+    print(
+        "ℹ️   6.0.0-A records the choice only — it does not yet narrow what is "
+        "projected into .claude/ .cursor/ .augment/. Pack-scoped surfacing "
+        "(ADR-040) activates in 6.0.0-B behind a staged, opt-in rollout."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())