feat(#1430): versioned capability manifest + native stamping (ADR-1244 Phase 1) (#1436)

* feat(#1430): versioned capability manifest + native stamping (ADR-1244 Phase 1)

Make the capability manifest versioned — the data substrate the Capability
Ecosystem (ADR-1244) keys off:

- capability.json gains a REQUIRED semver `version` plus the optional
  ecosystem envelope (`engines.gsd`, `compatVersions`, `integrity`,
  `provenance`); the build-time conformance validator enforces them via a new
  `validateVersionEnvelope()` (exported for the Phase 2 runtime overlay).
- All 32 native capabilities stamped with `version` (= package version,
  lockstep) + `engines.gsd`; `sync-manifest-versions.cjs` gains a glob sweep
  that keeps them in sync, and the issue-844 regression guard is extended.
- Strict SemVer 2.0.0 grammar blocks metacharacter/space/unicode smuggling in
  version strings; range/integrity fields are shape-validated (satisfaction
  and the load-time gate are deferred to Phase 2/4).
- Capability rel-paths emitted forward-slash for cross-platform git correctness.

Closes #1430

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(#1430): add changeset for versioned capability manifest

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

scripts/sync-manifest-versions.cjs

@@ -68,6 +68,66 @@ function findDrift(opts) {
   return drift;
 }
 
+// ─── ADR-1244 D6: native capability manifests ────────────────────────────────
+//
+// Native capabilities (capabilities/<id>/capability.json) carry a `version`
+// stamped in lockstep with the package version at release. Unlike
+// VERSIONED_MANIFESTS (fixed paths), capabilities are discovered by glob so a
+// new capability is auto-covered without editing this file. The version-sync
+// regression guard (issue #844) treats every swept capability manifest as
+// registered.
+
+// Discover capabilities/<id>/capability.json under `root`, sorted for stable
+// staging order. Returns [] when there is no capabilities/ directory.
+function listCapabilityManifests(opts) {
+  const root = (opts && opts.root) || ROOT;
+  const dir = path.join(root, 'capabilities');
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    // Forward-slash rel paths (NOT path.join) so they match `git ls-files`
+    // output, git pathspecs, and the forward-slash VERSIONED_MANIFESTS on every
+    // platform — path.join would emit backslashes on Windows and break the
+    // issue-844 regression guard's ALLOWED-set comparison.
+    .map((e) => 'capabilities/' + e.name + '/capability.json')
+    .filter((rel) => fs.existsSync(path.join(root, rel)))
+    .sort();
+}
+
+// Stamp `version` into each native capability manifest. Returns changed rel paths.
+function syncCapabilityVersions(opts) {
+  const root = (opts && opts.root) || ROOT;
+  const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
+  const changed = [];
+  for (const rel of listCapabilityManifests({ root })) {
+    const abs = path.join(root, rel);
+    const manifest = readJson(abs);
+    if (manifest.version !== v) {
+      manifest.version = v;
+      fs.writeFileSync(abs, JSON.stringify(manifest, null, 2) + '\n');
+      changed.push(rel);
+    }
+  }
+  return changed;
+}
+
+// Native capability manifests whose version != package version.
+function findCapabilityDrift(opts) {
+  const root = (opts && opts.root) || ROOT;
+  const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
+  const drift = [];
+  for (const rel of listCapabilityManifests({ root })) {
+    const found = readJson(path.join(root, rel)).version;
+    if (found !== v) drift.push({ manifest: rel, found, expected: v });
+  }
+  return drift;
+}
+
 // Best-effort outside git; fail-closed inside a work tree so a release never
 // ships a stale manifest that the working-tree test already accepted.
 function stageManifests(opts) {
@@ -83,21 +143,32 @@ function stageManifests(opts) {
     console.warn('sync-manifest-versions: not a git work tree; skipping staging.');
     return;
   }
+  const toStage = [...VERSIONED_MANIFESTS, ...listCapabilityManifests({ root })];
   try {
-    execFileSync('git', ['add', '--', ...VERSIONED_MANIFESTS], { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
+    execFileSync('git', ['add', '--', ...toStage], { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
   } catch (err) {
     const detail = err && err.stderr ? err.stderr.toString().trim() : (err && err.message) || 'unknown error';
     throw new Error(`sync-manifest-versions: failed to git-add manifests inside a work tree: ${detail}`);
   }
 }
 
-module.exports = { VERSIONED_MANIFESTS, syncManifestVersions, findDrift, getPackageVersion, stageManifests };
+module.exports = {
+  VERSIONED_MANIFESTS,
+  syncManifestVersions,
+  findDrift,
+  getPackageVersion,
+  stageManifests,
+  // ADR-1244 D6: native capability version sweep
+  listCapabilityManifests,
+  syncCapabilityVersions,
+  findCapabilityDrift,
+};
 
 if (require.main === module) {
   const args = process.argv.slice(2);
   const version = getPackageVersion();
   if (args.includes('--check')) {
-    const drift = findDrift({ version });
+    const drift = [...findDrift({ version }), ...findCapabilityDrift({ version })];
     if (drift.length) {
       for (const d of drift) {
         console.error('Manifest ' + d.manifest + ' version ' + d.found + ' != package.json ' + d.expected);
@@ -105,10 +176,11 @@ if (require.main === module) {
       console.error('Run `node scripts/sync-manifest-versions.cjs` to fix.');
       process.exitCode = 1;
     } else {
-      console.log('All ' + VERSIONED_MANIFESTS.length + ' versioned manifests in sync at ' + version + '.');
+      const total = VERSIONED_MANIFESTS.length + listCapabilityManifests().length;
+      console.log('All ' + total + ' versioned manifests in sync at ' + version + '.');
     }
   } else {
-    const changed = syncManifestVersions({ version });
+    const changed = [...syncManifestVersions({ version }), ...syncCapabilityVersions({ version })];
     if (changed.length) {
       console.log('Stamped ' + version + ' into: ' + changed.join(', '));
     } else {