feat(core): render skill, reference, and MCP context updates as deltas

Pure additions announce only the new entries and pure removals name
what is gone, instead of restating the full list on every change.
Description or instruction edits still restate the superseding list.

packages/core/test/reference-guidance.test.ts

@@ -73,4 +73,41 @@ describe("ReferenceGuidance", () => {
       ),
     ),
   )
+
+  it.effect("announces added and removed references as deltas", () => {
+    const reference = (name: string, description: string) =>
+      new Reference.Info({
+        name,
+        path: AbsolutePath.make(`/${name}`),
+        description,
+        source: Reference.LocalSource.make({ type: "local", path: AbsolutePath.make(`/${name}`), description }),
+      })
+    let references = [reference("docs", "Use for product documentation")]
+    return Effect.gen(function* () {
+      const guidance = yield* ReferenceGuidance.Service
+      const initialized = yield* SystemContext.initialize(yield* guidance.load())
+
+      references = [reference("docs", "Use for product documentation"), reference("examples", "Use for examples")]
+      const added = yield* SystemContext.reconcile(yield* guidance.load(), initialized.applied)
+      expect(added).toMatchObject({
+        _tag: "Updated",
+        text: [
+          "New project references are available in addition to those previously listed:",
+          "  <reference>",
+          "    <name>examples</name>",
+          "    <path>/examples</path>",
+          "    <description>Use for examples</description>",
+          "  </reference>",
+        ].join("\n"),
+      })
+
+      references = [reference("examples", "Use for examples")]
+      expect(
+        yield* SystemContext.reconcile(yield* guidance.load(), added._tag === "Updated" ? added.applied : {}),
+      ).toMatchObject({
+        _tag: "Updated",
+        text: "The following project references are no longer available and must not be used: docs.",
+      })
+    }).pipe(Effect.provide(guidanceLayer(Layer.mock(Reference.Service, { list: () => Effect.succeed(references) }))))
+  })
 })

packages/core/test/skill/guidance.test.ts

@@ -74,7 +74,73 @@ describe("SkillGuidance", () => {
           .pipe(Effect.flatMap((context) => SystemContext.reconcile(context, initialized.applied))),
       ).toMatchObject({
         _tag: "Updated",
-        text: expect.stringContaining("No skills are currently available."),
+        text: "The following skills are no longer available and must not be used: effect.",
+      })
+    }).pipe(Effect.provide(layer(() => skills)))
+  })
+
+  it.effect("announces added and removed skills as deltas without restating the list", () => {
+    const agent = AgentV2.Info.make(AgentV2.Info.empty(build))
+    const debugging = SkillV2.Info.make({
+      name: "debugging",
+      description: "Diagnose hard bugs",
+      location: AbsolutePath.make(path.resolve("/skills/debugging/SKILL.md")),
+      content: "Debugging guidance",
+    })
+    let skills = [effect]
+    return Effect.gen(function* () {
+      const guidance = yield* SkillGuidance.Service
+      const initialized = yield* guidance
+        .load({ id: agent.id, info: agent })
+        .pipe(Effect.flatMap(SystemContext.initialize))
+
+      skills = [effect, debugging]
+      const added = yield* guidance
+        .load({ id: agent.id, info: agent })
+        .pipe(Effect.flatMap((context) => SystemContext.reconcile(context, initialized.applied)))
+      expect(added).toMatchObject({
+        _tag: "Updated",
+        text: [
+          "New skills are available in addition to those previously listed:",
+          "  <skill>",
+          "    <name>debugging</name>",
+          "    <description>Diagnose hard bugs</description>",
+          "  </skill>",
+        ].join("\n"),
+      })
+
+      skills = [debugging]
+      const removed = yield* guidance
+        .load({ id: agent.id, info: agent })
+        .pipe(
+          Effect.flatMap((context) => SystemContext.reconcile(context, added._tag === "Updated" ? added.applied : {})),
+        )
+      expect(removed).toMatchObject({
+        _tag: "Updated",
+        text: "The following skills are no longer available and must not be used: effect.",
+      })
+    }).pipe(Effect.provide(layer(() => skills)))
+  })
+
+  it.effect("restates the full skill list when a description changes", () => {
+    const agent = AgentV2.Info.make(AgentV2.Info.empty(build))
+    let skills = [effect]
+    return Effect.gen(function* () {
+      const guidance = yield* SkillGuidance.Service
+      const initialized = yield* guidance
+        .load({ id: agent.id, info: agent })
+        .pipe(Effect.flatMap(SystemContext.initialize))
+
+      skills = [SkillV2.Info.make({ ...effect, description: "Build applications with Effect v4" })]
+      expect(
+        yield* guidance
+          .load({ id: agent.id, info: agent })
+          .pipe(Effect.flatMap((context) => SystemContext.reconcile(context, initialized.applied))),
+      ).toMatchObject({
+        _tag: "Updated",
+        text: expect.stringContaining(
+          "The available skills have changed. This list supersedes the previous available skills list.",
+        ),
       })
     }).pipe(Effect.provide(layer(() => skills)))
   })