@synap-core/workspace-templates 0.12.0 → 0.23.0

package/src/send-message-maps.test.ts

@@ -0,0 +1,227 @@
+/**
+ * send_message and request_connection, as a pod app asks for them (CRM
+ * consolidation, plan 214f05bb, Lane 3; backend contract of Lane 2,
+ * feat/intent-send-message): the app sends ONE input `{ to: <entity id>, text,
+ * subject? }` (`request_connection`: `{ to, text? }`) and the pod resolves the
+ * recipient for each tool through `$to.<key>` (email, phone,
+ * linkedin.providerId, linkedin.publicIdentifier, chat, attendee). An action is
+ * reachable for a person when every `$to` path it reads resolves.
+ *
+ * Pinned here, where the maps are authored:
+ *  - ONE send door (founder decision d6, 2026-11-02, session d00cd2ac): no
+ *    Unipile verb serves send_message any more. An app's or automation's
+ *    send_message resolves to the pod's own `messaging.send` (Synap Core),
+ *    which files the message in the person's channel; `unipile_send_message`,
+ *    `unipile_start_chat` and `linkedin_send_first_message` stay as agent
+ *    tool calls, with no intent and no input map;
+ *  - Unipile: one action per account `unipile_list_accounts` lists (a declared
+ *    read, the pod refuses any other account source), LinkedIn AND Instagram,
+ *    for `linkedin_send_invite` (request_connection);
+ *  - LinkedIn by the person's PROFILE (2 Nov, session a638fbf2): no lead the
+ *    pod holds carries a LinkedIn member id, only `linkedinUrl`, which the pod
+ *    resolves as `linkedin.publicIdentifier`. `linkedin_send_first_message`
+ *    (an agent tool call) and `linkedin_send_invite` look the person up (which gives the
+ *    member id and the network distance) and refuse before sending what
+ *    LinkedIn would refuse: a message to someone not connected, an invitation
+ *    to someone connected or already invited, a note over 300 characters.
+ *    Their code runs here against a fake Unipile;
+ *  - Gmail: the person's email, the subject, the text as the body;
+ *  - the new verb starts a 1to1 chat, never a group;
+ *  - no Unipile skill carries an install-time `{{param}}` outside its
+ *    providerSpec (the pod's reconcile refuses to re-apply such a template,
+ *    "manual re-apply needed", so these maps could never reach an install).
+ *
+ * NOT covered: the pod's resolution of `$to` and its reach (backend); Unipile
+ * accepting the calls (checked against the v2 OpenAPI 2.62.0 reference, not a
+ * live account).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+type Skill = Record<string, any>;
+const load = (file: string) =>
+  JSON.parse(readFileSync(join(import.meta.dirname, "..", "capabilities", file), "utf8")) as {
+    spec: { skills: Skill[]; provides?: string[] };
+  };
+const unipile = load("unipile-linkedin.capability.json");
+const google = load("nango-google.capability.json");
+const skill = (cap: typeof unipile, name: string) => cap.spec.skills.find((s) => s.name === name)!;
+
+/** The recipient keys the pod resolves (Lane 2 contract). */
+const TO_KEYS = ["email", "phone", "linkedin.providerId", "linkedin.publicIdentifier", "chat", "attendee"];
+const ACCOUNTS = { verb: "unipile_list_accounts", id: "id", label: "name", provider: "provider" };
+
+describe("Unipile — what a pod app may ask it to send", () => {
+  it("the account source is a declared read listing every connected account", () => {
+    const list = skill(unipile, "unipile_list_accounts");
+    expect(list.metadata?.readOnly).toBe(true);
+    expect(list.providerSpec.pathTemplate).toBe("/accounts/");
+    // Every provider: LinkedIn and Instagram both get their own action (founder, 28 Oct, decision 34103d1b).
+    expect(list.providerSpec.query?.provider).toBeUndefined();
+  });
+
+  it.each(["unipile_send_message", "unipile_start_chat", "linkedin_send_first_message"])(
+    "%s serves no intent: send_message goes through the pod's send door (messaging.send)",
+    (name) => {
+      const verb = skill(unipile, name);
+      expect(verb, name).toBeDefined();
+      expect(verb.intent).toBeUndefined();
+      expect(verb.inputMap).toBeUndefined();
+    }
+  );
+
+  it("no Unipile verb serves send_message, and the capability does not provide it", () => {
+    expect(unipile.spec.skills.length).toBeGreaterThanOrEqual(14);
+    expect(unipile.spec.skills.filter((s) => s.intent === "send_message").map((s) => s.name)).toEqual([]);
+    expect(unipile.spec.provides).not.toContain("send_message");
+    // What it still serves for an app is untouched.
+    expect(unipile.spec.provides).toEqual(expect.arrayContaining(["request_connection", "publish_post"]));
+  });
+
+  it.each([
+    ["linkedin_send_invite", "request_connection", { providerId: "$to.linkedin.publicIdentifier", accountId: "$account.id", message: "$.text" }],
+  ])("%s serves %s, one action per Unipile account", (name, intent, params) => {
+    const verb = skill(unipile, name);
+    expect(verb.intent).toBe(intent);
+    expect(verb.inputMap).toEqual({ params, accounts: ACCOUNTS });
+    for (const param of Object.keys(params)) expect(Object.keys(verb.parameters)).toContain(param);
+  });
+
+  it("unipile_start_chat starts a 1to1 chat, LinkedIn through its CLASSIC_PRIMARY inbox", () => {
+    const code: string = skill(unipile, "unipile_start_chat").code;
+    expect(code).toContain("/inboxes/CLASSIC_PRIMARY/chats/send");
+    expect(code).toContain("/chats/send");
+    // users_ids as ONE string: an array, even of one id, asks Unipile for a group.
+    expect(code).toContain("users_ids: attendeeId");
+    expect(code).toMatch(/res\?\.proposed === true/);
+  });
+});
+
+/**
+ * Runs a verb's code as the pod's runtime does (`(async function(args, context){ <code> })` with
+ * callProvider and propose in scope) against a fake Unipile: the profile lookup answers `lookup`,
+ * every POST succeeds. Returns what it did, so a test reads the calls, never the code's text.
+ */
+function runVerb(name: string, args: Record<string, unknown>, lookup: { status: number; body?: Record<string, unknown> }) {
+  const calls: Array<{ method: string; path: string; body?: Record<string, unknown> }> = [];
+  const notes: Array<Record<string, unknown>> = [];
+  const callProvider = async (tool: string, method: string, path: string, body?: Record<string, unknown>) => {
+    expect(tool).toBe("unipile_linkedin");
+    calls.push({ method, path, body });
+    return method === "GET" ? { status: lookup.status, body: lookup.body ?? {} } : { status: 201, body: { chat_id: "chat_1", id: "rr_1" } };
+  };
+  const propose = { entity: async (e: Record<string, unknown>) => void notes.push(e) };
+  const fn = new Function("args", "context", "callProvider", "propose", `return (async function () {\n${skill(unipile, name).code}\n})();`);
+  return { done: fn(args, {}, callProvider, propose) as Promise<Record<string, unknown>>, calls, notes };
+}
+
+const ACCOUNT = "acc_li";
+const lookupPath = (who: string) => `/${ACCOUNT}/users/${who}?variant=linkedin_classic`;
+const connected = { status: 200, body: { provider_id: "ACoAAmember", public_identifier: "ada-lovelace", first_name: "Ada", last_name: "Lovelace", network_distance: "FIRST_DEGREE" } };
+
+describe("linkedin_send_first_message — a message to one person, by their profile", () => {
+  const send = (lookup: { status: number; body?: Record<string, unknown> }) =>
+    runVerb("linkedin_send_first_message", { accountId: ACCOUNT, attendeeId: "ada-lovelace", text: "Hello Ada" }, lookup);
+
+  it("looks the person up, then sends to their member id as ONE id (an array asks for a group)", async () => {
+    const run = send(connected);
+    await expect(run.done).resolves.toMatchObject({ success: true, attendeeId: "ACoAAmember", chatId: "chat_1" });
+    expect(run.calls).toEqual([
+      { method: "GET", path: lookupPath("ada-lovelace"), body: undefined },
+      { method: "POST", path: `/${ACCOUNT}/inboxes/CLASSIC_PRIMARY/chats/send`, body: { text: "Hello Ada", users_ids: "ACoAAmember" } },
+    ]);
+    expect(run.notes).toHaveLength(1);
+  });
+
+  it("reads v2's `id` when the profile has no provider_id", async () => {
+    const run = send({ status: 200, body: { id: "ACoAAv2", network_distance: "FIRST_DEGREE" } });
+    await expect(run.done).resolves.toMatchObject({ success: true, attendeeId: "ACoAAv2" });
+  });
+
+  it.each(["SECOND_DEGREE", "THIRD_DEGREE", "OUT_OF_NETWORK"])("refuses someone %s before anything is sent", async (distance) => {
+    const run = send({ status: 200, body: { ...connected.body, network_distance: distance } });
+    await expect(run.done).rejects.toThrow(/Ada Lovelace is not one of your LinkedIn connections yet.*connection request first/);
+    expect(run.calls.map((c) => c.method)).toEqual(["GET"]);
+    expect(run.notes).toHaveLength(0);
+  });
+
+  it("an unknown distance never blocks", async () => {
+    const run = send({ status: 200, body: { provider_id: "ACoAAmember" } });
+    await expect(run.done).resolves.toMatchObject({ success: true });
+  });
+
+  it("a profile LinkedIn does not know sends nothing", async () => {
+    const run = send({ status: 404 });
+    await expect(run.done).rejects.toThrow(/no profile for ada-lovelace/);
+    expect(run.calls.map((c) => c.method)).toEqual(["GET"]);
+  });
+});
+
+describe("linkedin_send_invite — a connection request, by their profile", () => {
+  const invite = (lookup: { status: number; body?: Record<string, unknown> }, message?: string) =>
+    runVerb("linkedin_send_invite", { accountId: ACCOUNT, providerId: "ada-lovelace", message }, lookup);
+  const stranger = { status: 200, body: { ...connected.body, network_distance: "SECOND_DEGREE" } };
+
+  it("looks the person up, then invites their member id with the note", async () => {
+    const run = invite(stranger, "Hi Ada");
+    await expect(run.done).resolves.toMatchObject({ success: true, providerId: "ACoAAmember" });
+    expect(run.calls).toEqual([
+      { method: "GET", path: lookupPath("ada-lovelace"), body: undefined },
+      { method: "POST", path: `/${ACCOUNT}/users/me/relation-requests`, body: { user_id: "ACoAAmember", message: "Hi Ada" } },
+    ]);
+  });
+
+  it("refuses someone already connected", async () => {
+    const run = invite(connected);
+    await expect(run.done).rejects.toThrow(/already one of your LinkedIn connections/);
+    expect(run.calls.map((c) => c.method)).toEqual(["GET"]);
+  });
+
+  it("refuses a second request while one is pending", async () => {
+    const run = invite({ status: 200, body: { ...stranger.body, invitation: { type: "SENT", status: "PENDING" } } });
+    await expect(run.done).rejects.toThrow(/already pending/);
+    expect(run.calls.map((c) => c.method)).toEqual(["GET"]);
+  });
+
+  it("refuses a note over LinkedIn's 300 characters before calling anyone", async () => {
+    const run = invite(stranger, "x".repeat(301));
+    await expect(run.done).rejects.toThrow(/at most 300 characters/);
+    expect(run.calls).toEqual([]);
+  });
+});
+
+describe("Unipile can be updated on every pod", () => {
+  // backend `installTimePlaceholders`: skill name and every projected field but providerSpec.
+  const scanned = unipile.spec.skills.map((s) => [s.name, JSON.stringify({ ...s, providerSpec: undefined })] as const);
+
+  it("sees every skill (the scan is not empty)", () => {
+    expect(scanned.length).toBeGreaterThanOrEqual(14);
+  });
+
+  it.each(scanned)("%s carries no install-time placeholder", (_name, fields) => {
+    expect(fields).not.toMatch(/\{\{\s*\w+\s*\}\}/);
+  });
+
+  it("the only install param is the API key (the account is a call argument)", () => {
+    expect((unipile.spec as { params?: Array<{ name: string }> }).params?.map((p) => p.name)).toEqual(["unipileApiKey"]);
+  });
+});
+
+describe("Gmail — what a pod app may ask it to send", () => {
+  it("gmail_send writes to the person's email, with the subject, the text as its body", () => {
+    const verb = skill(google, "gmail_send");
+    expect(verb.intent).toBe("send_message");
+    expect(verb.inputMap).toEqual({ params: { to: "$to.email", subject: "$.subject", body: "$.text" } });
+  });
+});
+
+describe("every $to path in the catalog names a key the pod resolves", () => {
+  it("send and invite maps read only known recipient keys", () => {
+    const paths = [...unipile.spec.skills, ...google.spec.skills]
+      .flatMap((s) => Object.values((s.inputMap?.params ?? {}) as Record<string, unknown>))
+      .filter((v): v is string => typeof v === "string" && v.startsWith("$to."));
+    expect(paths.length).toBeGreaterThanOrEqual(2);
+    for (const p of paths) expect(TO_KEYS, p).toContain(p.slice("$to.".length));
+  });
+});

package/src/shared-role-ssot.test.ts

@@ -124,9 +124,10 @@ describe("workspace-templates — shared ecosystem role SSOT (corpus)", () => {
     expect(foundation, "foundation template must exist in the corpus").toBeDefined();
     // `porteur` and `funder` join the relationship roles: a business model
     // rests on WHO carries it and WHO funds it, and both are revocable hats on
-    // an existing person/company rather than kinds of their own.
+    // an existing person/company rather than kinds of their own. `churned` is
+    // NOT here: a state is never a role — it is `clientStatus: churned`.
     expect([...SHARED_ROLE_SLUGS].sort()).toEqual(
-      ["churned", "client", "funder", "lead", "partner", "porteur", "sponsor"]
+      ["client", "funder", "lead", "partner", "porteur", "sponsor"]
     );
   });
 
@@ -268,4 +269,41 @@ describe("workspace-templates — shared ecosystem role SSOT (corpus)", () => {
       );
     expect(violations, violations.join("\n")).toEqual([]);
   });
+
+  // (e) A STATE IS NEVER A ROLE (work model, founder rule 2026-10-11). The
+  // `churned` role duplicated `clientStatus: churned`: one fact, two homes, and
+  // nothing kept them in step. A role slug that is also a status value of some
+  // role is that defect again. The status values are DERIVED from every role's
+  // status-like select (slug ending in status/stage) across the corpus, never
+  // hand-listed. Granularity: role slugs vs ROLE status values only — a kind's
+  // stage value (deal's `lead`) is deliberately not scanned, since a deal stage
+  // named after the lead role is a different (wave-1) question.
+  it("(e) no role slug is also a status value of a role", () => {
+    const STATUS_LIKE = /(status|stage)$/i;
+    const stateValues = new Map<string, string>();
+    const roleSlugs = new Map<string, string>();
+    for (const tpl of templates) {
+      for (const p of profilesOf(tpl)) {
+        if (normalizeKind(p.profileKind) !== "role") continue;
+        roleSlugs.set(p.slug, templateSlug(tpl));
+        for (const prop of p.properties ?? []) {
+          if (!STATUS_LIKE.test(prop.slug) || !Array.isArray(prop.enumValues)) continue;
+          for (const v of prop.enumValues) {
+            stateValues.set(String(v), `${templateSlug(tpl)}:${p.slug}.${prop.slug}`);
+          }
+        }
+      }
+    }
+    // Non-vacuity: the scan still sees the value that motivated it.
+    expect(stateValues.get("churned"), "scan no longer sees clientStatus: churned").toBeDefined();
+    expect(roleSlugs.size).toBeGreaterThan(10);
+    const violations = [...roleSlugs.entries()]
+      .filter(([slug]) => stateValues.has(slug))
+      .map(
+        ([slug, tpl]) =>
+          `${tpl} declares role '${slug}', which is also the status value ${stateValues.get(slug)}. ` +
+          `A state is never a role: make it an option of that status, not a facet.`
+      );
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
 });

package/src/ship-a-change.template.test.ts

@@ -0,0 +1,177 @@
+/**
+ * The dev loop as stored config (plan v5 T2): Builder's "Ship a change", the
+ * staged `ship-a-change-*` automations that move it on facts, and the
+ * `github-read` capability that reads the same facts on the person's token.
+ *
+ * What this guards:
+ *   1. the process FOLLOWS the feature's declared lifecycle: it names that
+ *      property, and every status a stage writes or a worker reads is one of
+ *      its options (never an invented one);
+ *   2. ONE human gate, at the lab deploy (the commitment); red checks send the
+ *      work back to Build; the PR is a declared `pull_request` outcome;
+ *   3. REACHABILITY across files (derived from the automation files, not
+ *      listed): every stage an automation moves a session to is a stage of
+ *      the process, every evidence key an automation posts is one a criterion
+ *      reads, and every playbook an automation runs exists in Builder; a
+ *      merge acts only through a guard that it landed on the default branch
+ *      (`intoDefault`, decision F3: a stacked merge is not delivered);
+ *   4. github-read stays read-only and bring-your-own: every declarative verb
+ *      is a GET on its vaulted tool, a code verb (the merged CHECK) calls its
+ *      tool with GET only and nothing else, and the token is the person's
+ *      (never pod-wide).
+ *
+ * Not covered: whether the pod runs the staged automations (they need
+ * backend#286's verbs), and GitHub's real responses (NEEDS-DOGFOOD).
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { getWorkspaceTemplate } from "./templates.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const builder = getWorkspaceTemplate("builder-workspace")!;
+const pb = builder.playbooks!.find((p) => p.name === "Ship a change")! as unknown as {
+  subjectProfile: { profileSlug: string; statusProperty?: string };
+  activators?: { on: string; status?: string; mode?: string }[];
+  stages: {
+    key: string;
+    subjectStatus?: string;
+    gate?: { kind: string };
+    onFail?: { toStage: string };
+    criteria?: { key: string; check: { kind: string; evidenceKey?: string } }[];
+    expectedOutputs?: { kind: string }[];
+  }[];
+};
+const feature = builder.profiles.find((p) => p.slug === pb.subjectProfile.profileSlug)! as unknown as {
+  lifecycle: { property: string; options: { key: string }[] };
+};
+
+type FlowNode = { id: string; type: string; data: Record<string, any> };
+type FlowEdge = { source: string; target: string };
+const automationDir = join(HERE, "../automations");
+const automations = readdirSync(automationDir)
+  .filter((f) => f.startsWith("ship-a-change-") && f.endsWith(".automation.json"))
+  .map((f) => {
+    const raw = JSON.parse(readFileSync(join(automationDir, f), "utf8"));
+    return {
+      file: f,
+      event: raw.triggerConfig?.eventPattern as string | undefined,
+      nodes: raw.flowDefinition.nodes as FlowNode[],
+      edges: raw.flowDefinition.edges as FlowEdge[],
+    };
+  });
+const outputs = (type: string) =>
+  automations.flatMap((a) =>
+    a.nodes.filter((n) => n.type === "output" && n.data.outputType === type).map((n) => ({ file: a.file, n }))
+  );
+
+describe("Ship a change — the process follows the feature's lifecycle", () => {
+  it("names the lifecycle property, and every status it writes or reads is an option of it", () => {
+    expect(pb.subjectProfile.statusProperty).toBe(feature.lifecycle.property);
+    const options = new Set(feature.lifecycle.options.map((o) => o.key));
+    const used = [
+      ...pb.stages.map((s) => s.subjectStatus).filter(Boolean),
+      ...(pb.activators ?? []).map((a) => a.status).filter(Boolean),
+    ];
+    expect(used.length).toBeGreaterThanOrEqual(5); // non-vacuity: spec, in_progress, in_review, done + the worker's spec
+    expect(used.filter((s) => !options.has(s!))).toEqual([]);
+  });
+
+  it("one human gate, at the lab deploy; red checks go back to Build; the PR is a pull_request outcome", () => {
+    expect(pb.stages.filter((s) => s.gate?.kind === "human").map((s) => s.key)).toEqual(["deploy"]);
+    const checks = pb.stages.find((s) => s.key === "checks")!;
+    expect(checks.gate).toEqual({ kind: "check" });
+    expect(checks.onFail).toEqual({ toStage: "build" });
+    const prStage = pb.stages.find((s) => s.key === "pr-opened")!;
+    expect(prStage.expectedOutputs?.map((o) => o.kind)).toContain("pull_request");
+    const keys = new Set(pb.stages.map((s) => s.key));
+    expect(pb.stages.flatMap((s) => (s.onFail ? [s.onFail.toStage] : [])).filter((k) => !keys.has(k))).toEqual([]);
+  });
+
+  it("a worker proposes (never runs) when a feature is shaped", () => {
+    expect(pb.activators).toContainEqual(expect.objectContaining({ on: "enters_status", status: "spec", mode: "propose" }));
+    expect((pb.activators ?? []).filter((a) => a.mode !== "propose")).toEqual([]);
+  });
+});
+
+describe("the staged ship-a-change automations reach the process", () => {
+  it("every stage an automation moves a session to is a stage of Ship a change", () => {
+    const moves = outputs("session_update");
+    expect(moves.length).toBeGreaterThanOrEqual(4); // non-vacuity: opened, green, red, merged
+    const keys = new Set(pb.stages.map((s) => s.key));
+    expect(moves.filter(({ n }) => !keys.has(n.data.config.currentStage)).map(({ file, n }) => `${file}: ${n.data.config.currentStage}`)).toEqual([]);
+  });
+
+  it("every evidence key an automation posts is one a criterion of the process reads", () => {
+    const posted = outputs("post_evidence").flatMap(({ file, n }) => Object.keys(n.data.config.evidence).map((k) => ({ file, k })));
+    expect(posted.length).toBeGreaterThanOrEqual(4);
+    const read = new Set(pb.stages.flatMap((s) => (s.criteria ?? []).map((c) => c.check.evidenceKey).filter(Boolean)));
+    expect(posted.filter(({ k }) => !read.has(k)).map(({ file, k }) => `${file}: ${k}`)).toEqual([]);
+  });
+
+  it("every playbook an automation runs is a Builder playbook", () => {
+    const runs = automations.flatMap((a) => a.nodes.filter((n) => n.type === "playbook_run").map((n) => n.data.playbookName));
+    expect(runs.length).toBeGreaterThanOrEqual(1);
+    const names = new Set(builder.playbooks!.map((p) => p.name));
+    expect(runs.filter((r) => !names.has(r))).toEqual([]);
+  });
+
+  it("a merge acts only after a guard that it landed on the default branch", () => {
+    const merged = automations.filter((a) => a.event === "dev.pr_merged");
+    expect(merged.length).toBeGreaterThanOrEqual(1);
+    // Reachability, not shape: drop every guard that checks intoDefault === true,
+    // then no output may still be reachable from the trigger.
+    const unguarded = merged.flatMap((a) => {
+      const blocks = new Set(
+        a.nodes
+          .filter((n) => n.type === "guard" && (n.data.checks ?? []).some((c: any) => c.path === "trigger.payload.data.intoDefault" && c.equals === true))
+          .map((n) => n.id)
+      );
+      const seen = new Set<string>();
+      const queue = a.nodes.filter((n) => n.type === "trigger").map((n) => n.id);
+      while (queue.length) {
+        const id = queue.shift()!;
+        if (seen.has(id) || blocks.has(id)) continue;
+        seen.add(id);
+        queue.push(...a.edges.filter((e) => e.source === id).map((e) => e.target));
+      }
+      return a.nodes.filter((n) => n.type !== "trigger" && n.type !== "guard" && seen.has(n.id)).map((n) => `${a.file}: ${n.id}`);
+    });
+    expect(unguarded).toEqual([]);
+  });
+});
+
+describe("github-read — read-only, bring your own token", () => {
+  const cap = JSON.parse(readFileSync(join(HERE, "../capabilities/github-read.capability.json"), "utf8")).spec;
+  const tools = new Set((cap.tools as { name: string }[]).map((t) => t.name));
+
+  it("every verb only reads: a declarative verb is a GET, a code verb calls its tool with GET only", () => {
+    expect(cap.skills.length).toBeGreaterThanOrEqual(5); // pr get, checks, release latest, compare + the merged check
+    const code = cap.skills.filter((s: { kind: string }) => s.kind === "code");
+    expect(code.length).toBeGreaterThanOrEqual(1); // non-vacuity: github_check_pr_merged
+    for (const s of cap.skills) {
+      expect(s.requires.every((t: string) => tools.has(t)), s.name).toBe(true);
+      expect(s.metadata?.readOnly, s.name).toBe(true);
+      if (s.kind === "declarative") {
+        expect(s.providerSpec.method, s.name).toBe("GET");
+        expect(tools.has(s.providerSpec.tool), s.name).toBe(true);
+        continue;
+      }
+      expect(s.kind, s.name).toBe("code");
+      const calls = [...String(s.code).matchAll(/callProvider\(\s*'([^']+)'\s*,\s*'([A-Z]+)'/g)];
+      expect(calls.length, s.name).toBeGreaterThanOrEqual(1);
+      for (const [, tool, method] of calls) {
+        expect(tools.has(tool), `${s.name} → ${tool}`).toBe(true);
+        expect(method, `${s.name} → ${tool}`).toBe("GET");
+      }
+      expect(String(s.code), s.name).not.toMatch(/host\.fetch|propose\./);
+    }
+  });
+
+  it("the token is the person's own vault secret, never pod-wide, and every tool uses it", () => {
+    const refs = new Set((cap.vault as { ref: string; podWide?: boolean }[]).map((v) => v.ref));
+    expect((cap.vault as { podWide?: boolean }[]).filter((v) => v.podWide)).toEqual([]);
+    for (const t of cap.tools) expect(refs.has(t.credentialRef), t.name).toBe(true);
+  });
+});

package/src/skills.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Space-linked skills — the DECLARATION side.
+ *
+ * A template declares `skills: [{ slug, when, mode }]`; the pod links each to
+ * the new space at install. This file proves three things a live pod depends on:
+ *
+ *   1. the SHAPE rule fires (bad slug, bad mode, duplicate) — the same
+ *      `validateSpaceSkillDeclaration` the pod's applier runs, so author time
+ *      and install time cannot drift;
+ *   2. a well-formed declaration REACHES THE WIRE via `toPackageDefinition`
+ *      (asserted on the VALUE, not the key's existence — a declared-but-dropped
+ *      field is the failure this whole ledger exists to prevent);
+ *   3. the workspace door does NOT carry it, which is the deliberate routing
+ *      recorded in `WorkspaceDefinitionDropped` — if that ever flips, this test
+ *      says so instead of the field silently landing nowhere.
+ */
+
+import { describe, expect, it } from "vitest";
+import { toPackageDefinition, toWorkspaceDefinition } from "./define.js";
+import { validateTemplate } from "./validate.js";
+import type { WorkspaceYaml } from "./types.js";
+
+/** The smallest template that can carry a `skills:` declaration. */
+function tplWith(skills: unknown): WorkspaceYaml {
+  return {
+    meta: {
+      slug: "skills-probe",
+      name: "Skills probe",
+      description: "d",
+      icon: "x",
+      color: "violet",
+    },
+    workspace: { name: "Skills probe", description: "d" },
+    profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
+    skills,
+  } as unknown as WorkspaceYaml;
+}
+
+const GOOD = [
+  {
+    slug: "system/synap/creative-director",
+    when: "any content ask — carousel, deck, video",
+    mode: "always",
+  },
+];
+
+describe("skills — a template declares them and validation enforces the shape", () => {
+  it("accepts a well-formed declaration (the happy path is not vacuous)", () => {
+    const result = validateTemplate(tplWith(GOOD), {});
+    const skillErrors = result.errors.filter((e) => e.rule.startsWith("skill-"));
+    expect(
+      skillErrors,
+      `a valid declaration must raise no skill rule: ${JSON.stringify(skillErrors)}`
+    ).toEqual([]);
+  });
+
+  it("rejects a malformed slug with an actionable path", () => {
+    const result = validateTemplate(
+      tplWith([{ slug: "System/Synap/Creative-Director", mode: "always" }]),
+      {}
+    );
+    const bad = result.errors.find((e) => e.rule === "skill-invalid");
+    expect(bad, JSON.stringify(result.errors)).toBeDefined();
+    expect(bad!.path).toBe("skills.0");
+    expect(bad!.message).toMatch(/not a valid skill slug/);
+  });
+
+  it("rejects an unknown mode", () => {
+    const result = validateTemplate(
+      tplWith([{ slug: "system/synap/x", mode: "sometimes" }]),
+      {}
+    );
+    const bad = result.errors.find((e) => e.rule === "skill-invalid");
+    expect(bad, JSON.stringify(result.errors)).toBeDefined();
+    expect(bad!.message).toMatch(/`mode` must be one of/);
+  });
+
+  it("rejects the SAME skill declared twice — two modes is ambiguous, not a merge", () => {
+    const result = validateTemplate(
+      tplWith([
+        { slug: "system/synap/x", mode: "always" },
+        { slug: "system/synap/x", mode: "on-demand" },
+      ]),
+      {}
+    );
+    const dup = result.errors.find((e) => e.rule === "skill-duplicate");
+    expect(dup, JSON.stringify(result.errors)).toBeDefined();
+    expect(dup!.path).toBe("skills.1.slug");
+  });
+});
+
+describe("skills — a LINK needs an INSTALL (the silent failure, made loud)", () => {
+  /** The same probe, able to declare dependencies too. */
+  function tpl(skills: unknown, dependencies?: unknown): WorkspaceYaml {
+    return {
+      ...(tplWith(skills) as unknown as Record<string, unknown>),
+      ...(dependencies ? { dependencies } : {}),
+    } as unknown as WorkspaceYaml;
+  }
+  const LINK = [{ slug: "creative-director", mode: "on-demand" }];
+
+  it("REFUSES a link nothing installs — that is the silent one", () => {
+    // Without this rule the template publishes, installs cleanly, and the skill
+    // link does NOTHING: a missing dependency is non-fatal by design, so the
+    // only symptom is an agent that never gets the skill.
+    const result = validateTemplate(tpl(LINK), {});
+    const rule = result.errors.find(
+      (e) => e.rule === "skill-linked-without-install"
+    );
+    expect(rule, JSON.stringify(result.errors)).toBeDefined();
+    expect(rule!.path).toBe("skills.0.slug");
+    expect(rule!.message).toContain("dependencies");
+  });
+
+  it("accepts the same link once the dependency declares it", () => {
+    const result = validateTemplate(
+      tpl(LINK, [
+        { slug: "creative-director", kind: "skill", relation: "require" },
+      ]),
+      {}
+    );
+    expect(
+      result.errors.filter((e) => e.rule === "skill-linked-without-install")
+    ).toEqual([]);
+  });
+
+  it("accepts the seeded `system/…` namespace — present on every pod, no install needed", () => {
+    const result = validateTemplate(
+      tpl([{ slug: "system/synap/onboard", mode: "on-demand" }]),
+      {}
+    );
+    expect(
+      result.errors.filter((e) => e.rule === "skill-linked-without-install")
+    ).toEqual([]);
+  });
+
+  it("a WORKSPACE dependency does not satisfy a skill link", () => {
+    // The kinds are not interchangeable: `require`ing a workspace brings a space,
+    // not a skill row, and the link would still resolve to nothing.
+    const result = validateTemplate(
+      tpl(LINK, [{ slug: "creative-director", kind: "workspace" }]),
+      {}
+    );
+    expect(
+      result.errors.some((e) => e.rule === "skill-linked-without-install")
+    ).toBe(true);
+  });
+});
+
+describe("skills — the declaration reaches the wire (and only the right door)", () => {
+  it("toPackageDefinition carries the declared skills, value for value", () => {
+    const pkg = toPackageDefinition(tplWith(GOOD));
+    // Value equality, not merely a present key: a ledger entry is a CLAIM about
+    // routing, and only the value arriving can check it.
+    expect(pkg.skills).toEqual(GOOD);
+  });
+
+  it("a template with no skills emits no `skills` key at all", () => {
+    const pkg = toPackageDefinition(tplWith(undefined));
+    expect("skills" in pkg).toBe(false);
+  });
+
+  it("the WORKSPACE door does NOT carry skills — the routing is deliberate", () => {
+    // Recorded in `WorkspaceDefinitionDropped`: the skill is linked post-workspace
+    // by the package apply, so the workspace door has no such field. If this ever
+    // starts passing `skills` through, the ledger comment is stale.
+    const result = toWorkspaceDefinition(tplWith(GOOD));
+    expect("skills" in result.definition).toBe(false);
+  });
+});