@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/agent-config

@@ -1,954 +1,57 @@
 #!/usr/bin/env bash
-# agent-config — consumer-facing CLI for the event4u/agent-config package.
+# Maintainer / source-checkout entry point.
 #
-# This is the MASTER entrypoint shipped inside the package
-# (node_modules/@event4u/agent-config/scripts/agent-config or
-# vendor/event4u/agent-config/scripts/agent-config). A thin wrapper at
-# the consumer's repo root (`./agent-config`) delegates here.
+# Public consumer entry point is `dist/cli/agent-config.js` via
+# `npx @event4u/agent-config` — that's the path documented in README.
+# This shim is the canonical local invocation for maintainers working
+# in a source checkout, where `npx` can't resolve the bin without a
+# prior `npm link` (no `node_modules/.bin/agent-config` symlink).
 #
-# Commands are strictly consumer-facing. Maintainer workflows stay in
-# Taskfile.yml and are NOT exposed here.
+# Behaviour:
+#   - If dist/cli/agent-config.js exists  → forward to the TS binary
+#   - Else if scripts/_dispatch.bash exists → fall back to the legacy
+#     Bash dispatcher (preserves maintainer-internal callers — golden
+#     tests, work_engine harness — that pre-date the TS shell).
+#   - Else → error with a one-line build hint
 #
-# Invariants:
-#   * CWD on entry is the consumer's repo root — we keep it that way
-#     so underlying scripts resolve paths correctly.
-#   * PACKAGE_ROOT is derived from this script's location, used only to
-#     locate the package-internal Python scripts (mcp_render.py, …).
-#   * Unknown arguments are forwarded verbatim to the underlying script.
-
+# Deprecation warning is only emitted when this script is invoked from
+# an installed npm package (i.e. not a source-repo checkout). Source-
+# checkout detection: `$here/../src/cli/registry.ts` exists. Maintainers
+# running `./agent-config` from the repo root see no warning.
+#
+# Set AGENT_CONFIG_QUIET_DEPRECATION=1 to suppress the deprecation
+# warning unconditionally (used by test harnesses that pin the stderr
+# surface).
 set -euo pipefail
 
-# Resolve symlinks in BASH_SOURCE so PACKAGE_ROOT points at the real
-# package directory even when invoked via a symlink (global npm install,
-# vendor/bin symlink, user-placed symlink on PATH, …).
-SOURCE="${BASH_SOURCE[0]}"
-while [ -L "$SOURCE" ]; do
-  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
-  SOURCE="$(readlink "$SOURCE")"
-  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+# Resolve $0 through symlinks (maintainer repo root has a ./agent-config
+# symlink → scripts/agent-config). Portable across macOS and Linux —
+# avoids GNU-only `readlink -f`.
+src="$0"
+while [[ -L "$src" ]]; do
+  dir="$(cd -- "$(dirname -- "$src")" && pwd)"
+  src="$(readlink "$src")"
+  [[ "$src" != /* ]] && src="$dir/$src"
 done
-SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
-PACKAGE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-CONSUMER_ROOT="$(pwd)"
-
-VERSION_FILE="$PACKAGE_ROOT/package.json"
-
-usage() {
-  # Tier filter — see docs/contracts/command-surface-tiers.md.
-  # Default prints Tier-0 only; --tier=1 adds Tier-1; --tier=all adds Tier-2.
-  local tier="${1:-0}"
-
-  cat <<'EOF'
-agent-config — event4u/agent-config CLI
-
-Usage:
-  ./agent-config <command> [options]
-  ./agent-config --help [--tier=0|1|all]
-EOF
-
-  cat <<'EOF'
-
-Tier 0 — daily-driver (init → sync → validate → work):
-  init                       One-shot project install. Forwards to `scripts/install`
-                             with all args. Entry point for `npx @event4u/agent-config init`.
-                             Flags: --tools=<list> | --ai=<list> | --yes | --force
-  sync                       Replay agents/installed-tools.lock — re-installs any
-                             tool whose bridge marker is missing locally (ADR-008).
-                             Flags: --dry-run | --force | --project=<path>
-  validate                   Read-only drift detection on the manifest
-                             (marker missing, scope divergence, version drift).
-                             Exits 1 on drift. Flags: --quiet | --skip-version-check
-  work                       Drive the work_engine Python engine on a free-form prompt
-                             (Option-A loop; called by the /work command)
-  implement-ticket           Drive the work_engine Python engine on a ticket envelope
-                             (Option-A loop; called by the /implement-ticket command)
-  help                       Show this help (default Tier-0; --tier=1|all expands)
-  --version, -V              Print package version
-EOF
-
-  if [[ "$tier" == "1" || "$tier" == "all" ]]; then
-    cat <<'EOF'
-
-Tier 1 — power-user (release shape, audit, migration):
-  update                     Update the agent_config_version pin in .agent-settings.yml
-                             Flags: --check (read-only) | --to <version> (explicit pin)
-  versions                   List available @event4u/agent-config versions
-                             on npm. Marks the current pin and latest.
-                             Flags: --offline | --limit=N | --json
-  global                     Install to user-scope paths (~/.claude/, ~/.cursor/, …)
-                             Forwards to `scripts/install --global` (ADR-007).
-                             Flags: --tools=<list> | --ai=<list> | --yes | --force
-  export                     Eject a tool's canonical content into a chosen path
-                             (real file, no symlink). Idempotent; --force overrides
-                             content drift. See `./agent-config export --list`.
-                             Flags: --tool=<id> | --output=<path> | --force | --list
-  uninstall                  Remove bridge markers (project) or lockfile
-                             entries (global). Idempotent. User-deployed
-                             content under ~/.<tool>/ is preserved unless
-                             --purge is passed (destructive).
-                             Flags: --global | --tools=<list> | --dry-run
-                                    | --purge | --force | --project=<path>
-  prune                      Remove project bridge markers not declared in
-                             agents/installed-tools.lock (npm-prune style).
-                             Hard-floors when lockfile is absent.
-                             Flags: --dry-run | --json | --project=<path>
-                                    | --all-missing-lock
-  doctor                     Read-only drift report: manifest ↔ filesystem.
-                             Lists missing, modified, and foreign files.
-                             Exits 1 on drift, 2 on missing lockfile.
-                             Flags: --json | --project=<path>
-  explain                    Read-only decision-chain trace.
-                             Usage: explain config | explain rule <name>
-                                  | explain route "<text>"
-                             Flags: --json | --project=<path>
-  migrate                    One-shot migration off legacy composer / npm install paths
-                             Flags: --dry-run (detect only)
-  first-run                  Guided first-run setup — cost profile, settings, tooling
-  keys:install-anthropic     Install the Anthropic API key for the AI Council
-                             (interactive, /dev/tty only, writes ~/.config/agent-config/anthropic.key 0600)
-  keys:install-openai        Install the OpenAI API key for the AI Council
-                             (interactive, /dev/tty only, writes ~/.config/agent-config/openai.key 0600)
-  council:estimate           Pre-call council cost preview (no API call, no spend)
-                             Usage: council:estimate <question> [--input-mode prompt|roadmap]
-  council:run                Run the council. Requires --confirm to spend.
-                             Usage: council:run <question> --output <path> --confirm
-  council:render             Re-render a saved council responses JSON to markdown
-                             Usage: council:render <responses.json>
-EOF
-  fi
-
-  if [[ "$tier" == "all" ]]; then
-    cat <<'EOF'
-
-Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
-  mcp:render                 Render mcp.json → .cursor/mcp.json, .windsurf/mcp.json
-                             (pass --claude-desktop to also write user-scope config)
-  mcp:check                  Dry-run mcp:render; exit non-zero if targets are stale
-  mcp:setup                  Create .venv-mcp/ and install the mcp SDK
-                             (one-line MCP server onboarding; idempotent)
-  mcp:run                    Run the built-in MCP server over stdio
-                             (requires `mcp:setup` first; see docs/mcp-server.md)
-                             (experimental — beta gates: docs/contracts/mcp-beta-criteria.md)
-  roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
-  roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
-  settings:check             Validate .agent-settings.yml against the YAML-subset contract
-                             (docs/contracts/settings-sync-yaml-subset.md). Read-only.
-                             Exit 0 clean, 1 finding(s), 2 file absent / unreadable.
-  hooks:install              Install the pre-commit roadmap-progress hook
-                             (use --print to dump it, --force to overwrite an existing hook)
-  hooks:status               Print the runtime hook matrix (per-platform install + bindings)
-                             Flags: --format json|table, --strict (CI), --project-root <path>
-  hooks:doctor               Diagnose hook health: concerns + fail-open/closed posture,
-                             last dispatcher feedback per concern, missing trampolines.
-                             Wraps hooks:status. Read-only.
-                             Flags: --format json|table, --strict (CI), --project-root <path>
-  hooks:replay               Replay a fixture through the universal dispatcher with
-                             AGENT_CONFIG_REPLAY=1 (no writes under agents/state/).
-                             Usage: hooks:replay --platform <name> --event <event>
-                                    --payload <path|event-name> [--native-event <native>]
-                                    [--manifest <path>] [--json] [--dry-run]
-  migrate-state              Migrate a legacy .implement-ticket-state.json file
-                             to the v1 .work-state.json schema (preserves .bak)
-  memory:lookup              Retrieve memory entries (text or JSON envelope)
-  memory:signal              Append a provisional intake signal (memory proposal)
-  memory:hash                Hash a memory entry (YAML or JSON stdin)
-  memory:check               Validate memory YAML schema + staleness
-  memory:check-proposal      Run the admission gate on a memory proposal
-  proposal:check             Validate a learning/skill/rule proposal markdown
-  refine-ticket:detect       Run the deterministic refine-ticket detection helper
-  chat-history:hook          Platform hook entry point (read JSON from stdin)
-                             Usage: chat-history:hook --platform <claude|augment|cursor|cline|windsurf|gemini>
-  chat-history:checkpoint    Append a phase-boundary entry to agents/.agent-chat-history
-                             (CHECKPOINT fallback for platforms without native hooks)
-  roadmap-progress:hook      PostToolUse hook entry point (read JSON from stdin)
-                             Regenerates roadmaps-progress.md when a tool wrote under agents/roadmaps/
-  onboarding-gate:hook       Hook entry point (drains stdin)
-                             Writes .augment/state/onboarding-gate.json from .agent-settings.yml
-  context-hygiene:hook       PostToolUse hook entry point (read JSON from stdin)
-                             Maintains .augment/state/context-hygiene.json (turn count, loop, freshness)
-  dispatch:hook              Universal hook dispatcher (Phase 7, hook-architecture-v1.md)
-                             Usage: dispatch:hook --platform <name> --event <event> [--native-event <native>]
-                             Reads scripts/hook_manifest.yaml and runs the resolved concern chain.
-  telemetry:record           Append one artefact-engagement event (default-off)
-  telemetry:status           Print artefact-engagement telemetry status (read-only)
-  telemetry:report           Aggregate the engagement log into a quartile report
-EOF
-  fi
-
-  if [[ "$tier" == "0" ]]; then
-    cat <<'EOF'
-
-(Hidden: 15 Tier-1 + 26 Tier-2 commands. Run `./agent-config --help --tier=1`
-or `--tier=all` to see them. Tier criteria: docs/contracts/command-surface-tiers.md.)
-EOF
-  fi
-
-  cat <<'EOF'
-
-Examples (Tier 0):
-  ./agent-config init --tools=claude-code,cursor --yes
-  ./agent-config sync --dry-run
-  ./agent-config sync
-  ./agent-config validate
-  ./agent-config work --state-file .work-state.json --prompt-file prompt.txt
-  ./agent-config implement-ticket --state-file .work-state.json
-EOF
-
-  if [[ "$tier" == "1" || "$tier" == "all" ]]; then
-    cat <<'EOF'
-
-Examples (Tier 1):
-  ./agent-config global --tools=claude-code --yes
-  ./agent-config global --ai=cursor,windsurf
-  ./agent-config export --list
-  ./agent-config export --tool=agents-md --output=AGENTS.md
-  ./agent-config export --tool=copilot-instructions --output=.github/copilot-instructions.md
-  ./agent-config uninstall --tools=cursor --dry-run
-  ./agent-config uninstall --global --tools=windsurf --purge
-  ./agent-config prune --dry-run
-  ./agent-config prune --json
-  ./agent-config doctor
-  ./agent-config doctor --json
-  ./agent-config versions
-  ./agent-config versions --limit=10
-  ./agent-config versions --json
-  ./agent-config init --offline --tools=claude-code,cursor --yes
-  ./agent-config update --offline --to=2.2.0
-  ./agent-config first-run
-  ./agent-config keys:install-anthropic
-  ./agent-config keys:install-openai
-  ./agent-config council:estimate prompt.txt
-  ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
-  ./agent-config council:render agents/council-sessions/out.json
-EOF
-  fi
-
-  if [[ "$tier" == "all" ]]; then
-    cat <<'EOF'
-
-Examples (Tier 2):
-  ./agent-config mcp:render
-  ./agent-config mcp:render --claude-desktop
-  ./agent-config mcp:check
-  ./agent-config mcp:setup
-  ./agent-config mcp:run
-  ./agent-config roadmap:progress
-  ./agent-config settings:check
-  ./agent-config hooks:install
-  ./agent-config hooks:replay --platform augment --event post_tool_use --payload post_tool_use --json
-  ./agent-config migrate-state
-  ./agent-config memory:lookup --types domain-invariants --key billing
-  ./agent-config memory:signal --type architecture-decision --path src/Foo.php --body "…"
-  ./agent-config memory:check --path agents/memory
-  ./agent-config refine-ticket:detect ticket-body.txt
-  ./agent-config telemetry:status
-  ./agent-config telemetry:status --format json
-  ./agent-config telemetry:report --since 30d --top 20
-  ./agent-config telemetry:report --since 7d --format json --top 0
-EOF
-  fi
-
-  cat <<'EOF'
-
-All commands operate on the CURRENT DIRECTORY (your project root).
-The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
-EOF
-}
-
-print_version() {
-  if [[ -f "$VERSION_FILE" ]] && command -v python3 >/dev/null 2>&1; then
-    python3 -c "import json; print(json.load(open('$VERSION_FILE'))['version'])"
-  else
-    echo "unknown"
-  fi
-}
-
-require_python3() {
-  if ! command -v python3 >/dev/null 2>&1; then
-    echo "❌  agent-config: python3 not found on PATH" >&2
-    echo "    Install Python 3.10+ and retry." >&2
-    exit 127
-  fi
-}
-
-# Locate a script. First argument is relative to PACKAGE_ROOT, second is
-# an optional fallback relative to CONSUMER_ROOT (for scripts that ship
-# to the consumer via .augment/, e.g. update_roadmap_progress.py).
-resolve_script() {
-  local pkg_rel="$1"
-  local consumer_rel="${2-}"
-  local pkg_abs="$PACKAGE_ROOT/$pkg_rel"
-  if [[ -f "$pkg_abs" ]]; then
-    printf '%s' "$pkg_abs"
-    return 0
-  fi
-  if [[ -n "$consumer_rel" && -f "$CONSUMER_ROOT/$consumer_rel" ]]; then
-    printf '%s' "$CONSUMER_ROOT/$consumer_rel"
-    return 0
-  fi
-  echo "❌  agent-config: script not found: $pkg_rel" >&2
-  [[ -n "$consumer_rel" ]] && echo "    (also tried: $consumer_rel in $CONSUMER_ROOT)" >&2
-  return 1
-}
-
-# Resolve a script that ships under templates/scripts/. Tries (in order):
-#   1. CONSUMER_ROOT/scripts/<name>                       — local copy / customization
-#   2. CONSUMER_ROOT/.augment/templates/scripts/<name>    — installer-shipped
-#   3. PACKAGE_ROOT/.agent-src/templates/scripts/<name>   — package-internal fallback
-# Consumer customization wins so projects can patch behavior locally
-# without losing the upstream default.
-resolve_template_script() {
-  local name="$1"
-  local p
-  for p in \
-    "$CONSUMER_ROOT/scripts/$name" \
-    "$CONSUMER_ROOT/.augment/templates/scripts/$name" \
-    "$PACKAGE_ROOT/.agent-src/templates/scripts/$name"; do
-    if [[ -f "$p" ]]; then
-      printf '%s' "$p"
-      return 0
-    fi
-  done
-  echo "❌  agent-config: template script not found: $name" >&2
-  echo "    Searched:" >&2
-  echo "      - $CONSUMER_ROOT/scripts/$name" >&2
-  echo "      - $CONSUMER_ROOT/.augment/templates/scripts/$name" >&2
-  echo "      - $PACKAGE_ROOT/.agent-src/templates/scripts/$name" >&2
-  return 1
-}
-
-cmd_mcp_render() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/mcp_render.py")"
-  exec python3 "$script" "$@"
-}
-
-cmd_mcp_check() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/mcp_render.py")"
-  exec python3 "$script" --check "$@"
-}
-
-cmd_mcp_setup() {
-  local script
-  script="$(resolve_script "scripts/mcp_setup.sh")" || return 1
-  exec bash "$script" "$@"
-}
-
-# Run the built-in stdio MCP server. The server module ships inside the
-# package (PACKAGE_ROOT/scripts/mcp_server/), but the venv is created by
-# `mcp_setup.sh` at CWD — keeping consumer projects in control of where
-# the SDK install lives. PYTHONPATH points at PACKAGE_ROOT so the
-# `scripts.mcp_server` import resolves regardless of CWD.
-cmd_mcp_run() {
-  local venv_py="$CONSUMER_ROOT/.venv-mcp/bin/python"
-  if [[ ! -x "$venv_py" ]]; then
-    echo "❌  agent-config: .venv-mcp/ not found at $CONSUMER_ROOT/.venv-mcp" >&2
-    echo "    Run \`./agent-config mcp:setup\` first to create it." >&2
-    exit 1
-  fi
-  exec env PYTHONPATH="$PACKAGE_ROOT" "$venv_py" -m scripts.mcp_server "$@"
-}
-
-cmd_roadmap_progress() {
-  require_python3
-  local script
-  script="$(resolve_script ".agent-src/scripts/update_roadmap_progress.py" ".augment/scripts/update_roadmap_progress.py")"
-  exec python3 "$script" "$@"
-}
-
-cmd_roadmap_progress_check() {
-  require_python3
-  local script
-  script="$(resolve_script ".agent-src/scripts/update_roadmap_progress.py" ".augment/scripts/update_roadmap_progress.py")"
-  exec python3 "$script" --check "$@"
-}
-
-cmd_first_run() {
-  local script
-  script="$(resolve_script "scripts/first-run.sh")"
-  exec bash "$script" "$@"
-}
-
-cmd_implement_ticket() {
-  require_python3
-  local engine_root="$PACKAGE_ROOT/.agent-src/templates/scripts"
-  if [[ ! -d "$engine_root/work_engine" ]]; then
-    echo "❌  agent-config: work_engine module not found at $engine_root/work_engine" >&2
-    echo "    Reinstall the package and retry." >&2
-    return 1
-  fi
-  exec env PYTHONPATH="$engine_root" python3 -m work_engine "$@"
-}
-
-cmd_work() {
-  # /work shares the engine with /implement-ticket — only the input
-  # envelope differs (kind=prompt vs kind=ticket). Keeping a separate
-  # subcommand makes the user-facing distinction explicit and lets the
-  # two flows diverge later without churn at the wrapper layer.
-  require_python3
-  local engine_root="$PACKAGE_ROOT/.agent-src/templates/scripts"
-  if [[ ! -d "$engine_root/work_engine" ]]; then
-    echo "❌  agent-config: work_engine module not found at $engine_root/work_engine" >&2
-    echo "    Reinstall the package and retry." >&2
-    return 1
-  fi
-  exec env PYTHONPATH="$engine_root" python3 -m work_engine "$@"
-}
-
-cmd_migrate_state() {
-  require_python3
-  local engine_root="$PACKAGE_ROOT/.agent-src/templates/scripts"
-  if [[ ! -d "$engine_root/work_engine/migration" ]]; then
-    echo "❌  agent-config: work_engine.migration module not found at $engine_root/work_engine/migration" >&2
-    echo "    Reinstall the package and retry." >&2
-    return 1
-  fi
-  # -W ignore::RuntimeWarning suppresses the known sys.modules notice from
-  # `python3 -m pkg.subpkg.module` when the parent package eagerly imports
-  # the submodule via its CLI module. The migration is non-invasive and
-  # the warning is cosmetic; suppressing here avoids touching the engine.
-  exec env PYTHONPATH="$engine_root" python3 -W ignore::RuntimeWarning -m work_engine.migration.v0_to_v1 "$@"
-}
-
-cmd_memory_lookup() {
-  require_python3
-  local script
-  script="$(resolve_template_script "memory_lookup.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_memory_signal() {
-  require_python3
-  local script
-  script="$(resolve_template_script "memory_signal.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_memory_hash() {
-  require_python3
-  local script
-  script="$(resolve_template_script "memory_hash.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_telemetry_record() {
-  require_python3
-  local script
-  script="$(resolve_template_script "telemetry_record.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_telemetry_status() {
-  require_python3
-  local script
-  script="$(resolve_template_script "telemetry_status.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_telemetry_report() {
-  require_python3
-  local script
-  script="$(resolve_template_script "telemetry_report.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_memory_check() {
-  require_python3
-  local script
-  script="$(resolve_template_script "check_memory.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_memory_check_proposal() {
-  require_python3
-  local script
-  script="$(resolve_template_script "check_memory_proposal.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_proposal_check() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/check_proposal.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_refine_ticket_detect() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/refine_ticket_detect.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_chat_history_hook() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/chat_history.py")" || return 1
-  exec python3 "$script" hook-dispatch "$@"
-}
-
-cmd_roadmap_progress_hook() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/roadmap_progress_hook.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_onboarding_gate_hook() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/onboarding_gate_hook.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_context_hygiene_hook() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/context_hygiene_hook.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_dispatch_hook() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/hooks/dispatch_hook.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_hooks_status() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/hooks_status.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_hooks_doctor() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/hooks_doctor.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_hooks_replay() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/hooks/replay_hook.py")" || return 1
-  exec python3 "$script" "$@"
-}
-
-cmd_chat_history_checkpoint() {
-  require_python3
-  local script
-  script="$(resolve_script "scripts/chat_history.py")" || return 1
-  # Default cadence-bearing event when a user/agent invokes /chat-history-checkpoint:
-  # "phase" — explicit phase boundary, lands under per_phase / per_turn cadences.
-  exec python3 "$script" hook-append --event phase "$@"
-}
-
-cmd_hooks_install() {
-  local force=false
-  local print_only=false
-  for arg in "$@"; do
-    case "$arg" in
-      --force)   force=true ;;
-      --print)   print_only=true ;;
-      -h|--help)
-        cat <<'HELP'
-agent-config hooks:install — install the pre-commit roadmap-progress hook.
-
-Usage:
-  ./agent-config hooks:install [--force] [--print]
-
-Without flags: copies the hook to .git/hooks/pre-commit. Refuses to
-overwrite an existing pre-commit hook unless --force is given (the
-existing hook may already chain other tooling).
-
-  --print   dump the hook script to stdout (for manual chaining into an
-            existing pre-commit script, husky, lefthook, etc.)
-  --force   overwrite an existing .git/hooks/pre-commit (DESTRUCTIVE)
-HELP
-        return 0 ;;
-      *)
-        echo "❌  hooks:install: unknown argument: $arg" >&2
-        echo "    Run \`./agent-config hooks:install --help\` for usage." >&2
-        return 2 ;;
-    esac
-  done
-
-  local hook_src
-  hook_src="$(resolve_script ".agent-src/templates/hooks/pre-commit-roadmap-progress" ".augment/templates/hooks/pre-commit-roadmap-progress")" || return 1
-
-  if $print_only; then
-    cat "$hook_src"
-    return 0
-  fi
-
-  local git_dir
-  git_dir="$(git -C "$CONSUMER_ROOT" rev-parse --git-dir 2>/dev/null || true)"
-  if [[ -z "$git_dir" ]]; then
-    echo "❌  hooks:install: $CONSUMER_ROOT is not a git repository." >&2
-    return 1
-  fi
-  # Resolve relative git-dir paths (worktrees, submodules) against CONSUMER_ROOT.
-  [[ "$git_dir" != /* ]] && git_dir="$CONSUMER_ROOT/$git_dir"
-
-  local hook_dir="$git_dir/hooks"
-  local target="$hook_dir/pre-commit"
-  mkdir -p "$hook_dir"
-
-  if [[ -f "$target" ]] && ! $force; then
-    if grep -q "pre-commit-roadmap-progress" "$target" 2>/dev/null; then
-      echo "✅  hooks:install: already installed at $target"
-      return 0
-    fi
-    echo "⚠️   hooks:install: $target already exists and looks unrelated." >&2
-    echo "    Options:" >&2
-    echo "      1. Inspect it and append the snippet manually:" >&2
-    echo "         ./agent-config hooks:install --print >> $target" >&2
-    echo "      2. Replace it (destructive):" >&2
-    echo "         ./agent-config hooks:install --force" >&2
-    return 1
-  fi
-
-  cp "$hook_src" "$target"
-  chmod +x "$target"
-  echo "✅  hooks:install: pre-commit hook installed at $target"
-  echo "    To uninstall: rm $target"
-}
-
-# Wrap the interactive key installers under a stable CLI entry. The shell
-# scripts themselves enforce /dev/tty, 0600, and atomic write — this is
-# pure routing so consumers never have to know the package layout.
-cmd_keys_install_anthropic() {
-  local script
-  script="$(resolve_script "scripts/install_anthropic_key.sh")" || return 1
-  exec bash "$script" "$@"
-}
-
-cmd_keys_install_openai() {
-  local script
-  script="$(resolve_script "scripts/install_openai_key.sh")" || return 1
-  exec bash "$script" "$@"
-}
-
-# Council CLI — non-interactive wrapper around scripts.ai_council.orchestrator.
-# Three subcommands share one Python entry point; we forward the subcommand
-# verb so `./agent-config council:run --confirm` lands on `council_cli.py run`.
-cmd_council() {
-  require_python3
-  local sub="$1"; shift || true
-  local script
-  script="$(resolve_script "scripts/council_cli.py")" || return 1
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 "$script" "$sub" "$@"
-}
-
-# `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).
-cmd_update() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_update "$@"
-}
-
-# `agent-config migrate` — one-shot migration off legacy composer / npm
-# install paths onto the npx-only runtime. See scripts/_cli/cmd_migrate.py
-# (P3.5 of road-to-portable-runtime-and-update-check.md).
-cmd_migrate() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_migrate "$@"
-}
-
-# `agent-config init` — project-scope install entry point. Forwards
-# unmodified args to the bash installer. This is the canonical
-# `npx @event4u/agent-config init` consumer entry point (replaces the
-# deprecated @event4u/create-agent-config wrapper package).
-cmd_init() {
-  local script
-  script="$(resolve_script "scripts/install")" || return 1
-  exec bash "$script" "$@"
-}
-
-# `agent-config global` — user-scope install entry point. Forwards to the
-# bash installer with `--global` set (ADR-007). Phase 1.2 of
-# road-to-global-first-install.md. The bash wrapper handles option parsing
-# and forwards to `scripts/install.py --global`, where `install_global()`
-# currently scaffolds the per-tool anchor paths from USER_SCOPE_PATHS.
-# Concrete writes land in Phase 1.5 (export) and Phase 1.6 (lockfile).
-cmd_global() {
-  local script
-  script="$(resolve_script "scripts/install")" || return 1
-  exec bash "$script" --global "$@"
-}
-
-# `agent-config export` — write a tool's canonical content into a
-# user-chosen path. ADR-007 D3 / Phase 1.5 of
-# road-to-global-first-install.md. Replaces the rejected symlink-bridge.
-# See scripts/_cli/cmd_export.py for the registry and idempotency logic.
-cmd_export() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_export "$@"
-}
-
-# `agent-config sync` — replay agents/installed-tools.lock (ADR-008
-# Phase 3.3). Re-installs any tool whose bridge marker is missing on
-# disk. Typical onboarding flow: clone → `./agent-config sync` → done.
-cmd_sync() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_sync "$@"
-}
-
-# `agent-config validate` — read-only drift detection (ADR-008 Phase 3.4).
-# Surfaces marker-missing, scope-divergence, and version-drift; exits 1 on
-# any drift. Never edits the manifest or re-runs the installer.
-cmd_validate() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_validate "$@"
-}
-
-# `agent-config settings:check` — read-only YAML-subset validator for
-# `.agent-settings.yml` (P3.2 of road-to-proof-not-features.md). Contract
-# pinned in docs/contracts/settings-sync-yaml-subset.md. Exit 0 clean,
-# 1 finding(s), 2 file absent / unreadable.
-cmd_settings_check() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_settings_check "$@"
-}
-
-# `agent-config uninstall` — remove bridge markers (project) or lockfile
-# entries (global). Idempotent. Pass `--purge` to also delete deployed
-# content directories under user-scope anchors (destructive). See
-# scripts/_cli/cmd_uninstall.py.
-cmd_uninstall() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_uninstall "$@"
-}
-
-# `agent-config prune` — remove orphaned project bridge markers.
-# Drift-cleanup sibling to `uninstall`: compares on-disk markers
-# against agents/installed-tools.lock and unlinks anything not
-# declared. Hard-floors when lockfile is absent. See
-# scripts/_cli/cmd_prune.py.
-cmd_prune() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_prune "$@"
-}
-
-# `agent-config doctor` — read-only drift report against the manifest.
-# Surfaces missing / modified / foreign files. Exit 0 clean, 1 drift,
-# 2 manifest-absent. See scripts/_cli/cmd_doctor.py.
-cmd_doctor() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_doctor "$@"
-}
-
-# `agent-config versions` — list available @event4u/agent-config versions
-# on the npm registry. Marks the current pin (from .agent-settings.yml)
-# and the latest published version. Offline-tolerant. See
-# scripts/_cli/cmd_versions.py.
-cmd_versions() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_versions "$@"
-}
-
-# `agent-config explain <config|rule|route>` — print the decision chain
-# behind a configuration or routing outcome. Read-only diagnostic; never
-# edits state. See scripts/_cli/cmd_explain.py.
-cmd_explain() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_explain "$@"
-}
-
-main() {
-  local cmd="${1-}"
-  [[ $# -gt 0 ]] && shift || true
-
-  case "$cmd" in
-    mcp:render)              cmd_mcp_render "$@" ;;
-    mcp:check)               cmd_mcp_check "$@" ;;
-    mcp:setup)               cmd_mcp_setup "$@" ;;
-    mcp:run)                 cmd_mcp_run "$@" ;;
-    roadmap:progress)        cmd_roadmap_progress "$@" ;;
-    roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
-    hooks:install)           cmd_hooks_install "$@" ;;
-    keys:install-anthropic)  cmd_keys_install_anthropic "$@" ;;
-    keys:install-openai)     cmd_keys_install_openai "$@" ;;
-    first-run)               cmd_first_run "$@" ;;
-    implement-ticket)        cmd_implement_ticket "$@" ;;
-    work)                    cmd_work "$@" ;;
-    migrate-state)           cmd_migrate_state "$@" ;;
-    memory:lookup)           cmd_memory_lookup "$@" ;;
-    memory:signal)           cmd_memory_signal "$@" ;;
-    memory:hash)             cmd_memory_hash "$@" ;;
-    memory:check)            cmd_memory_check "$@" ;;
-    memory:check-proposal)   cmd_memory_check_proposal "$@" ;;
-    proposal:check)          cmd_proposal_check "$@" ;;
-    refine-ticket:detect)    cmd_refine_ticket_detect "$@" ;;
-    chat-history:hook)       cmd_chat_history_hook "$@" ;;
-    chat-history:checkpoint) cmd_chat_history_checkpoint "$@" ;;
-    roadmap-progress:hook)   cmd_roadmap_progress_hook "$@" ;;
-    onboarding-gate:hook)    cmd_onboarding_gate_hook "$@" ;;
-    context-hygiene:hook)    cmd_context_hygiene_hook "$@" ;;
-    dispatch:hook)           cmd_dispatch_hook "$@" ;;
-    hooks:status)            cmd_hooks_status "$@" ;;
-    hooks:doctor)            cmd_hooks_doctor "$@" ;;
-    hooks:replay)            cmd_hooks_replay "$@" ;;
-    telemetry:record)        cmd_telemetry_record "$@" ;;
-    telemetry:status)        cmd_telemetry_status "$@" ;;
-    telemetry:report)        cmd_telemetry_report "$@" ;;
-    council:estimate)        cmd_council estimate "$@" ;;
-    council:run)             cmd_council run "$@" ;;
-    council:render)          cmd_council render "$@" ;;
-    update)                  cmd_update "$@" ;;
-    migrate)                 cmd_migrate "$@" ;;
-    init)                    cmd_init "$@" ;;
-    global)                  cmd_global "$@" ;;
-    export)                  cmd_export "$@" ;;
-    sync)                    cmd_sync "$@" ;;
-    validate)                cmd_validate "$@" ;;
-    settings:check)          cmd_settings_check "$@" ;;
-    uninstall)               cmd_uninstall "$@" ;;
-    prune)                   cmd_prune "$@" ;;
-    doctor)                  cmd_doctor "$@" ;;
-    versions)                cmd_versions "$@" ;;
-    explain)                 cmd_explain "$@" ;;
-    help|--help|-h|"")
-      # Optional `--tier=0|1|all` filter (default 0).
-      local tier_arg="0"
-      for arg in "$@"; do
-        case "$arg" in
-          --tier=0|--tier=1|--tier=all) tier_arg="${arg#--tier=}" ;;
-          --tier|-t) ;; # next arg
-          0|1|all)
-            # Positional after --tier/-t.
-            tier_arg="$arg" ;;
-          --all) tier_arg="all" ;;
-        esac
-      done
-      usage "$tier_arg" ;;
-    --version|-V)            print_version ;;
-    *)
-      echo "❌  agent-config: unknown command: $cmd" >&2
-      echo "    Run \`./agent-config help\` for the command list." >&2
-      exit 2
-      ;;
-  esac
-}
-
-# Pre-flight pin resolver: when `.agent-settings.yml` carries a
-# non-empty `agent_config_version` that differs from the running
-# package version, re-exec via `npx @event4u/agent-config@<pin>`.
-# Skipped for `--version`, `help`, `update` and `migrate` (so consumers
-# can escape a bad pin or run the legacy-cleanup before a pin exists),
-# and when `AGENT_CONFIG_NO_PIN_REEXEC=1`. See P3.2 of
-# road-to-portable-runtime-and-update-check.md.
-maybe_pin_reexec() {
-  local cmd="${1-}"
-  case "$cmd" in
-    help|--help|-h|--version|-V|update|migrate|init|"") return 0 ;;
-  esac
-  if ! command -v python3 >/dev/null 2>&1; then
-    return 0
-  fi
-  local installed
-  installed="$(print_version)"
-  [[ -z "$installed" || "$installed" == "unknown" ]] && return 0
-  env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._lib.pin_resolver \
-    --cwd "$CONSUMER_ROOT" --installed "$installed" -- "$@" || true
-}
-
-# Post-subcommand banner: best-effort daily update-check notice on
-# stderr. Runs after the dispatch returns (subshell wrapper below)
-# so the banner appears post-output and never delays the subcommand.
-# Suppressed in CI, on non-TTY stdout, by AGENT_CONFIG_NO_UPDATE_CHECK=1,
-# or by `update_check.enabled: false` in settings. See P2 of
-# road-to-portable-runtime-and-update-check.md.
-run_update_check_banner() {
-  local cmd="${1-}"
-  case "$cmd" in
-    help|--help|-h|--version|-V|"") return 0 ;;
-  esac
-  if ! command -v python3 >/dev/null 2>&1; then
-    return 0
-  fi
-  local banner_script="$PACKAGE_ROOT/scripts/check_update_banner.py"
-  [[ -f "$banner_script" ]] || return 0
-  python3 "$banner_script" --cwd "$CONSUMER_ROOT" 2>/dev/null || true
-}
-
-# Global `--root <path>` / `--root=<path>` parsing (Step 8 A3).
-# Strips the flag from $@, validates the path is an existing directory,
-# and exports `AGENT_CONFIG_PROJECT_ROOT` + `AGENT_CONFIG_ROOT_OVERRIDE=1`
-# so the Python resolver picks origin=root-flag with fail-loud semantics.
-# Invalid path → exit 2 immediately, no fallback to anchor walk or CWD.
-parse_global_root_flag() {
-  local -a filtered=()
-  local root_value=""
-  local saw_flag=false
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --root)
-        saw_flag=true
-        if [[ $# -lt 2 ]]; then
-          echo "❌  agent-config: --root requires a path argument" >&2
-          exit 2
-        fi
-        root_value="$2"
-        shift 2
-        ;;
-      --root=*)
-        saw_flag=true
-        root_value="${1#--root=}"
-        shift
-        ;;
-      *)
-        filtered+=("$1")
-        shift
-        ;;
-    esac
-  done
-  if $saw_flag; then
-    if [[ -z "$root_value" ]]; then
-      echo "❌  agent-config: --root requires a non-empty path" >&2
-      exit 2
-    fi
-    if [[ ! -e "$root_value" ]]; then
-      echo "❌  agent-config: --root points to a path that does not exist: $root_value" >&2
-      exit 2
-    fi
-    if [[ ! -d "$root_value" ]]; then
-      echo "❌  agent-config: --root points to a non-directory: $root_value" >&2
-      exit 2
-    fi
-    # Absolutize so downstream Python sees a fully-resolved path.
-    root_value="$(cd "$root_value" && pwd)"
-    export AGENT_CONFIG_PROJECT_ROOT="$root_value"
-    export AGENT_CONFIG_ROOT_OVERRIDE=1
-    # Wrapper-coupling guard: when invoked through a consumer-root wrapper
-    # (CONSUMER_ROOT != root_value), surface a one-line warning on stderr
-    # so the operator notices the divergence. Non-fatal: --root is the
-    # deliberate override channel.
-    if [[ "$CONSUMER_ROOT" != "$root_value" ]]; then
-      echo "⚠️   agent-config: --root ($root_value) differs from wrapper CWD ($CONSUMER_ROOT)" >&2
-    fi
-  fi
-  # Re-emit the filtered argv via a global array consumed by main().
-  GLOBAL_FILTERED_ARGS=("${filtered[@]+"${filtered[@]}"}")
-}
-
-declare -a GLOBAL_FILTERED_ARGS
-parse_global_root_flag "$@"
-set -- "${GLOBAL_FILTERED_ARGS[@]+"${GLOBAL_FILTERED_ARGS[@]}"}"
-
-# Pin re-exec runs before dispatch — if it triggers, the process is
-# replaced and nothing else here matters.
-maybe_pin_reexec "$@"
-
-# Dispatch in a subshell so internal ``exec`` calls do not replace this
-# process — we still get to run the post-subcommand banner.
-( main "$@" )
-rc=$?
-run_update_check_banner "${1-}"
-exit "$rc"
+here="$(cd -- "$(dirname -- "$src")" && pwd)"
+ts_entry="$here/../dist/cli/agent-config.js"
+legacy_entry="$here/_dispatch.bash"
+source_marker="$here/../src/cli/registry.ts"
+
+# Suppress the deprecation warning when invoked from a source checkout
+# (maintainer path) — `src/` is not shipped in the published tarball.
+if [[ "${AGENT_CONFIG_QUIET_DEPRECATION:-0}" != "1" && ! -f "$source_marker" ]]; then
+  echo "warning: scripts/agent-config is deprecated; use 'npx @event4u/agent-config' instead" >&2
+fi
+
+if [[ -f "$ts_entry" ]]; then
+  exec node "$ts_entry" "$@"
+fi
+
+if [[ -f "$legacy_entry" ]]; then
+  exec bash "$legacy_entry" "$@"
+fi
+
+echo "❌  agent-config: neither dist/cli/agent-config.js nor scripts/_dispatch.bash found" >&2
+echo "    Run 'npm run build' in the package root to produce the TS binary." >&2
+exit 1