From 2391632973b6de1e6259eb6b1d6e6658c58e0a50 Mon Sep 17 00:00:00 2001
From: Tom Boucher <trekkie@nomorestars.com>
Date: Wed, 1 Jul 2026 11:06:21 -0400
Subject: [PATCH] feat(#1855): add Claude plugin marketplace manifest

Add .claude-plugin/marketplace.json so Claude-plugin-compatible runtimes
(ZCODE et al.) discover gsd-core from a custom marketplace source. The
canonical version lives at plugins[0].version and tracks package.json via
the release version-sync.

Refactor scripts/sync-manifest-versions.cjs so VERSIONED_MANIFESTS entries
are {path, versionKey} dot-path descriptors (default 'version'); register
marketplace.json with versionKey 'plugins.0.version'. getByPath/setByPath
reject __proto__/constructor/prototype (prototype-pollution guard).
plugin.json / gemini-extension.json behavior is unchanged.

- tests/issue-1855-marketplace-manifest.test.cjs: schema + version-sync guard
- tests/issue-844-manifest-version-sync.test.cjs: updated for descriptor shape
- VERSIONING.md + auto-backmerge VERSION_STAMP_MANIFESTS: include marketplace.json
- docs/how-to/install-on-your-runtime.md: marketplace discovery how-to
---
 .claude-plugin/marketplace.json               |  20 ++
 .github/workflows/auto-backmerge.yml          |   2 +-
 VERSIONING.md                                 |   8 +-
 docs/how-to/install-on-your-runtime.md        |   9 +
 scripts/sync-manifest-versions.cjs            |  79 ++++--
 .../issue-1855-marketplace-manifest.test.cjs  | 231 ++++++++++++++++++
 .../issue-844-manifest-version-sync.test.cjs  |  50 ++--
 tests/workflow-maintainer-skip.test.cjs       |  15 +-
 8 files changed, 369 insertions(+), 45 deletions(-)
 create mode 100644 .claude-plugin/marketplace.json
 create mode 100644 tests/issue-1855-marketplace-manifest.test.cjs

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 000000000..43bc4907e
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,20 @@
+{
+  "name": "gsd-core",
+  "description": "Marketplace for GSD Core — meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
+  "owner": {
+    "name": "open-gsd",
+    "url": "https://github.com/open-gsd"
+  },
+  "plugins": [
+    {
+      "name": "gsd-core",
+      "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
+      "version": "1.7.0-rc.1",
+      "source": "./",
+      "author": {
+        "name": "open-gsd",
+        "url": "https://github.com/open-gsd"
+      }
+    }
+  ]
+}
diff --git a/.github/workflows/auto-backmerge.yml b/.github/workflows/auto-backmerge.yml
index 3548234c5..d9cb9be9e 100644
--- a/.github/workflows/auto-backmerge.yml
+++ b/.github/workflows/auto-backmerge.yml
@@ -115,7 +115,7 @@ jobs:
           # filter those out. A substantive change still parks: it leaves
           # non-"version" lines (deps in package.json; resolved/integrity in the
           # lockfile when a dependency actually changes).
-          VERSION_STAMP_MANIFESTS='package.json package-lock.json .claude-plugin/plugin.json gemini-extension.json'
+          VERSION_STAMP_MANIFESTS='package.json package-lock.json .claude-plugin/plugin.json .claude-plugin/marketplace.json gemini-extension.json'
           DROPPED=$(printf '%s\n' "$DROPPED" | while IFS= read -r f; do
             [ -n "$f" ] || continue
             case " $VERSION_STAMP_MANIFESTS " in
diff --git a/VERSIONING.md b/VERSIONING.md
index 7c3a53493..1ba485a44 100644
--- a/VERSIONING.md
+++ b/VERSIONING.md
@@ -131,13 +131,17 @@ match `package.json`:
 
 - `.claude-plugin/plugin.json` — Claude Code plugin manifest (issue #766)
 - `gemini-extension.json` — Gemini CLI extension manifest (issue #775)
+- `.claude-plugin/marketplace.json` — Claude plugin marketplace manifest; its
+  version lives at `plugins[0].version` and is stamped via a nested versionKey
+  descriptor (issue #1855)
 
 The `version` npm lifecycle script (`scripts/sync-manifest-versions.cjs --stage`)
 stamps these files automatically on every `npm version` call, and stages them so
 they are included in the release commit alongside `package.json`.
 
-To add a new manifest that must track the package version, register its path in
-the `VERSIONED_MANIFESTS` array in `scripts/sync-manifest-versions.cjs`. A
+To add a new manifest that must track the package version, register its path
+(and, if its version field is not top-level, its dotted `versionKey`) in the
+`VERSIONED_MANIFESTS` array in `scripts/sync-manifest-versions.cjs`. A
 regression test (`tests/issue-844-manifest-version-sync.test.cjs`) enforces this:
 it scans all committed JSON files for a matching `version` field and fails if any
 are missing from the registry.
diff --git a/docs/how-to/install-on-your-runtime.md b/docs/how-to/install-on-your-runtime.md
index daed18174..bd11f0756 100644
--- a/docs/how-to/install-on-your-runtime.md
+++ b/docs/how-to/install-on-your-runtime.md
@@ -102,6 +102,15 @@ The `gsd-tools` binary (installed as part of the `@opengsd/gsd-core` npm package
 
 Node.js (`node`) must also be available on your `PATH`. The plugin's always-on guard hooks (wired in `hooks/hooks.json`) are invoked as `node "${CLAUDE_PLUGIN_ROOT}/hooks/<script>"`. Some Claude Code distributions ship as a standalone binary and do not expose a `node` executable on `PATH`; in those environments the plugin's hooks will not run. Verify with `node --version` before relying on the plugin hooks.
 
+#### Claude plugin marketplace discovery (ZCODE and compatible runtimes)
+
+GSD Core also ships a `.claude-plugin/marketplace.json` marketplace manifest (sibling to `plugin.json`). Runtimes that implement the Claude plugin marketplace contract — such as ZCODE — can discover and install GSD Core from a custom marketplace source without a manual clone:
+
+1. In your runtime's plugin UI, add a custom marketplace source pointing at `open-gsd/gsd-core` (GitHub `owner/repo` form).
+2. GSD Core appears in the catalog and can be installed directly from the UI.
+
+This path is **additive** and changes nothing about the Claude Code plugin install above (`.claude-plugin/plugin.json` is unchanged). The marketplace entry's `source` is `./`, so it reuses `plugin.json`'s `commands` / `skills` / `hooks` mapping. The catalog version tracks `package.json` (it lives at `plugins[0].version` and is stamped by the release version-sync), so the version you see in the marketplace matches the npm release.
+
 ---
 
 ### Gemini CLI
diff --git a/scripts/sync-manifest-versions.cjs b/scripts/sync-manifest-versions.cjs
index 81dc17ed0..023c58f8b 100644
--- a/scripts/sync-manifest-versions.cjs
+++ b/scripts/sync-manifest-versions.cjs
@@ -21,18 +21,65 @@ const { execFileSync } = require('child_process');
 
 const ROOT = path.resolve(__dirname, '..');
 
-// Single source of truth: runtime-integration manifests whose top-level `version`
-// MUST track package.json. Add a new manifest here so `npm version` keeps it in
-// sync — the regression guard test (issue 844) fails if you forget.
+// Single source of truth: runtime-integration manifests whose `version` field
+// MUST track package.json. Each entry names the manifest path plus the dotted
+// path to the version field inside that JSON document. Top-level `version` is
+// the default (plugin.json, gemini-extension.json); the Claude plugin
+// marketplace manifest carries its canonical version at plugins[0].version
+// (the schema-canonical location runtimes read — issue #1855).
+//
+// Add a new manifest here so `npm version` keeps it in sync — the regression
+// guard test (issue 844) fails if you forget.
 const VERSIONED_MANIFESTS = [
-  '.claude-plugin/plugin.json',
-  'gemini-extension.json',
+  { path: '.claude-plugin/plugin.json', versionKey: 'version' },
+  { path: 'gemini-extension.json', versionKey: 'version' },
+  { path: '.claude-plugin/marketplace.json', versionKey: 'plugins.0.version' },
 ];
 
+// Convenience: just the registered paths, for consumers that only need to
+// iterate files (e.g. the issue-844 regression-guard ALLOWED set).
+const VERSIONED_MANIFEST_PATHS = VERSIONED_MANIFESTS.map((e) => e.path);
+
 function readJson(p) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
 
+// Property names that must never be traversed/assigned through a dotted path —
+// the prototype-pollution triple. Mirrors the _isSafePropKey CodeQL barrier used
+// elsewhere in the repo. Versions are hand-authored descriptors, but the helpers
+// are exported, so guard them before reuse across a trust boundary.
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function assertSafePath(dotPath) {
+  for (const seg of String(dotPath).split('.')) {
+    if (UNSAFE_KEYS.has(seg)) {
+      throw new Error(`refusing to traverse reserved property "${seg}" in version path "${dotPath}"`);
+    }
+  }
+}
+
+// Read a dotted path ('plugins.0.version') from a parsed JSON document.
+// Returns undefined if any intermediate is missing. Array indices are plain
+// numeric keys, so 'plugins.0.version' resolves obj.plugins[0].version.
+// Reserved properties (__proto__/constructor/prototype) are rejected.
+function getByPath(obj, dotPath) {
+  assertSafePath(dotPath);
+  return String(dotPath).split('.').reduce((cur, key) => (cur == null ? cur : cur[key]), obj);
+}
+
+// Write a value at a dotted path. Intermediate nodes must already exist (every
+// registered manifest is hand-authored with its version slot present, so this
+// never needs to materialize a path). Reserved properties are rejected. Kept
+// trivial — no eval, no creation.
+function setByPath(obj, dotPath, value) {
+  assertSafePath(dotPath);
+  const parts = String(dotPath).split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
 function getPackageVersion(root) {
   const r = root || ROOT;
   return readJson(path.join(r, 'package.json')).version;
@@ -44,13 +91,13 @@ function syncManifestVersions(opts) {
   const root = (opts && opts.root) || ROOT;
   const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
   const changed = [];
-  for (const rel of VERSIONED_MANIFESTS) {
-    const abs = path.join(root, rel);
+  for (const entry of VERSIONED_MANIFESTS) {
+    const abs = path.join(root, entry.path);
     const manifest = readJson(abs);
-    if (manifest.version !== v) {
-      manifest.version = v;
+    if (getByPath(manifest, entry.versionKey) !== v) {
+      setByPath(manifest, entry.versionKey, v);
       fs.writeFileSync(abs, JSON.stringify(manifest, null, 2) + '\n');
-      changed.push(rel);
+      changed.push(entry.path);
     }
   }
   return changed;
@@ -61,9 +108,10 @@ function findDrift(opts) {
   const root = (opts && opts.root) || ROOT;
   const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
   const drift = [];
-  for (const rel of VERSIONED_MANIFESTS) {
-    const found = readJson(path.join(root, rel)).version;
-    if (found !== v) drift.push({ manifest: rel, found, expected: v });
+  for (const entry of VERSIONED_MANIFESTS) {
+    const manifest = readJson(path.join(root, entry.path));
+    const found = getByPath(manifest, entry.versionKey);
+    if (found !== v) drift.push({ manifest: entry.path, found, expected: v });
   }
   return drift;
 }
@@ -143,7 +191,7 @@ function stageManifests(opts) {
     console.warn('sync-manifest-versions: not a git work tree; skipping staging.');
     return;
   }
-  const toStage = [...VERSIONED_MANIFESTS, ...listCapabilityManifests({ root })];
+  const toStage = [...VERSIONED_MANIFEST_PATHS, ...listCapabilityManifests({ root })];
   try {
     execFileSync('git', ['add', '--', ...toStage], { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
   } catch (err) {
@@ -154,6 +202,9 @@ function stageManifests(opts) {
 
 module.exports = {
   VERSIONED_MANIFESTS,
+  VERSIONED_MANIFEST_PATHS,
+  getByPath,
+  setByPath,
   syncManifestVersions,
   findDrift,
   getPackageVersion,
diff --git a/tests/issue-1855-marketplace-manifest.test.cjs b/tests/issue-1855-marketplace-manifest.test.cjs
new file mode 100644
index 000000000..545a3bc2f
--- /dev/null
+++ b/tests/issue-1855-marketplace-manifest.test.cjs
@@ -0,0 +1,231 @@
+'use strict';
+
+/**
+ * Regression tests for issue #1855: Claude plugin marketplace manifest.
+ *
+ * Asserts structural and semantic correctness of:
+ *   .claude-plugin/marketplace.json  — Claude plugin marketplace manifest
+ *
+ * This manifest lets Claude-plugin-compatible runtimes (ZCODE et al.) discover
+ * and install gsd-core from a custom marketplace source. It is the
+ * marketplace-discovery sibling of .claude-plugin/plugin.json (issue #766),
+ * which remains the Claude Code single-plugin manifest and is unchanged.
+ *
+ * The version that runtimes read lives at plugins[0].version (the canonical
+ * marketplace schema location), and is kept in sync with package.json by
+ * scripts/sync-manifest-versions.cjs via a nested versionKey descriptor.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const pkg = require(path.join(ROOT, 'package.json'));
+const pluginJson = require(path.join(ROOT, '.claude-plugin', 'plugin.json'));
+const {
+  VERSIONED_MANIFESTS,
+  VERSIONED_MANIFEST_PATHS,
+  getByPath,
+  setByPath,
+  syncManifestVersions,
+} = require(path.join(ROOT, 'scripts', 'sync-manifest-versions.cjs'));
+const helpers = require(path.join(__dirname, 'helpers.cjs'));
+
+const MARKETPLACE_JSON_PATH = path.join(ROOT, '.claude-plugin', 'marketplace.json');
+const MARKETPLACE_REL = '.claude-plugin/marketplace.json';
+
+// ─── Section A: marketplace.json structure ───────────────────────────────────
+describe('A: .claude-plugin/marketplace.json', () => {
+
+  let manifest;
+
+  test('exists and is valid JSON', () => {
+    assert.ok(fs.existsSync(MARKETPLACE_JSON_PATH), '.claude-plugin/marketplace.json must exist');
+    const raw = fs.readFileSync(MARKETPLACE_JSON_PATH, 'utf-8');
+    manifest = JSON.parse(raw); // throws on invalid JSON
+    assert.ok(typeof manifest === 'object' && manifest !== null, 'manifest must be a JSON object');
+  });
+
+  test('top-level name is a non-empty string', (t) => {
+    if (!manifest) { t.skip('manifest could not be parsed'); return; }
+    assert.ok(typeof manifest.name === 'string' && manifest.name.trim().length > 0, 'marketplace name must be a non-empty string');
+  });
+
+  test('top-level description is a non-empty string', (t) => {
+    if (!manifest) { t.skip('manifest could not be parsed'); return; }
+    assert.ok(typeof manifest.description === 'string' && manifest.description.trim().length > 0, 'marketplace description must be a non-empty string');
+  });
+
+  test('owner.{name,url} are non-empty strings', (t) => {
+    if (!manifest) { t.skip('manifest could not be parsed'); return; }
+    assert.ok(manifest.owner && typeof manifest.owner.name === 'string' && manifest.owner.name.trim().length > 0, 'owner.name must be a non-empty string');
+    assert.ok(typeof manifest.owner.url === 'string' && /^https?:\/\//.test(manifest.owner.url), 'owner.url must be an http(s) URL');
+  });
+
+  test('plugins[] is a non-empty array', (t) => {
+    if (!manifest) { t.skip('manifest could not be parsed'); return; }
+    assert.ok(Array.isArray(manifest.plugins) && manifest.plugins.length > 0, 'plugins must be a non-empty array');
+  });
+
+  test('plugins[0] has the gsd-core entry with source "./"', (t) => {
+    if (!manifest) { t.skip('manifest could not be parsed'); return; }
+    const entry = manifest.plugins[0];
+    assert.ok(entry && typeof entry === 'object', 'plugins[0] must be an object');
+    assert.equal(entry.name, pluginJson.name, `plugins[0].name (${entry && entry.name}) must equal plugin.json name (${pluginJson.name})`);
+    assert.equal(entry.source, './', 'plugins[0].source must be "./" (repo root, same as plugin.json relative refs)');
+    assert.ok(typeof entry.description === 'string' && entry.description.trim().length > 0, 'plugins[0].description must be a non-empty string');
+  });
+
+  test('plugins[0].author.{name,url} match plugin.json author / owner', (t) => {
+    if (!manifest) { t.skip('manifest could not be parsed'); return; }
+    const entry = manifest.plugins[0];
+    assert.ok(entry.author && typeof entry.author.name === 'string' && entry.author.name.trim().length > 0, 'plugins[0].author.name must be a non-empty string');
+    assert.equal(entry.author.name, pluginJson.author && pluginJson.author.name, 'plugins[0].author.name must match plugin.json author.name');
+  });
+
+  test('plugins[0].version matches package.json version (synced)', (t) => {
+    if (!manifest) { t.skip('manifest could not be parsed'); return; }
+    const entry = manifest.plugins[0];
+    assert.equal(
+      entry.version,
+      pkg.version,
+      `plugins[0].version (${entry.version}) must match package.json version (${pkg.version}). ` +
+      'Run `node scripts/sync-manifest-versions.cjs` to fix — the marketplace plugin version is stamped via a nested versionKey descriptor. (#1855)'
+    );
+  });
+
+  test('no plugins[0].$schema key (intentionally omitted, parity with plugin.json)', (t) => {
+    if (!manifest) { t.skip('manifest could not be parsed'); return; }
+    const entry = manifest.plugins[0];
+    assert.ok(!Object.prototype.hasOwnProperty.call(entry, '$schema'), 'plugins[0] must NOT contain a $schema key');
+  });
+});
+
+// ─── Section B: registration in the version-sync registry ────────────────────
+describe('B: marketplace.json is registered for version sync', () => {
+
+  test('marketplace.json path appears in VERSIONED_MANIFESTS', () => {
+    const paths = VERSIONED_MANIFESTS.map((e) => (typeof e === 'string' ? e : e && e.path));
+    assert.ok(
+      paths.includes(MARKETPLACE_REL),
+      `VERSIONED_MANIFESTS must register ${MARKETPLACE_REL} so 'npm version' keeps plugins[0].version in sync (issue #844 / #1855). Got: ${JSON.stringify(paths)}`
+    );
+  });
+
+  test('marketplace.json entry uses the nested plugins.0.version key', () => {
+    const entry = VERSIONED_MANIFESTS.find((e) => (typeof e === 'string' ? e : e && e.path) === MARKETPLACE_REL);
+    // Nested dot-path is what makes the canonical marketplace version (plugins[0].version) the stamped field.
+    const versionKey = typeof entry === 'string' ? 'version' : entry && entry.versionKey;
+    assert.equal(
+      versionKey,
+      'plugins.0.version',
+      `${MARKETPLACE_REL} must be registered with versionKey 'plugins.0.version' (the schema-canonical location runtimes read). Got: ${JSON.stringify(entry)}`
+    );
+  });
+
+  test('marketplace.json is in the staging list (stageManifests derives from VERSIONED_MANIFEST_PATHS)', () => {
+    // stageManifests() git-adds [...VERSIONED_MANIFEST_PATHS, ...capabilities]. If
+    // marketplace.json were dropped from the paths list, `npm version` would stage
+    // every other manifest but silently skip it — so pin the path here too.
+    assert.ok(
+      VERSIONED_MANIFEST_PATHS.includes(MARKETPLACE_REL),
+      `VERSIONED_MANIFEST_PATHS must include ${MARKETPLACE_REL} so stageManifests() stages it on npm version. Got: ${JSON.stringify(VERSIONED_MANIFEST_PATHS)}`
+    );
+  });
+});
+
+// ─── Section D: nested-path helpers are prototype-pollution-safe ──────────────
+describe('D: getByPath / setByPath reject reserved properties', () => {
+
+  test('plugins.0.version resolves a nested array-index path', () => {
+    const doc = { plugins: [{ version: '1.2.3' }] };
+    assert.equal(getByPath(doc, 'plugins.0.version'), '1.2.3');
+  });
+
+  test('getByPath returns undefined for a missing intermediate', () => {
+    assert.equal(getByPath({ plugins: [] }, 'plugins.0.version'), undefined);
+  });
+
+  for (const reserved of ['__proto__', 'constructor', 'prototype']) {
+    test(`getByPath refuses to traverse "${reserved}"`, () => {
+      assert.throws(
+        () => getByPath({}, `${reserved}.x`),
+        /refusing to traverse reserved property/,
+        `getByPath must reject the reserved "${reserved}" segment`
+      );
+    });
+    test(`setByPath refuses to assign through "${reserved}" (no prototype pollution)`, () => {
+      const target = {};
+      assert.throws(
+        () => setByPath(target, `${reserved}.polluted`, 'yes'),
+        /refusing to traverse reserved property/,
+        `setByPath must reject the reserved "${reserved}" segment`
+      );
+      // Confirm nothing leaked onto Object.prototype.
+      assert.ok(({}).polluted === undefined, 'Object.prototype must not be polluted');
+    });
+  }
+});
+
+// ─── Section C: sync stamps the nested version (temp fixture, red→green) ─────
+describe('C: syncManifestVersions stamps plugins[0].version (temp fixture)', () => {
+
+  test('stamps a stale marketplace plugins[0].version to the package version, then is idempotent', () => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-1855-'));
+    try {
+      fs.writeFileSync(
+        path.join(tmpRoot, 'package.json'),
+        JSON.stringify({ name: 'x', version: '9.9.9-test.0' }, null, 2) + '\n'
+      );
+      // Seed a stale marketplace.json with a nested plugins[0].version.
+      const destAbs = path.join(tmpRoot, MARKETPLACE_REL);
+      fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+      const stale = JSON.parse(fs.readFileSync(MARKETPLACE_JSON_PATH, 'utf8'));
+      stale.plugins[0].version = '0.0.0';
+      fs.writeFileSync(destAbs, JSON.stringify(stale, null, 2) + '\n');
+
+      // Only sync the marketplace manifest in this fixture (other registered
+      // manifests are absent under tmpRoot). syncManifestVersions tolerates a
+      // missing manifest file by... it does NOT — it readJson-throws. So seed
+      // the other registered manifests too (stale) so the sync loop is happy.
+      for (const e of VERSIONED_MANIFESTS) {
+        const rel = typeof e === 'string' ? e : e.path;
+        if (rel === MARKETPLACE_REL) continue;
+        const realAbs = path.join(ROOT, rel);
+        if (!fs.existsSync(realAbs)) continue;
+        const other = JSON.parse(fs.readFileSync(realAbs, 'utf8'));
+        const vk = typeof e === 'string' ? 'version' : (e.versionKey || 'version');
+        setNested(other, vk, '0.0.0');
+        const d = path.join(tmpRoot, rel);
+        fs.mkdirSync(path.dirname(d), { recursive: true });
+        fs.writeFileSync(d, JSON.stringify(other, null, 2) + '\n');
+      }
+
+      const changed = syncManifestVersions({ root: tmpRoot });
+      assert.ok(changed.includes(MARKETPLACE_REL), `sync should report ${MARKETPLACE_REL} as changed`);
+
+      const synced = JSON.parse(fs.readFileSync(destAbs, 'utf8'));
+      assert.equal(synced.plugins[0].version, '9.9.9-test.0', 'plugins[0].version should be stamped to the package version');
+
+      // Idempotent second run does not re-report the marketplace manifest.
+      const changed2 = syncManifestVersions({ root: tmpRoot });
+      assert.ok(!changed2.includes(MARKETPLACE_REL), 'second sync should not re-report an already-synced marketplace manifest');
+    } finally {
+      helpers.cleanup(tmpRoot);
+    }
+  });
+});
+
+// Minimal nested dot-path setter mirroring the sync script's helper, for fixture seeding.
+function setNested(obj, dotPath, value) {
+  const parts = String(dotPath).split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i];
+    cur = cur[k];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
diff --git a/tests/issue-844-manifest-version-sync.test.cjs b/tests/issue-844-manifest-version-sync.test.cjs
index 0288dfa0f..60cbcc8d1 100644
--- a/tests/issue-844-manifest-version-sync.test.cjs
+++ b/tests/issue-844-manifest-version-sync.test.cjs
@@ -24,6 +24,9 @@ const ROOT = path.resolve(__dirname, '..');
 const helpers = require(path.join(__dirname, 'helpers.cjs'));
 const {
   VERSIONED_MANIFESTS,
+  VERSIONED_MANIFEST_PATHS,
+  getByPath,
+  setByPath,
   syncManifestVersions,
   getPackageVersion,
   stageManifests,
@@ -51,12 +54,12 @@ describe('A: syncManifestVersions — temp fixture', () => {
 
     // Copy real manifests into tmp, stamped at OLD version so tests can
     // verify the pre-sync (stale) state and post-sync (updated) state.
-    for (const rel of VERSIONED_MANIFESTS) {
-      const realAbs = path.join(ROOT, rel);
+    for (const entry of VERSIONED_MANIFESTS) {
+      const realAbs = path.join(ROOT, entry.path);
       const manifest = JSON.parse(fs.readFileSync(realAbs, 'utf8'));
-      manifest.version = '0.0.0';
+      setByPath(manifest, entry.versionKey, '0.0.0');
 
-      const destAbs = path.join(tmpRoot, rel);
+      const destAbs = path.join(tmpRoot, entry.path);
       const destDir = path.dirname(destAbs);
       if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
       fs.writeFileSync(destAbs, JSON.stringify(manifest, null, 2) + '\n');
@@ -89,13 +92,13 @@ describe('A: syncManifestVersions — temp fixture', () => {
     const pkgVersion = getPackageVersion(tmpRoot);
     assert.equal(pkgVersion, '9.9.9-test.0');
 
-    for (const rel of VERSIONED_MANIFESTS) {
-      const abs = path.join(tmpRoot, rel);
+    for (const entry of VERSIONED_MANIFESTS) {
+      const abs = path.join(tmpRoot, entry.path);
       const m = JSON.parse(fs.readFileSync(abs, 'utf8'));
       assert.equal(
-        m.version,
+        getByPath(m, entry.versionKey),
         '9.9.9-test.0',
-        `${rel} version should be 9.9.9-test.0 after sync`
+        `${entry.path} version (${entry.versionKey}) should be 9.9.9-test.0 after sync`
       );
     }
   });
@@ -109,10 +112,10 @@ describe('A: syncManifestVersions — temp fixture', () => {
         path.join(sub, 'package.json'),
         JSON.stringify({ name: 'x', version: '9.9.9-test.0' }, null, 2) + '\n'
       );
-      for (const rel of VERSIONED_MANIFESTS) {
-        const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8'));
-        manifest.version = '0.0.0';
-        const destAbs = path.join(sub, rel);
+      for (const entry of VERSIONED_MANIFESTS) {
+        const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, entry.path), 'utf8'));
+        setByPath(manifest, entry.versionKey, '0.0.0');
+        const destAbs = path.join(sub, entry.path);
         const destDir = path.dirname(destAbs);
         if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
         fs.writeFileSync(destAbs, JSON.stringify(manifest, null, 2) + '\n');
@@ -125,12 +128,15 @@ describe('A: syncManifestVersions — temp fixture', () => {
   });
 
   test('non-version fields are preserved after sync', () => {
-    for (const rel of VERSIONED_MANIFESTS) {
+    for (const entry of VERSIONED_MANIFESTS) {
+      const rel = entry.path;
       const real = JSON.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8'));
       const tmp = JSON.parse(fs.readFileSync(path.join(tmpRoot, rel), 'utf8'));
-      // Check that every non-version key from the real manifest exists in tmp
+      // Check that every non-version key from the real manifest exists in tmp.
+      // For nested versionKey manifests (e.g. marketplace plugins[0].version),
+      // the comparison is structural at the top level only — the version slot
+      // itself is the one field sync is allowed to change.
       for (const key of Object.keys(real)) {
-        if (key === 'version') continue;
         assert.ok(
           Object.prototype.hasOwnProperty.call(tmp, key),
           `${rel}: field "${key}" should be preserved after sync`
@@ -140,7 +146,8 @@ describe('A: syncManifestVersions — temp fixture', () => {
   });
 
   test('each synced file ends with a single trailing newline', () => {
-    for (const rel of VERSIONED_MANIFESTS) {
+    for (const entry of VERSIONED_MANIFESTS) {
+      const rel = entry.path;
       const raw = fs.readFileSync(path.join(tmpRoot, rel), 'utf8');
       assert.ok(raw.endsWith('\n'), `${rel} must end with a trailing newline`);
       assert.ok(!raw.endsWith('\n\n'), `${rel} must not end with a double newline`);
@@ -159,15 +166,16 @@ describe('B: real manifests match package.json version', () => {
 
   const pkgVersion = getPackageVersion(ROOT);
 
-  for (const rel of VERSIONED_MANIFESTS) {
-    test(`${rel} version === ${pkgVersion}`, () => {
+  for (const entry of VERSIONED_MANIFESTS) {
+    const rel = entry.path;
+    test(`${rel} version (${entry.versionKey}) === ${pkgVersion}`, () => {
       const abs = path.join(ROOT, rel);
       assert.ok(fs.existsSync(abs), `${rel} must exist at ${abs}`);
       const m = JSON.parse(fs.readFileSync(abs, 'utf8'));
       assert.equal(
-        m.version,
+        getByPath(m, entry.versionKey),
         pkgVersion,
-        `${rel} version (${m.version}) must match package.json version (${pkgVersion}). ` +
+        `${rel} version (${entry.versionKey} = ${getByPath(m, entry.versionKey)}) must match package.json version (${pkgVersion}). ` +
         'Run `node scripts/sync-manifest-versions.cjs` to fix.'
       );
     });
@@ -254,7 +262,7 @@ describe('C: regression guard — version-bearing JSON files must be registered'
   // version-swept by syncCapabilityVersions (ADR-1244 D6) — discovered by glob,
   // so every one is "registered" without an explicit entry here.
   const ALLOWED = new Set([
-    ...VERSIONED_MANIFESTS,
+    ...VERSIONED_MANIFEST_PATHS,
     ...listCapabilityManifests({ root: ROOT }),
     'package.json',
     'package-lock.json',
diff --git a/tests/workflow-maintainer-skip.test.cjs b/tests/workflow-maintainer-skip.test.cjs
index 7f87a1bb3..acf094230 100644
--- a/tests/workflow-maintainer-skip.test.cjs
+++ b/tests/workflow-maintainer-skip.test.cjs
@@ -107,14 +107,15 @@ describe('Require Issue Link back-merge automation carve-out', () => {
 describe('Auto-backmerge needs_review version-manifest carve-out (#1404)', () => {
   const workflow = readWorkflow('.github/workflows/auto-backmerge.yml');
 
-  test('all four version manifests are filtered via version-only detection', () => {
-    // package.json / package-lock.json / plugin.json / gemini-extension.json
-    // diverge every release; a drop that is ONLY "version" lines must not park
-    // (parking is what lets the back-merge go stale). A substantive change still
-    // parks. (#1404)
+  test('all version-bearing manifests are filtered via version-only detection', () => {
+    // package.json / package-lock.json / plugin.json / marketplace.json /
+    // gemini-extension.json diverge every release; a drop that is ONLY
+    // "version" lines must not park (parking is what lets the back-merge go
+    // stale). A substantive change still parks. The grep matches the indented
+    // "version": line for marketplace.json's plugins[0].version too. (#1404 / #1855)
     assert.ok(
-      workflow.includes("VERSION_STAMP_MANIFESTS='package.json package-lock.json .claude-plugin/plugin.json gemini-extension.json'"),
-      'auto-backmerge.yml must version-only-filter all four version manifests'
+      workflow.includes("VERSION_STAMP_MANIFESTS='package.json package-lock.json .claude-plugin/plugin.json .claude-plugin/marketplace.json gemini-extension.json'"),
+      'auto-backmerge.yml must version-only-filter all version-bearing manifests (incl. marketplace.json #1855)'
     );
     assert.ok(
       workflow.includes(`grep -vE '^[+-][[:space:]]*"version":'`),