@christang/keel 5.74.0 → 5.75.0

package/README.md

@@ -55,8 +55,12 @@ claude plugin marketplace add TanglmChris/keel
 claude plugin install keel@keel-marketplace
 ```
 
-After an update, `/reload-plugins` applies it in the running session; otherwise it applies at the
-next start.
+Updates arrive by themselves once a project is set up: `keel --init --target claude` (and
+`keel --install`) declares auto-update for `keel-marketplace` in the project's
+`.claude/settings.json`, which Claude reads before its own default of off. A new release is fetched
+in the background after a session's first message; `/reload-plugins` applies it in the running
+session, and otherwise it applies at the next start. To opt out, set that entry's `autoUpdate` to
+`false`; Keel keeps a value the project states, and `keel --doctor` reports which one is declared.
 
 **Codex, and your own terminal** — install the CLI as well (it also installs the bundled
 OpenSpec CLI):

package/README.zh-CN.md

@@ -46,7 +46,10 @@ claude plugin marketplace add TanglmChris/keel
 claude plugin install keel@keel-marketplace
 ```
 
-更新之后，在当前会话执行 `/reload-plugins` 即可生效；不执行的话，下次启动时生效。
+项目初始化后，更新会自己到来：`keel --init --target claude`（以及 `keel --install`）会在项目的
+`.claude/settings.json` 里为 `keel-marketplace` 声明自动更新，Claude 先读这个声明，而不是它默认的"关闭"。
+新版本会在会话发出第一条消息后在后台下载；执行 `/reload-plugins` 即在当前会话生效，否则下次启动时生效。
+不想自动更新，就把那一项的 `autoUpdate` 设为 `false`；项目写明的值 Keel 会保留，`keel --doctor` 会报告当前声明的是哪一个。
 
 **Codex，以及你自己的终端** —— 另外装一份 CLI（同时装上捆绑的 OpenSpec CLI）：
 

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.74.0 -->
+<!-- keel:start version=5.75.0 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.

package/bin/keel.js

@@ -755,6 +755,46 @@ function openspecReportedVersion(command) {
   return match ? match[0] : null;
 }
 
+// What the project declares about Keel plugin auto-update (#164). Claude reads
+// it first from `autoUpdate` on the marketplace's `extraKnownMarketplaces`
+// entry, and `keel --install --target claude` writes it. The host reports no
+// auto-update state Keel could read, so this is the declaration only; whether
+// updates actually arrive is the host's to show.
+function pluginAutoUpdateDeclaration(repo) {
+  const settingsPath = path.join(repo, ".claude", "settings.json");
+  const observation =
+    "Keel reads the declaration; the host does not expose whether updates run";
+  let entry;
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    entry = ((settings && settings.extraKnownMarketplaces) || {})[
+      "keel-marketplace"
+    ];
+  } catch {
+    entry = undefined;
+  }
+  if (entry && entry.autoUpdate === true) {
+    return [
+      "ok",
+      `.claude/settings.json declares keel-marketplace autoUpdate: true; ${observation}`,
+    ];
+  }
+  if (entry && entry.autoUpdate === false) {
+    return [
+      "manual",
+      ".claude/settings.json declares keel-marketplace autoUpdate: false, "
+        + "which is the project's choice; updates arrive only through "
+        + "`claude plugin update`",
+    ];
+  }
+  return [
+    "manual",
+    "not declared, so Claude leaves auto-update off for this marketplace; "
+      + "run keel --install --target claude, or enable it under /plugin → "
+      + "Marketplaces",
+  ];
+}
+
 // The root is the repository under diagnosis, never PACKAGE_ROOT. Rooting this
 // at Keel's own install location made the line a statement about a repository
 // the reader was never shown: a consumer pinning 9.9.9 was told the version
@@ -1572,6 +1612,10 @@ function printTargetSurface(repo, target) {
             : "claude plugin install keel@<marketplace>"
         } and verify in a fresh session`
     );
+    if (target === "claude") {
+      const [status, detail] = pluginAutoUpdateDeclaration(repo);
+      printDoctorLine("plugin auto-update", status, detail);
+    }
   }
 
   const openspecSkillRoot = openspecSkillRootForTarget(target);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@christang/keel",
-  "version": "5.74.0",
+  "version": "5.75.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@christang/keel",
-      "version": "5.74.0",
+      "version": "5.75.0",
       "license": "MIT",
       "dependencies": {
         "@fission-ai/openspec": "^1.4.1"

package/package.json

@@ -2,7 +2,7 @@
   "name": "@christang/keel",
   "displayName": "Keel",
   "description": "Keel OpenSpec execution discipline CLI for Claude Code, Codex, and OpenCode.",
-  "version": "5.74.0",
+  "version": "5.75.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/plugins/keel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.74.0",
+  "version": "5.75.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.74.0",
+  "version": "5.75.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/scripts/install_to_repo.py

@@ -532,6 +532,13 @@ def collect_actions(repo: Path, target: str) -> list[InstallAction]:
         )
     if "claude" in targets and not unmanaged_keel_content_warning(repo, "CLAUDE.md"):
         actions.append(managed_content_action("CLAUDE.md", CLAUDE_IMPORT_BLOCK))
+    if "claude" in targets:
+        actions.append(
+            InstallAction(
+                relative_path=Path(".claude/settings.json"),
+                strategy="claude-marketplace-settings",
+            )
+        )
 
     actions.append(openspec_config_action())
     actions.append(keel_config_action())
@@ -923,6 +930,82 @@ def action_source_content(action: InstallAction) -> str:
     return action.content or ""
 
 
+# Claude reads a marketplace's auto-update setting first from `autoUpdate` on
+# its `extraKnownMarketplaces` entry in any settings file, and defaults it off
+# for every marketplace that is not Anthropic's own (#164). The project's
+# committed `.claude/settings.json` is such a file, so declaring it here is what
+# lets a Keel release reach a project with nobody toggling anything.
+KEEL_MARKETPLACE_NAME = "keel-marketplace"
+KEEL_MARKETPLACE_ENTRY = {
+    "source": {"source": "github", "repo": "TanglmChris/keel"},
+    "autoUpdate": True,
+}
+
+
+def load_settings_object(existing: str, purpose: str) -> dict:
+    if not existing.strip():
+        return {}
+    try:
+        settings = json.loads(existing)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"cannot {purpose} .claude/settings.json because it is not valid JSON: {exc}"
+        ) from exc
+    if not isinstance(settings, dict):
+        raise ValueError(
+            f"cannot {purpose} .claude/settings.json because it is not a JSON object"
+        )
+    return settings
+
+
+def merge_claude_marketplace_settings(existing: str) -> tuple[str, str]:
+    """Declare auto-update for the Keel marketplace, keeping the project's say.
+
+    An existing entry keeps its own source — a developer may have added the
+    marketplace from a local directory under this name — and any `autoUpdate`
+    it states, because a project that wrote `false` has decided.
+    """
+    settings = load_settings_object(existing, "declare plugin auto-update in")
+    markets = settings.get("extraKnownMarketplaces", {})
+    if not isinstance(markets, dict):
+        raise ValueError(
+            "cannot declare plugin auto-update because .claude/settings.json "
+            "field 'extraKnownMarketplaces' is not an object"
+        )
+    entry = markets.get(KEEL_MARKETPLACE_NAME)
+    if isinstance(entry, dict):
+        declared = dict(entry)
+        declared.setdefault("autoUpdate", True)
+    else:
+        declared = json.loads(json.dumps(KEEL_MARKETPLACE_ENTRY))
+    merged_settings = dict(settings)
+    merged_settings["extraKnownMarketplaces"] = {**markets, KEEL_MARKETPLACE_NAME: declared}
+    merged = json.dumps(merged_settings, indent=2, ensure_ascii=False) + "\n"
+    before = (
+        json.dumps(settings, indent=2, ensure_ascii=False) + "\n"
+        if existing.strip()
+        else ""
+    )
+    return merged, "skip" if before == merged else "update"
+
+
+def remove_claude_marketplace_settings(existing: str) -> tuple[str | None, str]:
+    """Remove the entry only when it is exactly the one Keel writes."""
+    settings = load_settings_object(existing, "remove plugin auto-update from")
+    markets = settings.get("extraKnownMarketplaces")
+    if not isinstance(markets, dict) or markets.get(KEEL_MARKETPLACE_NAME) != KEEL_MARKETPLACE_ENTRY:
+        return existing, "skip"
+    remaining = {k: v for k, v in markets.items() if k != KEEL_MARKETPLACE_NAME}
+    updated = dict(settings)
+    if remaining:
+        updated["extraKnownMarketplaces"] = remaining
+    else:
+        updated.pop("extraKnownMarketplaces", None)
+    if not updated:
+        return None, "remove"
+    return json.dumps(updated, indent=2, ensure_ascii=False) + "\n", "remove-managed"
+
+
 def load_hook_config(content: str) -> dict:
     try:
         config = json.loads(content)
@@ -1047,6 +1130,15 @@ def plan_action(
     destination = require_inside_repo(repo, action.relative_path)
     source_content = action_source_content(action)
 
+    if action.strategy == "claude-marketplace-settings":
+        existing = destination.read_text(encoding="utf-8") if destination.exists() else ""
+        merged, kind = merge_claude_marketplace_settings(existing)
+        return PlannedAction(
+            "create" if not destination.exists() else kind,
+            action.relative_path,
+            merged if kind != "skip" or not destination.exists() else None,
+        )
+
     if action.strategy == "keel-hook-settings":
         existing = destination.read_text(encoding="utf-8") if destination.exists() else ""
         merged, kind = merge_keel_hook_settings(existing, source_content)
@@ -1113,6 +1205,17 @@ def plan_uninstall_managed(repo: Path, relative_path: str) -> PlannedAction:
     return PlannedAction("remove-managed", Path(relative_path), updated)
 
 
+def plan_uninstall_claude_marketplace_settings(repo: Path) -> PlannedAction:
+    relative = Path(".claude/settings.json")
+    path = require_inside_repo(repo, relative)
+    if not path.is_file():
+        return PlannedAction("skip", relative)
+    updated, kind = remove_claude_marketplace_settings(path.read_text(encoding="utf-8"))
+    if kind == "skip":
+        return PlannedAction("skip", relative)
+    return PlannedAction(kind, relative, updated)
+
+
 def plan_uninstall_template(
     repo: Path,
     relative_path: str,
@@ -1242,6 +1345,10 @@ def plan_uninstall_actions(repo: Path, target: str) -> list[PlannedAction]:
     actions.append(plan_uninstall_managed(repo, "AGENTS.md"))
     if "claude" in targets:
         actions.append(plan_uninstall_managed(repo, "CLAUDE.md"))
+        actions.append(plan_uninstall_claude_marketplace_settings(repo))
+        # Removing the settings file can leave `.claude/` holding nothing that
+        # anyone wrote, and uninstall leaves no empty directory of its own.
+        actions.append(rmdir_if_empty_action(".claude"))
 
     for action in openspec_schema_actions():
         if action.source_path is not None:

package/scripts/validate_plugin.py

@@ -38,8 +38,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.74.0"
-PROTOCOL_VERSION = "5.74.0"
+PACKAGE_VERSION = "5.75.0"
+PROTOCOL_VERSION = "5.75.0"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
 # Mirrors KEEL_PACKAGE_NAME in scripts/install_to_repo.py, one of the two
@@ -16040,6 +16040,188 @@ def installed_elsewhere(config: Path, market_name: str, sentinel: str) -> list |
     return None if any((Path(p) / sentinel).is_file() for p in paths) else paths
 
 
+# Issue #164: project setup declares Claude plugin auto-update. Claude reads a
+# marketplace's auto-update first from `autoUpdate` on its
+# `extraKnownMarketplaces` entry in any settings file, and defaults it off for
+# every marketplace that is not Anthropic's own.
+KEEL_MARKETPLACE_NAME = "keel-marketplace"
+KEEL_MARKETPLACE_ENTRY = {
+    "source": {"source": "github", "repo": "TanglmChris/keel"},
+    "autoUpdate": True,
+}
+AUTO_UPDATE_LABEL = "init-declares-plugin-auto-update"
+
+
+def _settings(repo: Path) -> dict | None:
+    path = repo / ".claude/settings.json"
+    if not path.is_file():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _marketplace_entry(repo: Path) -> dict | None:
+    settings = _settings(repo) or {}
+    return (settings.get("extraKnownMarketplaces") or {}).get(KEEL_MARKETPLACE_NAME)
+
+
+def _auto_update_m1(tmp: Path) -> str | None:
+    repo = tmp / "fresh"
+    repo.mkdir()
+    init = run_keel(repo, "--init", "--target", "claude")
+    if init.returncode != 0:
+        return f"M1 keel --init failed: {(init.stderr or init.stdout).strip()}"
+    entry = _marketplace_entry(repo)
+    if entry != KEEL_MARKETPLACE_ENTRY:
+        return (
+            f"M1 keel --init declared no plugin auto-update: {KEEL_MARKETPLACE_NAME} "
+            f"in .claude/settings.json is {entry!r}, expected "
+            f"{KEEL_MARKETPLACE_ENTRY!r}"
+        )
+    return None
+
+
+def _auto_update_m2(tmp: Path) -> str | None:
+    permissions = {"allow": ["Bash(git:*)"]}
+    local_source = {"source": "directory", "path": "/somewhere/keel"}
+    cases = {
+        "permissions-only": ({"permissions": permissions}, None),
+        "own-source": (
+            {"extraKnownMarketplaces": {KEEL_MARKETPLACE_NAME: {"source": local_source}}},
+            {"source": local_source, "autoUpdate": True},
+        ),
+        "declared-off": (
+            {
+                "extraKnownMarketplaces": {
+                    KEEL_MARKETPLACE_NAME: {**KEEL_MARKETPLACE_ENTRY, "autoUpdate": False}
+                }
+            },
+            {**KEEL_MARKETPLACE_ENTRY, "autoUpdate": False},
+        ),
+    }
+    for name, (existing, expected) in cases.items():
+        repo = tmp / name
+        write_text(repo / ".claude/settings.json", json.dumps(existing, indent=2) + "\n")
+        installed = run_keel(repo, "--install", "--target", "claude")
+        if installed.returncode != 0:
+            return f"M2 {name} keel --install failed: {(installed.stderr or installed.stdout).strip()}"
+        settings = _settings(repo) or {}
+        want = expected if expected is not None else KEEL_MARKETPLACE_ENTRY
+        if _marketplace_entry(repo) != want:
+            return (
+                f"M2 {name}: install did not merge into an existing "
+                f".claude/settings.json as declared; entry is "
+                f"{_marketplace_entry(repo)!r}, expected {want!r}"
+            )
+        if name == "permissions-only" and settings.get("permissions") != permissions:
+            return (
+                f"M2 {name}: the merge into an existing .claude/settings.json "
+                f"lost what the project wrote: {settings!r}"
+            )
+        again = run_keel(repo, "--install", "--target", "claude")
+        if "skip .claude/settings.json" not in (again.stdout or ""):
+            return (
+                f"M2 {name}: a second install did not skip the merge into an "
+                f"existing .claude/settings.json: {again.stdout!r}"
+            )
+    return None
+
+
+def _auto_update_m3(tmp: Path) -> str | None:
+    permissions = {"allow": ["Bash(git:*)"]}
+    ours = tmp / "uninstall-ours"
+    write_text(
+        ours / ".claude/settings.json",
+        json.dumps(
+            {
+                "permissions": permissions,
+                "extraKnownMarketplaces": {KEEL_MARKETPLACE_NAME: KEEL_MARKETPLACE_ENTRY},
+            },
+            indent=2,
+        )
+        + "\n",
+    )
+    run_keel(ours, "--uninstall", "--target", "claude")
+    settings = _settings(ours) or {}
+    if _marketplace_entry(ours) is not None:
+        return f"M3 uninstall left Keel's own marketplace entry behind: {settings!r}"
+    if settings.get("permissions") != permissions:
+        return f"M3 uninstall left the file without the project's permissions: {settings!r}"
+    changed = {**KEEL_MARKETPLACE_ENTRY, "autoUpdate": False}
+    theirs = tmp / "uninstall-theirs"
+    write_text(
+        theirs / ".claude/settings.json",
+        json.dumps({"extraKnownMarketplaces": {KEEL_MARKETPLACE_NAME: changed}}, indent=2)
+        + "\n",
+    )
+    run_keel(theirs, "--uninstall", "--target", "claude")
+    if _marketplace_entry(theirs) != changed:
+        return (
+            "M3 uninstall left the file without the entry the project changed; "
+            f"it removed what Keel did not write: {_settings(theirs)!r}"
+        )
+    return None
+
+
+def _auto_update_m4(tmp: Path) -> str | None:
+    states = {
+        "on": (KEEL_MARKETPLACE_ENTRY, "plugin auto-update: ok"),
+        "off": ({**KEEL_MARKETPLACE_ENTRY, "autoUpdate": False}, "plugin auto-update: manual"),
+        "absent": (None, "plugin auto-update: manual"),
+    }
+    for name, (entry, prefix) in states.items():
+        repo = tmp / f"doctor-{name}"
+        settings = {"extraKnownMarketplaces": {KEEL_MARKETPLACE_NAME: entry}} if entry else {}
+        write_text(repo / ".claude/settings.json", json.dumps(settings) + "\n")
+        doctor = run_keel(repo, "--doctor", "--target", "claude")
+        lines = [
+            line
+            for line in (doctor.stdout or "").splitlines()
+            if line.startswith("plugin auto-update:")
+        ]
+        if len(lines) != 1:
+            return f"M4 {name}: doctor printed no plugin auto-update line: {lines!r}"
+        line = lines[0]
+        if not line.startswith(prefix):
+            return f"M4 {name}: doctor's plugin auto-update line is not {prefix!r}: {line!r}"
+        if name == "off" and "false" not in line:
+            return f"M4 off: the line does not name the project's false: {line!r}"
+        if name == "absent" and "keel --install --target claude" not in line:
+            return f"M4 absent: the line does not name the command that declares it: {line!r}"
+    return None
+
+
+def _auto_update_m5(tmp: Path) -> str | None:
+    repo = tmp / "codex"
+    repo.mkdir()
+    run_keel(repo, "--init", "--target", "codex")
+    if (repo / ".claude/settings.json").exists():
+        return (
+            "M5 keel --init --target codex wrote .claude/settings.json for codex: "
+            f"{_settings(repo)!r}"
+        )
+    return None
+
+
+def validate_init_declares_plugin_auto_update_scenario() -> int:
+    with tempfile.TemporaryDirectory(
+        prefix="keel-auto-update-", ignore_cleanup_errors=True
+    ) as raw:
+        tmp = Path(raw)
+        for check in (
+            _auto_update_m1,
+            _auto_update_m2,
+            _auto_update_m3,
+            _auto_update_m4,
+            _auto_update_m5,
+        ):
+            problem = check(tmp)
+            if problem:
+                report(f"{AUTO_UPDATE_LABEL} {problem}")
+                return 1
+    report(f"{AUTO_UPDATE_LABEL} scenario passed.")
+    return 0
+
+
 def validate_native_plugin_marketplaces_scenario() -> int:
     codex = shutil.which("codex")
     claude = claude_cli()
@@ -30987,6 +31169,7 @@ SCENARIOS: tuple = (
     ("native-plugin-session-start", validate_native_plugin_session_start_scenario),
     ("runtime-version-drift", validate_runtime_version_drift_scenario),
     ("plugin-runs-its-own-cli", validate_plugin_runs_its_own_cli_scenario),
+    ("init-declares-plugin-auto-update", validate_init_declares_plugin_auto_update_scenario),
     ("native-plugin-marketplaces", validate_native_plugin_marketplaces_scenario),
     ("native-plugin-install-matrix", validate_native_plugin_install_matrix_scenario),
     ("native-goal-projection", validate_native_goal_projection_scenario),