@christang/keel 5.78.0 → 5.80.0

package/README.md

@@ -46,9 +46,10 @@ Node.js `>=20.19.0` (the bundled OpenSpec CLI needs it).
 
 ## Install
 
-**Claude Code** — the plugin is the whole install. It is the published `@christang/keel`
-package, so it carries the `keel` CLI and the bundled OpenSpec along with the skills and hooks,
-and the agent's `keel` commands run the copy the plugin brought:
+**Claude Code** — the plugin is the whole install. It is this repository at the release's tag,
+the same tree npm publishes as `@christang/keel`, so it carries the `keel` CLI along with the
+skills and hooks, and Claude installs the pinned OpenSpec from its lockfile when it installs the
+plugin. The agent's `keel` commands run the copy the plugin brought:
 
 ```bash
 claude plugin marketplace add TanglmChris/keel
@@ -62,6 +63,10 @@ in the background after a session's first message; `/reload-plugins` applies it
 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.
 
+Each release's notes also carry the entry Anthropic's official plugin directory would list for it,
+pinned to the commit the release tag points at. The directory takes the same tagged tree this
+marketplace installs.
+
 **Codex, and your own terminal** — install the CLI as well (it also installs the bundled
 OpenSpec CLI):
 

package/README.zh-CN.md

@@ -38,8 +38,9 @@ Node.js `>=20.19.0`（内置的 OpenSpec CLI 需要）。
 
 ## 安装
 
-**Claude Code** —— 装插件就够了。插件本身就是发布的 `@christang/keel` 包，技能和 hook 之外还带着
-`keel` CLI 和捆绑的 OpenSpec；agent 运行的 `keel` 就是插件带来的这一份：
+**Claude Code** —— 装插件就够了。插件就是本仓库在发布 tag 上的那棵树，和 npm 发布的 `@christang/keel`
+是同一份，技能和 hook 之外还带着 `keel` CLI；安装插件时 Claude 会按锁文件装好锁定版本的 OpenSpec。
+agent 运行的 `keel` 就是插件带来的这一份：
 
 ```bash
 claude plugin marketplace add TanglmChris/keel
@@ -51,6 +52,9 @@ claude plugin install keel@keel-marketplace
 新版本会在会话发出第一条消息后在后台下载；执行 `/reload-plugins` 即在当前会话生效，否则下次启动时生效。
 不想自动更新，就把那一项的 `autoUpdate` 设为 `false`；项目写明的值 Keel 会保留，`keel --doctor` 会报告当前声明的是哪一个。
 
+每个版本的 release notes 里还附有 Anthropic 官方插件目录对应的条目，锁定到该版本 tag 指向的 commit。
+官方目录装到的就是这个 marketplace 装的同一棵带 tag 的树。
+
 **Codex，以及你自己的终端** —— 另外装一份 CLI（同时装上捆绑的 OpenSpec CLI）：
 
 ```bash

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.78.0 -->
+<!-- keel:start version=5.80.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

@@ -2,7 +2,7 @@
 "use strict";
 
 // The bare `keel` a Claude plugin's `bin/` puts on the agent's PATH (#164).
-// On Claude the plugin is this published package, and the host adds `bin/`
+// On Claude the plugin is this repository's tagged tree, and the host adds `bin/`
 // to PATH by file name, so `keel.js` alone would answer to `keel.js`. npm's
 // own `bin` map keeps pointing at `keel.js`; this file only gives the plugin
 // the same name.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@christang/keel",
-  "version": "5.78.0",
+  "version": "5.80.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@christang/keel",
-      "version": "5.78.0",
+      "version": "5.80.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.78.0",
+  "version": "5.80.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.78.0",
+  "version": "5.80.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.78.0",
+  "version": "5.80.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/scripts/session-start.js

@@ -137,6 +137,44 @@ function pluginManifest() {
   return { version: null, remedy: HOST_UPDATE };
 }
 
+// On Claude the plugin is the repository's tagged tree, cached at
+// <plugins>/cache/<marketplace>/<plugin>/<version>, and the host records what
+// it installed in <plugins>/installed_plugins.json (#172). Another install of
+// this same plugin at a different version means the update already happened
+// and this session has not reloaded it. Located from this file's own path, like
+// the manifest; anything unexpected is no pending install, which leaves the
+// report exactly as it was.
+function pendingInstall(loaded) {
+  try {
+    const root = fs.realpathSync(path.resolve(__dirname, "..", "..", ".."));
+    const record = path.join(root, "..", "..", "..", "..", "installed_plugins.json");
+    const plugins = JSON.parse(fs.readFileSync(record, "utf8")).plugins;
+    const versions = new Set();
+    for (const entries of Object.values(plugins || {})) {
+      for (const entry of Array.isArray(entries) ? entries : []) {
+        if (!entry || typeof entry.installPath !== "string") continue;
+        // Compared through the real path: node loads this file through its
+        // symlinks resolved, while the host records whatever path it chose.
+        const installPath = path.resolve(entry.installPath);
+        let parent;
+        try {
+          parent = fs.realpathSync(path.dirname(installPath));
+        } catch {
+          continue;
+        }
+        if (parent !== path.dirname(root)) continue;
+        if (path.join(parent, path.basename(installPath)) === root) continue;
+        if (typeof entry.version === "string") versions.add(entry.version.trim());
+      }
+    }
+    if (versions.size !== 1) return null;
+    const [version] = versions;
+    return version && version !== loaded ? version : null;
+  } catch {
+    return null;
+  }
+}
+
 // The repository states which protocol it runs in the managed block the
 // installer wrote. AGENTS.md is the canonical carrier; CLAUDE.md is read second
 // because a repository may carry only the target-native file.
@@ -193,16 +231,25 @@ function versionReport(cwd, cli, pathCli = null) {
   // The host puts the user's PATH ahead of plugin `bin/` directories, so a
   // global install is what the agent's own `keel` commands run even though
   // this hook ran the plugin's. Both remedies are named; neither is run.
-  const shadow = pathCli && pathCli !== cli
+  const pending = pendingInstall(plugin.version);
+  // With an installed update pending, the PATH copy is judged against what
+  // the reload will load: one that matches it shadows nothing afterwards, and
+  // aligning with the loaded plugin would be a downgrade (#172).
+  const target = pending || cli;
+  const shadow = pathCli && pathCli !== target
     ? ` The \`keel\` on PATH (${pathCli}) shadows this plugin's CLI for the `
       + "agent's commands, because the host puts your PATH first: remove it "
       + "with `npm rm -g @christang/keel`, since the plugin carries its own, "
-      + `or align it with \`npm i -g @christang/keel@${cli}\`.`
+      + `or align it with \`npm i -g @christang/keel@${target}\`.`
     : "";
+  // An update the host already installed needs only the reload (#172), so
+  // naming the update command there sends the reader to what already happened.
+  const remedy = pending
+    ? `The host has already installed plugin ${pending}, so nothing needs updating.`
+    : `Updating is ${plugin.remedy}, which Keel names and does not run.`;
   return `runtime versions disagree: ${named}${missing}. A session's hooks are `
     + "fixed when it loads the plugin, so an updated plugin applies after "
-    + "`/reload-plugins` or at the next session start. Updating is "
-    + `${plugin.remedy}, which Keel names and does not run.${shadow}`;
+    + `\`/reload-plugins\` or at the next session start. ${remedy}${shadow}`;
 }
 
 // The `keel` a bare command resolves, asked only when this hook ran its own
@@ -268,7 +315,7 @@ function panel(lines) {
   ].join("\n");
 }
 
-// On Claude the plugin is the published package (#164), so the CLI it shipped
+// On Claude the plugin is the repository's tagged tree (#164), so the CLI it shipped
 // with sits three levels above this script. It is recognized by the package's
 // name and not by the path alone: a Codex cache holds only `plugins/keel`, and
 // whatever lies above that is not this plugin's to run.

package/scripts/bump_version.js

@@ -4,8 +4,8 @@
 // One-shot version bump across every place Keel pins its version.
 //
 // The Keel validation suite requires the same version in package.json,
-// npm-shrinkwrap.json, both native plugin manifests, the Claude marketplace
-// entry and the package release it pins, the validator constants, the
+// npm-shrinkwrap.json, the native plugin manifests, the Claude marketplace
+// entry and the release tag it installs, the validator constants, the
 // protocol docs, and the changelog. This script updates all of them together
 // so a release never ships half-aligned.
 //
@@ -62,19 +62,31 @@ function bumpPackageFiles(newVersion) {
   process.stdout.write("  updated npm-shrinkwrap.json\n");
 }
 
-// On Claude the plugin is the published package (#164): the marketplace entry
-// is its manifest, labeled with the release and pinned to that same release of
-// `@christang/keel`. Both numbers move, or a refresh installs the old package.
+// On Claude the plugin is the tagged repository tree. Its root manifest carries
+// the release version, and Keel's marketplace entry names that version and the
+// tag it installs from git. All three move, or a refresh installs the old tree.
 function bumpClaudeMarketplace(newVersion) {
+  const manifestRel = ".claude-plugin/plugin.json";
+  const manifestPath = path.join(ROOT, manifestRel);
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  manifest.version = newVersion;
+  writeJson(manifestPath, manifest);
+  process.stdout.write(`  updated ${manifestRel}\n`);
+
   const relPath = ".claude-plugin/marketplace.json";
   const filePath = path.join(ROOT, relPath);
   const market = JSON.parse(fs.readFileSync(filePath, "utf8"));
   const entry = (market.plugins || []).find((plugin) => plugin.name === "keel");
-  if (!entry || !entry.source || typeof entry.source !== "object") {
-    fail(`expected an npm-sourced keel entry in ${relPath}`);
+  if (
+    !entry
+    || !entry.source
+    || typeof entry.source !== "object"
+    || entry.source.source !== "url"
+  ) {
+    fail(`expected a git-sourced keel entry in ${relPath}`);
   }
   entry.version = newVersion;
-  entry.source.version = newVersion;
+  entry.source.ref = `v${newVersion}`;
   writeJson(filePath, market);
   process.stdout.write(`  updated ${relPath}\n`);
 }

package/scripts/official_entry.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+"use strict";
+
+// The entry Anthropic's official plugin directory would list for a release.
+//
+// The directory pins every third-party plugin to a commit of its git
+// repository, so the entry is only useful pinned to the commit the release
+// tag points at. The release job appends this output to the release notes;
+// submitting it, or asking the directory to move its pin, is the owner's act.
+// This script reads the root manifest and nothing else, and runs nothing.
+//
+// Usage:
+//   node scripts/official_entry.js <X.Y.Z> <40-character commit sha>
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+const REPOSITORY = "https://github.com/TanglmChris/keel";
+
+const [version, sha] = process.argv.slice(2);
+// A pin the directory could not use prints nothing, so a pipe into the notes
+// cannot carry a half-formed entry.
+if (!/^\d+\.\d+\.\d+$/.test(version || "") || !/^[0-9a-f]{40}$/.test(sha || "")) {
+  process.stderr.write(
+    "official-entry: usage: node scripts/official_entry.js <X.Y.Z> <40-hex commit sha>\n"
+  );
+  process.exit(1);
+}
+const manifest = JSON.parse(
+  fs.readFileSync(path.join(ROOT, ".claude-plugin", "plugin.json"), "utf8")
+);
+const entry = {
+  name: manifest.name,
+  description: manifest.description,
+  category: "development",
+  source: { source: "url", url: `${REPOSITORY}.git`, sha },
+  homepage: REPOSITORY,
+};
+process.stdout.write(`${JSON.stringify(entry, null, 2)}\n`);

package/scripts/validate_plugin.py

@@ -38,8 +38,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.78.0"
-PROTOCOL_VERSION = "5.78.0"
+PACKAGE_VERSION = "5.80.0"
+PROTOCOL_VERSION = "5.80.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
@@ -2371,9 +2371,10 @@ def validate_version_alignment_scenario() -> int:
             )
             return 1
 
-    # M5 — on Claude the marketplace entry is the manifest and names the
-    # package release it installs (#164), so both of its numbers are version
-    # markers, and the script that moves every marker has to move them.
+    # M5 — on Claude the plugin is the tagged repository: the root manifest
+    # carries the version, and the marketplace entry names it and the tag it
+    # installs, so all three are version markers, and the script that moves
+    # every marker has to move them.
     def claude_entry_versions(root: Path) -> dict:
         market = json.loads(
             (root / ".claude-plugin/marketplace.json").read_text(encoding="utf-8")
@@ -2382,11 +2383,23 @@ def validate_version_alignment_scenario() -> int:
             (e for e in market.get("plugins", []) if e.get("name") == "keel"), {}
         )
         source = entry.get("source") if isinstance(entry.get("source"), dict) else {}
-        return {"version": entry.get("version"), "source.version": source.get("version")}
+        ref = source.get("ref")
+        return {
+            "version": entry.get("version"),
+            "source.ref": ref[1:] if isinstance(ref, str) and ref.startswith("v") else ref,
+        }
+
+    def root_manifest_version(root: Path) -> str | None:
+        manifest = root / ".claude-plugin/plugin.json"
+        if not manifest.is_file():
+            return None
+        return json.loads(manifest.read_text(encoding="utf-8")).get("version")
 
     stale = {
         k: v for k, v in claude_entry_versions(ROOT).items() if v != PACKAGE_VERSION
     }
+    if root_manifest_version(ROOT) != PACKAGE_VERSION:
+        stale["root plugin manifest"] = root_manifest_version(ROOT)
     if stale:
         report(
             "version-alignment scenario claude marketplace entry version "
@@ -2399,6 +2412,7 @@ def validate_version_alignment_scenario() -> int:
             "package.json",
             "npm-shrinkwrap.json",
             ".claude-plugin/marketplace.json",
+            ".claude-plugin/plugin.json",
             "plugins/keel/.claude-plugin/plugin.json",
             "plugins/keel/.codex-plugin/plugin.json",
             "scripts/bump_version.js",
@@ -2421,6 +2435,12 @@ def validate_version_alignment_scenario() -> int:
             report("version-alignment scenario: bump_version.js failed in a scratch copy.")
             report((bumped.stderr or bumped.stdout).strip())
             return 1
+        if root_manifest_version(scratch) != "99.0.0":
+            report(
+                "version-alignment scenario root plugin manifest was not moved "
+                f"by bump_version.js: {root_manifest_version(scratch)!r}"
+            )
+            return 1
         left = {
             k: v
             for k, v in claude_entry_versions(scratch).items()
@@ -14834,51 +14854,53 @@ def validate_native_plugin_manifests_scenario() -> int:
         ),
         None,
     )
-    # M1 — on Claude the plugin is the published package (#164): the entry
-    # fetches it from npm, pinned to the release it is labeled with, and acts
-    # as the manifest. An unpinned source would let a refresh between merge
-    # and publish cache the previous package under the new label.
-    source = (claude_entry or {}).get("source")
-    if (
-        not isinstance(source, dict)
-        or source.get("source") != "npm"
-        or source.get("package") != "@christang/keel"
-    ):
+    # M1 — on Claude the plugin is the tagged repository tree, and the manifest
+    # at its root is the one Claude manifest, so a directory entry nobody here
+    # controls only has to say where the repository is.
+    root_manifest_path = ROOT / ".claude-plugin/plugin.json"
+    if not root_manifest_path.is_file():
         report(
-            "native-plugin-manifests claude marketplace entry is not the "
-            f"published package: source {source!r}"
+            "native-plugin-manifests has no root plugin manifest at "
+            ".claude-plugin/plugin.json, so a git-sourced entry has nothing to "
+            "read the skills, agent, and hooks from."
         )
         return 1
-    pinned = {
-        "version": claude_entry.get("version"),
-        "source.version": source.get("version"),
-    }
-    unpinned = {k: v for k, v in pinned.items() if v != package_version}
-    if unpinned:
+    root_manifest = json.loads(root_manifest_path.read_text(encoding="utf-8"))
+    plugin_manifest = json.loads(
+        (ROOT / PLUGIN_ROOT / ".claude-plugin/plugin.json").read_text(
+            encoding="utf-8"
+        )
+    )
+    differing = [
+        key
+        for key in ("name", "version", "description")
+        if root_manifest.get(key) != plugin_manifest.get(key)
+        or root_manifest.get(key) in (None, "")
+    ]
+    if differing or root_manifest.get("version") != package_version:
         report(
-            "native-plugin-manifests claude marketplace entry is not the "
-            f"published package at {package_version}: {unpinned!r}"
+            "native-plugin-manifests root plugin manifest disagrees with "
+            f"{PLUGIN_ROOT}/.claude-plugin/plugin.json or the package version "
+            f"{package_version} on {differing or ['version']!r}"
         )
         return 1
     declared_paths = [
-        *claude_entry.get("skills", []),
-        *claude_entry.get("agents", []),
+        *root_manifest.get("skills", []),
+        *root_manifest.get("agents", []),
     ]
     unresolved = [
         path for path in declared_paths if not (ROOT / path).exists()
     ]
     if not declared_paths or unresolved:
         report(
-            "native-plugin-manifests claude marketplace entry is not the "
-            "published package's manifest: its skills and agents must resolve "
-            f"inside the package; declared {declared_paths!r}, unresolved "
-            f"{unresolved!r}"
+            "native-plugin-manifests root plugin manifest's skills and agents "
+            f"must resolve inside the repository; declared {declared_paths!r}, "
+            f"unresolved {unresolved!r}"
         )
         return 1
-
-    # M2 — the entry states the hooks a second time, so it is held to the
-    # file Codex discovers: the same events, matchers, scripts, and timeouts,
-    # with each script path resolved from the package root instead.
+    # The manifest states the hooks a second time, so it is held to the file
+    # Codex discovers: the same events, matchers, scripts, and timeouts, with
+    # each script path resolved from the repository root instead.
     plugin_hooks = json.loads(
         (ROOT / PLUGIN_ROOT / "hooks/hooks.json").read_text(encoding="utf-8")
     )["hooks"]
@@ -14888,11 +14910,37 @@ def validate_native_plugin_manifests_scenario() -> int:
             "${CLAUDE_PLUGIN_ROOT}/plugins/keel/scripts/",
         )
     )
-    if claude_entry.get("hooks") != expected_hooks:
+    if root_manifest.get("hooks") != expected_hooks:
         report(
-            "native-plugin-manifests claude marketplace entry hooks diverge "
+            "native-plugin-manifests root plugin manifest hooks diverge "
             f"from {PLUGIN_ROOT}/hooks/hooks.json after resolving script paths "
-            f"from the package root: {claude_entry.get('hooks')!r}"
+            f"from the repository root: {root_manifest.get('hooks')!r}"
+        )
+        return 1
+
+    # M2 — Keel's own entry installs the same tagged tree the official
+    # directory would, from git. It pins the tag rather than a commit because
+    # the file is part of the commit it would have to name, and it restates no
+    # component, so the root manifest stays the only place they are declared.
+    source = (claude_entry or {}).get("source")
+    want_source = {
+        "source": "url",
+        "url": KEEL_REPOSITORY_GIT_URL,
+        "ref": f"v{package_version}",
+    }
+    restated = [
+        key for key in ("skills", "agents", "hooks") if key in (claude_entry or {})
+    ]
+    if (
+        source != want_source
+        or (claude_entry or {}).get("version") != package_version
+        or restated
+    ):
+        report(
+            "native-plugin-manifests claude marketplace entry is not the "
+            f"tagged repository at v{package_version}: source {source!r}, "
+            f"version {(claude_entry or {}).get('version')!r}, restated "
+            f"components {restated!r}"
         )
         return 1
 
@@ -15450,6 +15498,9 @@ def validate_native_plugin_session_start_scenario() -> int:
 # one independently: the plugin's by planting a manifest beside a copy of the
 # shipping hook, the CLI's by what the fake CLI prints, and the repository's by
 # the managed block in its AGENTS.md.
+# Where the Claude plugin is fetched from, by Keel's marketplace and by the
+# official directory entry each release states.
+KEEL_REPOSITORY_GIT_URL = "https://github.com/TanglmChris/keel.git"
 VERSION_DRIFT_STATEMENT = "runtime versions disagree"
 # How an update applies: the hooks are fixed when the plugin loads, and the
 # host's `/reload-plugins` reloads it in the running session (#164). A restart
@@ -15867,7 +15918,7 @@ def plant_path_keel(directory: Path, cli_script: Path) -> Path:
 
 
 def validate_plugin_runs_its_own_cli_scenario() -> int:
-    """Issue #164: on Claude the plugin is the published package.
+    """Issue #164: on Claude the plugin carries the whole package.
 
     The hook, running from inside that package, must run the CLI the package
     ships rather than whatever `keel` is on PATH, and must report a PATH copy
@@ -16002,44 +16053,289 @@ def validate_plugin_runs_its_own_cli_scenario() -> int:
     return 0
 
 
+def validate_drift_names_a_pending_reload_scenario() -> int:
+    """Issue #172: an update the host already installed needs only a reload.
+
+    The session keeps the hooks it loaded, and `/clear` does not reload them, so
+    a plugin the host has already updated keeps reporting drift until the
+    reader reloads. Naming the host's update command there sends them to an
+    action that already happened, and aligning the PATH copy with the loaded
+    plugin is a downgrade.
+    """
+    label = "drift-names-a-pending-reload"
+    event = {"hook_event_name": "SessionStart", "source": "clear"}
+    with tempfile.TemporaryDirectory(
+        prefix="keel-pending-reload-", ignore_cleanup_errors=True
+    ) as raw_tmp:
+        tmp = Path(raw_tmp)
+        repo = tmp / "repo"
+        write_text(repo / "openspec/changes/demo/tasks.md", task_contract_fixture())
+        write_text(
+            repo / "AGENTS.md",
+            "# Keel v5.81.0 Agent Protocol\n\n"
+            "<!-- keel:start version=5.81.0 -->\n## Session Start\n"
+            "<!-- keel:end -->\n",
+        )
+        # The host's layout: <plugins>/cache/<marketplace>/<plugin>/<version>,
+        # with its install record in <plugins>. The loaded copy is 5.80.0.
+        plugins_dir = tmp / "plugins"
+        package = plugins_dir / "cache/mkt/keel/5.80.0"
+        write_text(
+            package / "package.json",
+            json.dumps({"name": "@christang/keel", "version": "5.80.0"}) + "\n",
+        )
+        fake_keel_cli(package / "bin/keel.js", "5.80.0")
+        plugin = plant_session_start_plugin(package / "plugins/keel", "5.80.0")
+        record = plugins_dir / "installed_plugins.json"
+
+        def write_record(entries: dict) -> None:
+            write_text(record, json.dumps({"version": 2, "plugins": entries}) + "\n")
+
+        installed = str(plugins_dir / "cache/mkt/keel/5.81.0")
+        write_record(
+            {
+                "keel@mkt": [
+                    {"scope": "user", "installPath": installed, "version": "5.81.0"}
+                ]
+            }
+        )
+        path_cli = Path(fake_keel_cli(tmp / "path-cli.js", "5.81.0").split('"')[1])
+        path_dir = plant_path_keel(tmp / "path", path_cli)
+        env = {"PATH": str(path_dir) + os.pathsep + os.environ.get("PATH", "")}
+
+        def channels() -> dict[str, str]:
+            run = run_session_start_hook(
+                repo, event, keel_cli=None, plugin_root=plugin, extra_env=env
+            )
+            return {
+                "additionalContext": session_start_context(run) or "",
+                "systemMessage": session_start_message(run) or "",
+            }
+
+        pending = channels()
+        for channel, text in pending.items():
+            lowered = text.lower()
+            # M1 — the update is named as installed, and the reload as the remedy.
+            if "claude plugin update" in lowered:
+                report(
+                    f"{label} M1 {channel} named claude plugin update for an "
+                    f"update the host already installed: {text!r}"
+                )
+                return 1
+            if "already installed plugin 5.81.0" not in lowered:
+                report(
+                    f"{label} M1 {channel} does not say the host already "
+                    f"installed plugin 5.81.0: {text!r}"
+                )
+                return 1
+            if "/reload-plugins" not in lowered:
+                report(f"{label} M1 {channel} does not name /reload-plugins: {text!r}")
+                return 1
+            # M2 — a PATH copy at the installed version is not a shadow.
+            if "shadows" in lowered or "@christang/keel@5.80.0" in lowered:
+                report(
+                    f"{label} M2 {channel} called a PATH keel at the installed "
+                    f"version a shadow: {text!r}"
+                )
+                return 1
+
+        # M3 — another plugin's install is not this one's, and no record at
+        # all is the same as a record that names nothing of ours. Its directory
+        # exists, as the host's would, so the entry is excluded by being
+        # another plugin's and not by being unreadable.
+        (plugins_dir / "cache/mkt/other/9.9.9").mkdir(parents=True)
+        write_record(
+            {
+                "other@mkt": [
+                    {
+                        "scope": "user",
+                        "installPath": str(plugins_dir / "cache/mkt/other/9.9.9"),
+                        "version": "9.9.9",
+                    }
+                ]
+            }
+        )
+        unrelated = channels()
+        for channel, text in unrelated.items():
+            lowered = text.lower()
+            if "already installed" in lowered:
+                report(
+                    f"{label} M3 {channel} read another plugin's install as "
+                    f"this one's: {text!r}"
+                )
+                return 1
+            if "claude plugin update" not in lowered:
+                report(
+                    f"{label} M3 {channel} dropped the update command with no "
+                    f"install of this plugin recorded: {text!r}"
+                )
+                return 1
+        record.unlink()
+        absent = channels()
+        if absent != unrelated:
+            report(
+                f"{label} M3 a missing install record changed the report:\n"
+                f"  no record:      {absent!r}\n  other plugin:   {unrelated!r}"
+            )
+            return 1
+    report(f"{label} scenario passed.")
+    return 0
+
+
+def validate_official_directory_entry_scenario() -> int:
+    """Each release states the entry Anthropic's official directory would list.
+
+    The directory pins third-party plugins to a commit of a git repository, so
+    the entry is only useful pinned to the commit the release tag points at.
+    Keel prints it and submits nothing.
+    """
+    label = "official-directory-entry"
+    script = ROOT / "scripts/official_entry.js"
+    sha = "0123456789abcdef0123456789abcdef01234567"
+
+    def run(*args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["node", str(script), *args],
+            cwd=ROOT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            capture_output=True,
+            check=False,
+        )
+
+    # M1 — the entry, pinned to the given commit.
+    printed = run("5.80.0", sha)
+    try:
+        entry = json.loads(printed.stdout) if printed.returncode == 0 else None
+    except ValueError:
+        entry = None
+    if not isinstance(entry, dict):
+        report(
+            f"{label} M1 printed no official directory entry: exit "
+            f"{printed.returncode}, {(printed.stderr or printed.stdout).strip()!r}"
+        )
+        return 1
+    manifest = json.loads(
+        (ROOT / ".claude-plugin/plugin.json").read_text(encoding="utf-8")
+    )
+    want = {
+        "name": "keel",
+        "description": manifest.get("description"),
+        "category": "development",
+        "source": {"source": "url", "url": KEEL_REPOSITORY_GIT_URL, "sha": sha},
+        "homepage": "https://github.com/TanglmChris/keel",
+    }
+    if entry != want:
+        report(
+            f"{label} M1 printed an entry that is not the release's: "
+            f"{entry!r}, expected {want!r}"
+        )
+        return 1
+
+    # M2 — a pin the directory could not use is refused, and prints nothing a
+    # careless pipe could paste.
+    for args in (("5.80", sha), ("5.80.0", sha[:-1])):
+        refused = run(*args)
+        if refused.returncode == 0 or refused.stdout.strip():
+            report(
+                f"{label} M2 accepted a malformed pin {args!r}: exit "
+                f"{refused.returncode}, stdout {refused.stdout!r}"
+            )
+            return 1
+
+    # M3 — the release job appends the entry for the tag's commit to the notes
+    # before it creates the release.
+    workflow = (ROOT / ".github/workflows/publish.yml").read_text(encoding="utf-8")
+    step = workflow[workflow.find("name: Tag and release the landed version"):]
+    create = step.find("gh release create")
+    append = step.find('node scripts/official_entry.js "$VERSION" "$SHA"')
+    if append < 0:
+        report(
+            f"{label} M3 release notes do not carry the official directory "
+            "entry: the release step never runs `node scripts/official_entry.js "
+            '"$VERSION" "$SHA"`.'
+        )
+        return 1
+    if create < 0:
+        report(f"{label} M3 the release step no longer runs `gh release create`.")
+        return 1
+    if create < append:
+        report(
+            f"{label} M3 the release step creates the release before it "
+            "writes the official directory entry, so the notes miss it."
+        )
+        return 1
+    if ">> notes.md" not in step[append:create]:
+        report(
+            f"{label} M3 the release step runs official_entry.js but does not "
+            "append its output to notes.md."
+        )
+        return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
 def stage_claude_market_under_test(tmp: Path) -> tuple[Path, str, str] | str:
-    """A Claude marketplace that installs this tree rather than the registry.
-
-    The committed entry installs the published package at this release, which
-    does not exist on the registry until the release lands (#164), and at a
-    version that does exist it installs the registry's copy and tests nothing
-    here. So an install smoke packs the tree the way npm publishes it and puts
-    it behind a copy of the committed entry whose source points at it and whose
-    manifest fields are unchanged. A sentinel only the packed tree carries lets
-    the caller prove which copy was installed. Returns the marketplace
-    directory, its name, and the sentinel, or a failure message.
+    """A Claude marketplace that installs this tree rather than GitHub's.
+
+    The committed entry installs the Keel repository at this release's tag,
+    which does not exist until the release lands, and at a tag that does exist
+    it installs GitHub's copy and tests nothing here. So an install smoke
+    stages the working tree — tracked and untracked-but-not-ignored files, as
+    they are on disk — as a scratch git repository tagged the same way, and
+    puts it behind a copy of the committed entry whose URL points at it and
+    whose other fields are unchanged. The host then fetches it through git and
+    installs its dependencies exactly as it would from GitHub. A sentinel only
+    the staged tree carries lets the caller prove which copy was installed.
+    Returns the marketplace directory, its name, and the sentinel, or a failure
+    message.
     """
-    npm = shutil.which("npm")
-    if npm is None:
-        return "needs npm to pack the package under test."
-    packed = subprocess.run(
-        [npm, "pack", "--json", "--pack-destination", str(tmp)],
+    git = shutil.which("git")
+    if git is None:
+        return "needs git to stage the tree under test."
+    listed = subprocess.run(
+        [git, "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
         cwd=ROOT,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
         capture_output=True,
         check=False,
     )
-    if packed.returncode != 0:
-        return "npm pack failed: " + (packed.stderr or packed.stdout).strip()
-    tarball = tmp / json.loads(packed.stdout)[0]["filename"]
-    market = tmp / "claude-market"
-    market.mkdir()
-    subprocess.run(["tar", "-xzf", str(tarball), "-C", str(market)], check=True)
+    if listed.returncode != 0:
+        return "git ls-files failed: " + listed.stderr.decode("utf-8", "replace")
+    staged = tmp / "keel-under-test"
+    for relative in filter(None, listed.stdout.decode("utf-8").split("\0")):
+        source = ROOT / relative
+        if not source.is_file():
+            continue
+        target = staged / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, target)
     sentinel = ".keel-package-under-test"
-    write_text(market / "package" / sentinel, "\n")
+    write_text(staged / sentinel, "\n")
     committed = json.loads(
         (ROOT / ".claude-plugin/marketplace.json").read_text(encoding="utf-8")
     )
-    for entry in committed.get("plugins", []):
-        if entry.get("name") == "keel":
-            entry["source"] = "./package"
+    entry = next(
+        (e for e in committed.get("plugins", []) if e.get("name") == "keel"), None
+    )
+    source_field = (entry or {}).get("source")
+    if not isinstance(source_field, dict) or not source_field.get("ref"):
+        return f"the committed Claude entry pins no git ref: {source_field!r}"
+    identity = ["-c", "user.name=keel", "-c", "user.email=keel@invalid"]
+    for args in (
+        ["init", "-q"],
+        ["add", "-A"],
+        [*identity, "commit", "-q", "-m", "tree under test"],
+        ["tag", source_field["ref"]],
+    ):
+        done = subprocess.run(
+            [git, *args], cwd=staged, capture_output=True, text=True, check=False
+        )
+        if done.returncode != 0:
+            return f"git {args[-1]} failed staging the tree: {done.stderr.strip()}"
+    source_field["url"] = staged.resolve().as_uri()
+    market = tmp / "claude-market"
     write_text(
         market / ".claude-plugin/marketplace.json",
         json.dumps(committed, indent=2) + "\n",
@@ -16047,6 +16343,16 @@ def stage_claude_market_under_test(tmp: Path) -> tuple[Path, str, str] | str:
     return market, committed["name"], sentinel
 
 
+def shrinkwrap_openspec_version() -> str | None:
+    """The OpenSpec version the committed lockfile pins."""
+    lock = json.loads((ROOT / "npm-shrinkwrap.json").read_text(encoding="utf-8"))
+    return (
+        lock.get("packages", {})
+        .get("node_modules/@fission-ai/openspec", {})
+        .get("version")
+    )
+
+
 def installed_elsewhere(config: Path, market_name: str, sentinel: str) -> list | None:
     """None when Keel was installed from the package under test, else the paths."""
     installed = json.loads(
@@ -16566,7 +16872,69 @@ def validate_native_plugin_marketplaces_scenario() -> int:
             report(
                 "native-plugin-marketplaces claude plugin install failed to use "
                 f"the package under test; it installed from {elsewhere!r}, "
-                "which does not carry the sentinel the packed tree does."
+                "which does not carry the sentinel the staged tree does."
+            )
+            return 1
+        # M4 — the git install is a working plugin: the host loaded the
+        # skills and both hooks from the root manifest, and installed the
+        # OpenSpec the lockfile pins, since nothing in the tree carries it.
+        details = run_claude("plugin", "details", f"keel@{claude_market_name}")
+        details_text = details.stdout or ""
+        missing = [
+            needle
+            for needle in (
+                "keel-align-expectations",
+                "keel-review-checklist",
+                "SessionStart",
+                "PreToolUse",
+            )
+            if needle not in details_text
+        ]
+        if details.returncode != 0:
+            report(
+                "native-plugin-marketplaces claude plugin details failed for "
+                f"the git-installed plugin: {(details.stderr or details_text).strip()!r}"
+            )
+            return 1
+        if missing:
+            report(
+                "native-plugin-marketplaces the git-installed plugin lacks "
+                f"{missing!r} in claude plugin details: {details_text!r}"
+            )
+            return 1
+        installed = json.loads(
+            (claude_config / "plugins/installed_plugins.json").read_text(
+                encoding="utf-8"
+            )
+        )
+        install_path = Path(
+            installed["plugins"][f"keel@{claude_market_name}"][0]["installPath"]
+        )
+        openspec_bin = install_path / "node_modules/.bin/openspec"
+        if not openspec_bin.exists():
+            report(
+                "native-plugin-marketplaces the git-installed plugin has no "
+                f"installed OpenSpec at {openspec_bin}; the host did not "
+                "install the tree's dependencies."
+            )
+            return 1
+        probe = subprocess.run(
+            [str(openspec_bin), "--version"],
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        pinned = shrinkwrap_openspec_version()
+        if probe.returncode != 0:
+            report(
+                "native-plugin-marketplaces the git-installed OpenSpec failed "
+                f"to run: {(probe.stderr or probe.stdout).strip()!r}"
+            )
+            return 1
+        if pinned not in probe.stdout:
+            report(
+                "native-plugin-marketplaces the git-installed plugin does not "
+                f"carry the pinned OpenSpec {pinned}: {probe.stdout.strip()!r}"
             )
             return 1
         claude_list = run_claude("plugin", "list")
@@ -31446,6 +31814,8 @@ 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),
+    ("drift-names-a-pending-reload", validate_drift_names_a_pending_reload_scenario),
+    ("official-directory-entry", validate_official_directory_entry_scenario),
     ("init-declares-plugin-auto-update", validate_init_declares_plugin_auto_update_scenario),
     ("context-names-the-protocol-refresh", validate_context_names_the_protocol_refresh_scenario),
     ("init-never-downgrades-openspec", validate_init_never_downgrades_openspec_scenario),