Merge pull request #48 from codejunkie99/codex/resolve-upgrade-issues

Fix upgrade path and skill manifest drift

Author: codejunkie99

CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **`agentic-stack upgrade`.** Adds a safe project migration verb that refreshes
+  skeleton-owned `.agent` infrastructure, copies new skills, supports
+  `--dry-run`/`--yes`, and leaves adapter configs plus user memory untouched.
+- **`agentic-stack sync-manifest`.** Rebuilds `.agent/skills/_manifest.jsonl`
+  from installed `SKILL.md` frontmatter so copied skills can trigger correctly.
+
+### Fixed
+- Install/add now re-sync the skill manifest when a project already has
+  `.agent/skills`, preventing `_index.md` / `_manifest.jsonl` drift.
+- `doctor` now warns when Claude Code hook commands reference missing `.agent`
+  Python files or when hook scripts are present but not wired in
+  `.claude/settings.json`.
+
 ## [0.15.0] — 2026-05-06
 
 Minor release. Adds a production dashboard TUI for installed agentic-stack

README.md

@@ -154,6 +154,9 @@ verb-style subcommands (works with both `install.sh` and `install.ps1`):
 ./install.sh doctor              # read-only audit; green / yellow / red per adapter
 ./install.sh manage              # interactive TUI: header pane + menu loop for add/remove/audit
 ./install.sh transfer            # onboarding-style wizard: export/import memory as a curl bridge
+./install.sh upgrade --dry-run   # preview safe .agent infrastructure refresh
+./install.sh upgrade --yes       # copy latest harness/memory/tools + new skills
+./install.sh sync-manifest       # rebuild .agent/skills/_manifest.jsonl from SKILL.md frontmatter
 ./install.sh remove cursor       # confirm prompt + delete; no quarantine, no undo
 ```
 
@@ -172,6 +175,16 @@ synthesizes `install.json` from on-disk adapter signals so the new
 backend can track them. Installing on top without migration would
 orphan the prior installs.
 
+Upgrading an already-installed project after `brew upgrade`? Run
+`agentic-stack upgrade --dry-run` in the project first, then
+`agentic-stack upgrade --yes` to refresh only skeleton-owned `.agent`
+infrastructure (`harness/**/*.py`, top-level `memory/*.py`, `tools/*.py`,
+the generated skill index, and new skill directories). It does not rewrite
+`CLAUDE.md`, `.claude/settings.json`, personal/semantic/episodic/working
+memory, candidates, or existing skill directories. `agentic-stack
+sync-manifest` is available as a repair command if `_manifest.jsonl` drifts
+from installed `SKILL.md` files.
+
 ## Onboarding wizard
 
 If you ran bare `./install.sh` (no adapter name), the wizard starts
@@ -375,6 +388,8 @@ harness_manager/                # v0.9.0 manifest-driven Python backend
 ├── transfer_tui.py             # onboarding-style memory transfer wizard
 ├── transfer_plan.py            # natural-language target/scope planning
 ├── transfer_bundle.py          # export/import bundle codec + merge logic
+├── skill_manifest.py           # rebuilds skills/_manifest.jsonl from SKILL.md
+├── upgrade.py                  # safe .agent infrastructure refresh
 └── cli.py                      # argparse dispatcher for install.sh / install.ps1
 
 docs/                           # architecture, getting-started, per-harness

harness_manager/__init__.py

@@ -2,7 +2,7 @@
 
 This package is the implementation backend for `./install.sh` and `./install.ps1`.
 The user-facing surface is plain verbs: install, add, remove, doctor, status,
-dashboard, manage, and transfer.
+dashboard, manage, transfer, upgrade, and sync-manifest.
 The "harness_manager" name is internal only and never appears in CLI help, docs,
 or error messages users see.
 """

harness_manager/cli.py

@@ -14,12 +14,25 @@
 from . import install as install_mod
 from . import remove as remove_mod
 from . import schema as schema_mod
+from . import skill_manifest as skill_manifest_mod
 from . import state as state_mod
 from . import status as status_mod
+from . import upgrade as upgrade_mod
 from . import __version__
 
 
-VERBS = {"add", "remove", "doctor", "status", "manage", "dashboard", "dash", "transfer"}
+VERBS = {
+    "add",
+    "remove",
+    "doctor",
+    "status",
+    "manage",
+    "dashboard",
+    "dash",
+    "transfer",
+    "upgrade",
+    "sync-manifest",
+}
 
 
 def _stack_root() -> Path:
@@ -263,6 +276,37 @@ def cmd_transfer(args: list[str], target: Path) -> int:
     return transfer_tui.run(args, target_root=target, stack_root=_stack_root())
 
 
+def cmd_sync_manifest(target: Path) -> int:
+    try:
+        skill_manifest_mod.sync_manifest(target)
+        return 0
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+def cmd_upgrade(args: list[str], yes: bool) -> int:
+    dry_run = False
+    target_args: list[str] = []
+    for arg in args:
+        if arg == "--dry-run":
+            dry_run = True
+        elif arg in ("--yes", "-y"):
+            yes = True
+        else:
+            target_args.append(arg)
+    if len(target_args) > 1:
+        print("usage: ./install.sh upgrade [target-dir] [--dry-run] [--yes]", file=sys.stderr)
+        return 2
+    target = Path(target_args[0]) if target_args else Path.cwd()
+    return upgrade_mod.upgrade(
+        target_root=target,
+        stack_root=_stack_root(),
+        dry_run=dry_run,
+        yes=yes,
+    )
+
+
 def cmd_bare(target: Path, wizard_flags: list[str]) -> int:
     """`./install.sh` with no args.
 
@@ -342,6 +386,8 @@ def cmd_bare(target: Path, wizard_flags: list[str]) -> int:
     print("  ./install.sh dashboard   # interactive project dashboard")
     print("  ./install.sh manage      # interactive TUI for adapter management")
     print("  ./install.sh transfer    # onboarding-style memory transfer wizard")
+    print("  ./install.sh upgrade     # safely refresh .agent infrastructure")
+    print("  ./install.sh sync-manifest  # repair skills/_manifest.jsonl")
     return 2
 
 
@@ -487,6 +533,11 @@ def main(argv: list[str] | None = None) -> int:
             return cmd_dashboard(target, plain=plain)
         if verb == "transfer":
             return cmd_transfer(rest[1:], Path.cwd())
+        if verb == "upgrade":
+            return cmd_upgrade(rest[1:], yes=yes)
+        if verb == "sync-manifest":
+            target = Path(rest[1]) if len(rest) >= 2 else Path.cwd()
+            return cmd_sync_manifest(target)
 
     # Treat as adapter name (existing UX)
     adapter = first

harness_manager/doctor.py

@@ -11,6 +11,8 @@
 from __future__ import annotations
 
 import os
+import json
+import shlex
 import shutil
 import sys
 from pathlib import Path
@@ -234,6 +236,12 @@ def _audit_adapter(
             # Unknown post_install action — just record
             lines.append(f"post_install {action}: {st}")
 
+    if adapter_name == "claude-code":
+        hook_status, hook_lines = _audit_claude_hook_wiring(target_root)
+        if hook_lines:
+            lines.extend(hook_lines)
+            status_overall = max(status_overall, hook_status, key=_status_rank)
+
     # .agent/ brain still intact?
     if not (target_root / ".agent" / "AGENTS.md").is_file():
         lines.append(".agent/AGENTS.md missing — brain not present")
@@ -275,6 +283,91 @@ def _status_rank(s: str) -> int:
     return {GREEN: 0, YELLOW: 1, RED: 2}[s]
 
 
+def _audit_claude_hook_wiring(target_root: Path) -> tuple[str, list[str]]:
+    settings = target_root / ".claude" / "settings.json"
+    if not settings.is_file():
+        return GREEN, []
+    try:
+        data = json.loads(settings.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        return YELLOW, [f".claude/settings.json unreadable JSON: {e}"]
+
+    referenced = _claude_hook_references(data)
+    lines: list[str] = []
+    missing = [
+        rel
+        for rel in sorted(referenced)
+        if rel.startswith(".agent/") and not (target_root / rel).is_file()
+    ]
+    if missing:
+        lines.append(f"missing hook command file(s): {', '.join(missing)}")
+
+    hooks_dir = target_root / ".agent" / "harness" / "hooks"
+    if hooks_dir.is_dir():
+        wired = {rel for rel in referenced if rel.startswith(".agent/harness/hooks/")}
+        orphaned = []
+        for path in sorted(hooks_dir.glob("*.py")):
+            if _ignore_claude_orphan_candidate(path.name):
+                continue
+            rel = path.relative_to(target_root).as_posix()
+            if rel not in wired:
+                orphaned.append(rel)
+        if orphaned:
+            lines.append(
+                "orphaned hook files not referenced by .claude/settings.json: "
+                + ", ".join(orphaned)
+            )
+    return (YELLOW if lines else GREEN), lines
+
+
+def _claude_hook_references(settings: dict) -> set[str]:
+    refs: set[str] = set()
+    hooks = settings.get("hooks") or {}
+    if not isinstance(hooks, dict):
+        return refs
+    for entries in hooks.values():
+        if not isinstance(entries, list):
+            continue
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            for hook in entry.get("hooks") or []:
+                if not isinstance(hook, dict):
+                    continue
+                command = hook.get("command")
+                if isinstance(command, str):
+                    refs.update(_agent_paths_from_command(command))
+    return refs
+
+
+def _agent_paths_from_command(command: str) -> set[str]:
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        tokens = command.split()
+    refs: set[str] = set()
+    for token in tokens:
+        if ".agent/" not in token:
+            continue
+        rel = token[token.index(".agent/"):].strip(";,")
+        if rel.endswith(".py"):
+            refs.add(rel)
+    return refs
+
+
+def _ignore_claude_orphan_candidate(filename: str) -> bool:
+    if filename == "__init__.py" or filename.startswith("_"):
+        return True
+    if filename in {
+        "on_failure.py",
+        "post_execution.py",
+        "pre_tool_call.py",
+        "pi_post_tool.py",
+    }:
+        return True
+    return False
+
+
 def _summary(doc: dict, any_red: bool) -> str:
     n = len(doc.get("adapters", {}))
     if any_red:

harness_manager/install.py

@@ -13,6 +13,7 @@
 
 from . import post_install as post_install_mod
 from . import schema as schema_mod
+from . import skill_manifest as skill_manifest_mod
 from . import state as state_mod
 from . import __version__
 
@@ -189,6 +190,8 @@ def install(
     if not target_agent.exists():
         shutil.copytree(stack_root / ".agent", target_agent)
         log("  + .agent/ (portable brain)")
+    if (target_agent / "skills").is_dir():
+        skill_manifest_mod.sync_manifest(target_root, log=lambda _msg: None)
 
     files_written: list[str] = []        # we created — safe for remove to delete
     files_overwritten: list[str] = []    # we modified but file pre-existed — DO NOT delete on remove