fix(spec): regenerate the ADR-0087 manifest + upgrade guide the RC bump left stale

The v17 RC version bump moved PROTOCOL_VERSION to 17.0.0 without re-running
gen:spec-changes / gen:upgrade-guide, so spec-changes.json still declared
protocolVersion 16.0.0 with no protocol-17 entries while the protocol-17
conversions were already registered and live. check:spec-changes (Check
Generated Artifacts) fails on pristine origin/main — reproduced in a detached
worktree — and surfaced here only because this PR is the first since the bump
to touch a path the job's filter watches (skills/**).

Mechanical regeneration, no hand edits: spec-changes.json gains the five
protocol-17 conversions and protocolVersion 17.0.0; the upgrade guide gains
its generated Protocol 16 → 17 section. All four job steps now pass locally
(check:skill-docs, check:spec-changes, check:upgrade-guide,
check:authorable-surface). Ships as a spec patch so npm consumers get the
corrected manifest.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LXvaYR7TiJBCxYwjn51owH

Author: claude

.changeset/spec-changes-manifest-catchup.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): regenerate the ADR-0087 change manifest the RC version bump left stale
+
+The v17 RC bump moved `PROTOCOL_VERSION` to `17.0.0` but did not re-run
+`gen:spec-changes` / `gen:upgrade-guide`, so the published `spec-changes.json`
+still declared `protocolVersion: 16.0.0` with no protocol-17 entries — while the
+protocol-17 conversions (`execute`→`target`, `conditionalRequired`→`requiredWhen`,
+`knowledge.topics`→`sources`, `agent.tools` removal, sharing `full`→`edit`) were
+already registered and applied at load. Anything projecting the manifest (the
+generated upgrade guide, the `spec_changes` MCP tool) reported a 16-era chain on
+a 17 protocol.
+
+`check:spec-changes` caught it, but only on the first PR to touch a
+generated-artifacts path after the bump — this regenerates both projections and
+turns the gate green again. `docs/protocol-upgrade-guide.md` now carries the
+Protocol 16 → 17 section.

docs/protocol-upgrade-guide.md

@@ -3,7 +3,7 @@
 
 # Metadata protocol upgrade guide
 
-Current protocol: **16.0.0** · chain support floor: **protocol 10** · generated from the ADR-0087 registries (`@objectstack/spec` `conversions/` + `migrations/`).
+Current protocol: **17.0.0** · chain support floor: **protocol 10** · generated from the ADR-0087 registries (`@objectstack/spec` `conversions/` + `migrations/`).
 
 ## How to upgrade — from any past major
 
@@ -114,6 +114,24 @@ Protocol 16 flipped `DashboardWidgetSchema` to `.strict()` (framework#3251, ADR-
   - Why not automatic: The `.strict()` flip turns a previously silently-stripped unknown key into a parse error. There is no mapping target for an arbitrary unknown key — auto-deleting it would be exactly the silent data loss ADR-0078 bans — so each occurrence needs the author to decide: bind a `dataset` and select `dimensions`/`values`, move a renderer setting under `options`, or delete the dead key.
   - Done when: `objectstack validate` passes with no unknown-key parse errors on dashboard widgets.
 
+## Protocol 16 → 17
+
+Protocol 17 removes the last three deprecated authorable aliases: action `execute` (use `target`), field `conditionalRequired` (use `requiredWhen`), and agent `knowledge.topics` (use `knowledge.sources`). Each was already lowered into its canonical key at parse time and dropped from the parsed output, so no runtime behaviour changes — only the authorable surface shrinks to one spelling per slot. All three are pure key renames with unchanged values and replay losslessly; the schemas reject the removed spellings with a fix-it error naming the replacement.
+
+It also removes the sharing-rule access level `full` (#3865): declared as "Full Access (Transfer, Share, Delete)" but never enforced as anything but `edit` — both gates matched `edit`/`full` alike, so Setup promised admins a delete grant it never issued (ADR-0078). Unlike the OWD `sharingModel: 'full'` alias retired at step 13, this one HAS a lossless target precisely because it was inert — old and new shapes are behaviourally identical — so it converts mechanically and leaves no semantic residue. It is the one protocol-17 conversion that keeps a load-path acceptance window: it had no prior deprecation, and a removed enum value cannot carry the fix-it error the three key renames tombstone theirs with.
+
+Finally it removes agent `tools` (#3894): the legacy inline `{type,name,description}[]` fallback, which the runtime resolved against the FULL tool registry with no surface check — the one seam that broke ADR-0064's "an agent reaches exactly its surface-compatible skills' tools, nothing falls through to the global registry". Unlike the renames above this has NO lossless target: each entry has to become a reference inside a skill, which is a human decision about which skill. The conversion therefore drops the dead key (the runtime stopped reading it in cloud#910, so it already contributes nothing) and emits a notice per agent so the author knows where capability must be re-declared; the schema tombstones the key with a fix-it error naming `skills`.
+
+### Mechanical (applied for you)
+
+| Conversion | Surface | Change | Load window |
+|---|---|---|---|
+| `action-execute-to-target` | `action.execute` | action key 'execute' → 'target' (the deprecated handler alias, #3713) | retired — `migrate meta` only |
+| `field-conditionalRequired-to-requiredWhen` | `field.conditionalRequired` | field key 'conditionalRequired' → 'requiredWhen' (the deprecated predicate alias, #3754) | retired — `migrate meta` only |
+| `agent-knowledge-topics-to-sources` | `agent.knowledge.topics` | agent knowledge key 'topics' → 'sources' (the deprecated RAG-source alias, #1891) | retired — `migrate meta` only |
+| `agent-tools-to-skills` | `agent.tools` | agent key 'tools' removed — declare capability in a skill (ADR-0064, #3894) | retired — `migrate meta` only |
+| `sharing-rule-access-level-full-to-edit` | `sharingRule.accessLevel` | sharing-rule accessLevel 'full' → 'edit' (#3865 — `full` never granted more than `edit`) | live — protocol 17 loader accepts the old shape |
+
 ---
 
 *Machine-readable equivalents: `spec-changes.json` (shipped in `@objectstack/spec` and attached to each GitHub Release) and the structured output of `objectstack migrate meta --json`.*

packages/spec/spec-changes.json

@@ -1,11 +1,11 @@
 {
   "$comment": "GENERATED (ADR-0087 D4) — do not edit. Regenerate with: pnpm --filter @objectstack/spec gen:spec-changes. A projection of the D2 conversion table + D3 migration chain; the upgrade guide and the MCP spec_changes tool derive from this same data.",
-  "protocolVersion": "16.0.0",
+  "protocolVersion": "17.0.0",
   "supportFloor": 10,
   "migrateCommand": "objectstack migrate meta --from <N>  (N >= 10)",
   "aggregate": {
     "from": 10,
-    "to": 16,
+    "to": 17,
     "added": [],
     "converted": [
       {
@@ -67,6 +67,36 @@
         "to": "page component key 'visibility' → 'visibleWhen' (ADR-0089)",
         "conversionId": "page-component-visibility-to-visibleWhen",
         "toMajor": 15
+      },
+      {
+        "surface": "action.execute",
+        "to": "action key 'execute' → 'target' (the deprecated handler alias, #3713)",
+        "conversionId": "action-execute-to-target",
+        "toMajor": 17
+      },
+      {
+        "surface": "field.conditionalRequired",
+        "to": "field key 'conditionalRequired' → 'requiredWhen' (the deprecated predicate alias, #3754)",
+        "conversionId": "field-conditionalRequired-to-requiredWhen",
+        "toMajor": 17
+      },
+      {
+        "surface": "agent.knowledge.topics",
+        "to": "agent knowledge key 'topics' → 'sources' (the deprecated RAG-source alias, #1891)",
+        "conversionId": "agent-knowledge-topics-to-sources",
+        "toMajor": 17
+      },
+      {
+        "surface": "agent.tools",
+        "to": "agent key 'tools' removed — declare capability in a skill (ADR-0064, #3894)",
+        "conversionId": "agent-tools-to-skills",
+        "toMajor": 17
+      },
+      {
+        "surface": "sharingRule.accessLevel",
+        "to": "sharing-rule accessLevel 'full' → 'edit' (#3865 — `full` never granted more than `edit`)",
+        "conversionId": "sharing-rule-access-level-full-to-edit",
+        "toMajor": 17
       }
     ],
     "migrated": [
@@ -330,6 +360,45 @@
         }
       ],
       "removed": []
+    },
+    {
+      "from": 16,
+      "to": 17,
+      "added": [],
+      "converted": [
+        {
+          "surface": "action.execute",
+          "to": "action key 'execute' → 'target' (the deprecated handler alias, #3713)",
+          "conversionId": "action-execute-to-target",
+          "toMajor": 17
+        },
+        {
+          "surface": "field.conditionalRequired",
+          "to": "field key 'conditionalRequired' → 'requiredWhen' (the deprecated predicate alias, #3754)",
+          "conversionId": "field-conditionalRequired-to-requiredWhen",
+          "toMajor": 17
+        },
+        {
+          "surface": "agent.knowledge.topics",
+          "to": "agent knowledge key 'topics' → 'sources' (the deprecated RAG-source alias, #1891)",
+          "conversionId": "agent-knowledge-topics-to-sources",
+          "toMajor": 17
+        },
+        {
+          "surface": "agent.tools",
+          "to": "agent key 'tools' removed — declare capability in a skill (ADR-0064, #3894)",
+          "conversionId": "agent-tools-to-skills",
+          "toMajor": 17
+        },
+        {
+          "surface": "sharingRule.accessLevel",
+          "to": "sharing-rule accessLevel 'full' → 'edit' (#3865 — `full` never granted more than `edit`)",
+          "conversionId": "sharing-rule-access-level-full-to-edit",
+          "toMajor": 17
+        }
+      ],
+      "migrated": [],
+      "removed": []
     }
   ]
 }