@event4u/agent-config 4.9.0 → 5.0.0

package/scripts/_dispatch.bash

@@ -101,8 +101,12 @@ Tier 1 — power-user (release shape, audit, migration):
                              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)
+  migrate                    One-shot, opinionated migration off every legacy install /
+                             state shape — removes composer / npm package entries,
+                             deletes legacy symlinks + project-local config, migrates
+                             the v0 work-engine state file, refreshes .gitignore.
+                             Wizard recreates fresh config. Single flag: --dry-run
+                             (preview only). Contract: docs/contracts/migrate-command.md
   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)
@@ -138,10 +142,6 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              ~/.event4u/agent-config/ (the global-only consumer surface,
                              ADR-020). Idempotent; --force overwrites a non-empty global
                              file, --dry-run lists intended copies with zero writes.
-  migrate-to-global          One-shot legacy → global-only migration (Phase 5,
-                             road-to-global-only-install.md). Copy → verify → move →
-                             bridge. Runs lint_global_paths.py first. Flags:
-                             --dry-run, --force, --rollback, --skip-perms-gate.
   hooks:install              Install the combined pre-commit hook (roadmap-progress
                              + ADR-013 artefact frontmatter lint).
                              (use --print to dump it, --force to overwrite an existing hook)
@@ -156,8 +156,6 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              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)
@@ -187,7 +185,7 @@ EOF
   if [[ "$tier" == "0" ]]; then
     cat <<'EOF'
 
-(Hidden: 15 Tier-1 + 26 Tier-2 commands. Run `./agent-config --help --tier=1`
+(Hidden: 15 Tier-1 + 24 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
@@ -245,7 +243,6 @@ Examples (Tier 2):
   ./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
@@ -407,21 +404,6 @@ cmd_work() {
   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
@@ -560,26 +542,43 @@ cmd_chat_history_checkpoint() {
 cmd_hooks_install() {
   local force=false
   local print_only=false
+  local claude_mode=false
+  local regen_mode=false
   for arg in "$@"; do
     case "$arg" in
       --force)   force=true ;;
       --print)   print_only=true ;;
+      --claude|--lifecycle)  claude_mode=true ;;
+      --regen)               regen_mode=true ;;
       -h|--help)
         cat <<'HELP'
-agent-config hooks:install — install the combined pre-commit hook
-(roadmap-progress + ADR-013 artefact frontmatter lint).
+agent-config hooks:install — install hooks scaffolding.
 
-Usage:
-  ./agent-config hooks:install [--force] [--print]
+Three modes, picked by flag combination:
+
+  (no flag)           Install the legacy .git/hooks/pre-commit gate
+                      (roadmap-progress + ADR-013 frontmatter lint).
+                      Default for backwards compatibility.
 
-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). Each concern only
-runs when relevant files are staged — zero overhead otherwise.
+  --claude            Wire Claude Code lifecycle hooks: write
+  (--lifecycle alias) .claude/settings.json with the plugin enabled +
+                      ensure the ./agent-config symlink → scripts/agent-config
+                      at the consumer root. Idempotent.
+
+  --regen             Provision the roadmap-progress regenerator at
+                      .augment/scripts/update_roadmap_progress.py
+                      (canonical path per docs/contracts/hook-architecture-v1.md
+                      § Regenerator location). Idempotent.
+
+  --claude --regen    Both. The minimal-viable-scaffolding fix path
+                      for marketplace-install consumers — see
+                      road-to-hooks-actually-fire-in-consumers Phase 4.
+
+Other flags:
+  --print             Dump the legacy pre-commit hook script to stdout
+                      (for manual chaining into husky / lefthook / etc.)
+  --force             Overwrite an existing .git/hooks/pre-commit (DESTRUCTIVE)
 
-  --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 ;;
       *)
@@ -589,6 +588,30 @@ HELP
     esac
   done
 
+  # Phase 4 of road-to-hooks-actually-fire-in-consumers: --claude
+  # and --regen are mutually compatible with each other but NOT with
+  # the legacy pre-commit mode. Routing:
+  if $claude_mode || $regen_mode; then
+    local rc=0
+    if $claude_mode; then
+      _hooks_install_claude_lifecycle || rc=$?
+    fi
+    if $regen_mode && [[ $rc -eq 0 ]]; then
+      _hooks_install_regenerator || rc=$?
+    fi
+    return $rc
+  fi
+
+  # Default-path guidance for callers who passed no flag at all (Phase 4
+  # Step 3 — make the new modes discoverable without breaking the
+  # legacy default behaviour).
+  if [[ $# -eq 0 ]]; then
+    echo "ℹ️   hooks:install: no flag given — installing the legacy" >&2
+    echo "    .git/hooks/pre-commit gate. Use --claude (or --lifecycle)" >&2
+    echo "    to wire Claude Code hooks, --regen to install the" >&2
+    echo "    regenerator. See --help for details." >&2
+  fi
+
   local hook_src
   hook_src="$(resolve_script ".agent-src/templates/hooks/pre-commit-roadmap-progress" ".augment/templates/hooks/pre-commit-roadmap-progress")" || return 1
 
@@ -630,6 +653,92 @@ HELP
   echo "    To uninstall: rm $target"
 }
 
+# Phase 4 of road-to-hooks-actually-fire-in-consumers — `--claude`
+# (and its `--lifecycle` alias) path. Writes the minimal-viable Claude
+# Code lifecycle wiring: enables the plugin in `.claude/settings.json`
+# (idempotent dict-merge) AND ensures `./agent-config` is executable
+# at the consumer root (symlink → scripts/agent-config in the package).
+_hooks_install_claude_lifecycle() {
+  local settings_dir="$CONSUMER_ROOT/.claude"
+  local settings_file="$settings_dir/settings.json"
+  mkdir -p "$settings_dir"
+
+  # Idempotent merge using python3 — bash JSON edits are unsafe with
+  # nested keys. Falls back to a fresh-write when the file is absent.
+  python3 - "$settings_file" <<'PY' || return 1
+import json
+import sys
+from pathlib import Path
+
+target = Path(sys.argv[1])
+data = {}
+if target.is_file():
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"❌  hooks:install --claude: existing {target} is not valid JSON ({exc})", file=sys.stderr)
+        sys.exit(1)
+    if not isinstance(data, dict):
+        print(f"❌  hooks:install --claude: existing {target} is not a JSON object", file=sys.stderr)
+        sys.exit(1)
+enabled = data.setdefault("enabledPlugins", {})
+if not isinstance(enabled, dict):
+    print(f"❌  hooks:install --claude: enabledPlugins in {target} is not an object", file=sys.stderr)
+    sys.exit(1)
+enabled["agent-config@event4u-agent-config"] = True
+target.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+print(f"✅  hooks:install --claude: enabled plugin in {target}")
+PY
+
+  # Symlink the package's agent-config wrapper into the consumer root.
+  # Idempotent — replace stale symlinks; skip if already correct.
+  local link="$CONSUMER_ROOT/agent-config"
+  local link_target
+  # The package script lives at <package_root>/scripts/agent-config.
+  # Try to resolve the package root via the dispatcher's own location.
+  local package_root
+  package_root="$(dirname "$(dirname "$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "${BASH_SOURCE[0]}")")")"
+  link_target="$package_root/scripts/agent-config"
+
+  if [[ ! -e "$link_target" ]]; then
+    echo "⚠️   hooks:install --claude: package script not found at $link_target" >&2
+    echo "    Skipping symlink; the plugin-enable step succeeded." >&2
+    return 0
+  fi
+
+  if [[ -L "$link" ]]; then
+    local current
+    current="$(readlink "$link" 2>/dev/null || true)"
+    if [[ "$current" == "$link_target" ]]; then
+      echo "✅  hooks:install --claude: ./agent-config symlink already current"
+      return 0
+    fi
+    rm "$link"
+  elif [[ -e "$link" ]]; then
+    echo "⚠️   hooks:install --claude: ./agent-config exists but is not a symlink — leaving it alone" >&2
+    return 0
+  fi
+
+  if ln -s "$link_target" "$link" 2>/dev/null; then
+    echo "✅  hooks:install --claude: ./agent-config symlink → $link_target"
+  else
+    echo "⚠️   hooks:install --claude: could not create ./agent-config symlink" >&2
+    return 1
+  fi
+}
+
+# Phase 4 of road-to-hooks-actually-fire-in-consumers — `--regen` path.
+# Provisions the canonical regenerator via the shared helper module.
+# We invoke the script by path (not module form) so it works from any
+# CONSUMER_ROOT — module form requires the package's `scripts` dir to
+# be on PYTHONPATH which is not the case when invoked from a consumer.
+_hooks_install_regenerator() {
+  local package_root
+  package_root="$(dirname "$(dirname "$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "${BASH_SOURCE[0]}")")")"
+  python3 "$package_root/scripts/_lib/install_regenerator.py" "$CONSUMER_ROOT" "$package_root" 2>&1
+  return $?
+}
+
 # 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.
@@ -731,23 +840,14 @@ cmd_settings_check() {
 # `agent-config settings:migrate` — lift project-local
 # .agent-settings.yml / .agent-user.yml into ~/.event4u/agent-config/.
 # Phase 2.4 of road-to-global-only-install.md. Read-only on the source —
-# the destructive move step is owned by `migrate-to-global` (Phase 5).
+# the destructive move step is owned by the unified `agent-config migrate`
+# (see docs/contracts/migrate-command.md).
 # Exit 0 success / no-op, 1 non-empty global without --force or parse error.
 cmd_settings_migrate() {
   require_python3
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_settings_migrate "$@"
 }
 
-# `agent-config migrate-to-global` — Phase 5.1 + 5.3 + 5.5 of
-# road-to-global-only-install.md. Order: copy → verify → move → bridge.
-# Runs the lint_global_paths.py permissions gate first (Phase 5.0 / A7).
-# Flags: --dry-run (zero writes), --force (overwrite non-empty global),
-# --rollback (reverse the latest .legacy-pre-global-only/<stamp>/ snapshot).
-cmd_migrate_to_global() {
-  require_python3
-  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_migrate_to_global "$@"
-}
-
 # `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
@@ -809,7 +909,6 @@ main() {
     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 "$@" ;;
@@ -841,7 +940,6 @@ main() {
     validate)                cmd_validate "$@" ;;
     settings:check)          cmd_settings_check "$@" ;;
     settings:migrate)        cmd_settings_migrate "$@" ;;
-    migrate-to-global)       cmd_migrate_to_global "$@" ;;
     uninstall)               cmd_uninstall "$@" ;;
     prune)                   cmd_prune "$@" ;;
     doctor)                  cmd_doctor "$@" ;;

package/scripts/_lib/install_regenerator.py

@@ -0,0 +1,129 @@
+"""Provision the roadmap-progress regenerator into a consumer.
+
+Phase 3 of `road-to-hooks-actually-fire-in-consumers`.
+
+The roadmap-progress hook (`scripts/roadmap_progress_hook.py`)
+searches three locations for `update_roadmap_progress.py`. Only the
+**canonical** location is reliable in marketplace-install consumers:
+`.augment/scripts/update_roadmap_progress.py`. This helper pins the
+contract and copies the script idempotently.
+
+Canonical paths:
+
+| Side | Path |
+|---|---|
+| Source-of-truth (package) | `packages/core/.agent-src.uncondensed/scripts/update_roadmap_progress.py` |
+| Package self-use (dogfooding) | `.agent-src/scripts/update_roadmap_progress.py` (and `.augment/scripts/update_roadmap_progress.py` after `task sync`) |
+| Consumer install target | `<consumer_root>/.augment/scripts/update_roadmap_progress.py` |
+
+Used by:
+  - `scripts/install.py`'s init / full-install path.
+  - `scripts/_dispatch.bash::cmd_hooks_install --regen`.
+
+Contract: idempotent; preserves executable bit; never blocks.
+"""
+from __future__ import annotations
+
+import shutil
+import stat
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+REGENERATOR_REL = "scripts/update_roadmap_progress.py"
+"""Path of the script relative to the package's source-of-truth tree."""
+
+CONSUMER_REGENERATOR_REL = ".augment/scripts/update_roadmap_progress.py"
+"""Canonical destination path inside a consumer repo."""
+
+
+def package_source(package_root: Path) -> Optional[Path]:
+    """Resolve the package-side source-of-truth for the regenerator.
+
+    Searches the package layout in priority order:
+      1. `packages/core/.agent-src.uncondensed/scripts/update_roadmap_progress.py`
+      2. `.agent-src/scripts/update_roadmap_progress.py` (condensed projection)
+      3. `.augment/scripts/update_roadmap_progress.py` (tool projection)
+
+    Returns the first existing file, or None if none exist (which is
+    a misconfigured package and should be a hard error at the call
+    site).
+    """
+    candidates = [
+        package_root / "packages" / "core" / ".agent-src.uncondensed" / REGENERATOR_REL,
+        package_root / ".agent-src" / REGENERATOR_REL,
+        package_root / ".augment" / REGENERATOR_REL,
+    ]
+    for c in candidates:
+        if c.is_file():
+            return c
+    return None
+
+
+def consumer_target(consumer_root: Path) -> Path:
+    """Canonical destination path inside the consumer repo."""
+    return consumer_root / CONSUMER_REGENERATOR_REL
+
+
+def install_regenerator(package_root: Path, consumer_root: Path) -> tuple[bool, str]:
+    """Copy the regenerator into the consumer. Idempotent.
+
+    Returns (success, message). `success=False` means the call site
+    should surface the message; the helper never raises.
+    """
+    source = package_source(package_root)
+    if source is None:
+        return (
+            False,
+            "regenerator source not found in package "
+            "(searched packages/core/.agent-src.uncondensed/, "
+            ".agent-src/, .augment/)",
+        )
+    target = consumer_target(consumer_root)
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        # Idempotent: skip the copy if content is byte-identical.
+        if target.exists() and target.read_bytes() == source.read_bytes():
+            return (True, f"regenerator already current at {target}")
+        shutil.copyfile(source, target)
+        # Preserve executable bit so the hook can subprocess-call it.
+        mode = target.stat().st_mode
+        target.chmod(
+            mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+        )
+        return (True, f"regenerator installed at {target}")
+    except OSError as exc:
+        return (False, f"failed to install regenerator: {exc}")
+
+
+def is_installed(consumer_root: Path) -> bool:
+    """Quick boolean — does the canonical regenerator exist + is executable?"""
+    target = consumer_target(consumer_root)
+    if not target.is_file():
+        return False
+    import os
+    return os.access(target, os.X_OK)
+
+
+def main() -> int:
+    """CLI entry point — `python3 -m scripts._lib.install_regenerator <consumer-root>`."""
+    if len(sys.argv) < 2:
+        print(
+            "usage: install_regenerator.py <consumer_root> [<package_root>]",
+            file=sys.stderr,
+        )
+        return 2
+    consumer_root = Path(sys.argv[1]).resolve()
+    package_root = (
+        Path(sys.argv[2]).resolve()
+        if len(sys.argv) > 2
+        else Path(__file__).resolve().parent.parent.parent
+    )
+    ok, msg = install_regenerator(package_root, consumer_root)
+    print(msg)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())