fix(#1383): resolve GSD version without a top-level require of the runtime-root package.json (#1409)

* fix(#1383): resolve GSD version without a top-level require of the runtime-root package.json

The extracted runtime-artifact-conversion module sits in the gsd-tools
loader chain and did a module-load `require('../../../package.json')`.
On Codex (whose runtime root has no package.json) that threw
`Cannot find module '../../../package.json'`, crashing every gsd-tools
command before it did anything. Even on Claude the synthetic
`{"type":"commonjs"}` has no `version`, so the sole consumer already
emitted `version: undefined`.

Resolve the version lazily and defensively instead: read the installed
gsd-core/VERSION, else lazily require the runtime-root package.json, else
degrade to '' so the caller omits the field. Both sources are validated
against the repo's semver-prefix convention (mirrors update-context.cts)
so a garbled VERSION is never emitted verbatim. install.js's dead
duplicate converter is intentionally left untouched (scoped to the crash).

Adds a #1383 regression block exercising resolveVersionFrom across
VERSION-only / package.json-only / neither / malformed-VERSION layouts,
asserting no-throw and the correct version string.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(#1383): add changeset for the Codex gsd-tools crash fix

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(#1383): record resolveVersionFrom export in CONTEXT.md glossary

Maintainer review gate on PR #1409: the lazy resolveVersionFrom seam added on
the Runtime Artifact Conversion Module must be recorded in CONTEXT.md so the
canonical glossary doesn't drift from the exported surface.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(#1383): reword changeset to drop product-name parenthetical

product-name-purity (#1777) rejects 'Codex (…)' parentheticals that render
verbatim into CHANGELOG.md. Reword to a comma clause; no behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

tests/hermes-skills-migration.test.cjs

@@ -336,3 +336,61 @@ describe('Hermes Agent: SKILL.md format validation', () => {
     assert.strictEqual(fm.name, 'gsd-plan');
   });
 });
+
+// ─── #1383 regression: version lookup must not require a runtime-root package.json ──
+// The extracted conversion module sits in the gsd-tools loader chain, so its old
+// top-level `require('../../../package.json')` crashed EVERY gsd-tools command on
+// Codex — whose runtime root has no package.json — with
+// `Cannot find module '../../../package.json'`. The Hermes `version:` field (the
+// require's only consumer) must instead be sourced from the installed
+// gsd-core/VERSION, lazily and defensively, so the module loads everywhere and
+// the emitted version is a real semver, never `undefined`.
+describe('#1383 regression: gsd-tools version lookup without a runtime-root package.json', () => {
+  // Require the EXTRACTED module that the gsd-tools chain loads (not install.js's
+  // in-process copy), to assert the crash path itself is gone.
+  const conversion = require('../gsd-core/bin/lib/runtime-artifact-conversion.cjs');
+
+  let tmp;
+  beforeEach(() => { tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-1383-')); });
+  afterEach(() => { cleanup(tmp); });
+
+  // Build a fake install layout <tmp>/gsd-core/bin/lib and return that libDir.
+  // `version` writes <tmp>/gsd-core/VERSION; `rootPkg` writes <tmp>/package.json.
+  function layout({ version, rootPkg } = {}) {
+    const libDir = path.join(tmp, 'gsd-core', 'bin', 'lib');
+    fs.mkdirSync(libDir, { recursive: true });
+    if (version !== undefined) fs.writeFileSync(path.join(tmp, 'gsd-core', 'VERSION'), version);
+    if (rootPkg !== undefined) fs.writeFileSync(path.join(tmp, 'package.json'), JSON.stringify(rootPkg));
+    return libDir;
+  }
+
+  test('reads gsd-core/VERSION when the runtime root has no package.json (Codex layout)', () => {
+    const libDir = layout({ version: '9.9.9\n' }); // deliberately NO root package.json
+    assert.ok(!fs.existsSync(path.join(tmp, 'package.json')),
+      'precondition: Codex layout has no runtime-root package.json');
+    let v;
+    assert.doesNotThrow(() => { v = conversion.resolveVersionFrom(libDir); },
+      'version lookup must not throw on a layout without a runtime-root package.json');
+    assert.strictEqual(v, '9.9.9', 'version is read (trimmed) from the installed VERSION file');
+  });
+
+  test('falls back to the runtime-root package.json when no VERSION file exists (source/npm layout)', () => {
+    const libDir = layout({ rootPkg: { version: '1.2.3' } }); // no VERSION file
+    assert.strictEqual(conversion.resolveVersionFrom(libDir), '1.2.3',
+      'source/npm tree has a real package.json three dirs up');
+  });
+
+  test('degrades to "" (never throws, never emits undefined) when neither source exists', () => {
+    const libDir = layout({}); // neither VERSION nor package.json
+    let v;
+    assert.doesNotThrow(() => { v = conversion.resolveVersionFrom(libDir); });
+    assert.strictEqual(v, '', 'no source -> empty string, so the caller omits the version field');
+  });
+
+  test('rejects a non-semver VERSION file rather than emitting it verbatim', () => {
+    const libDir = layout({ version: 'not-a-version\n' }); // malformed, no package.json fallback
+    let v;
+    assert.doesNotThrow(() => { v = conversion.resolveVersionFrom(libDir); });
+    assert.strictEqual(v, '', 'garbled VERSION is rejected, so the caller omits the field');
+  });
+});