@synap-core/workspace-templates 0.12.0 → 0.24.0

package/src/start.test.ts

@@ -0,0 +1,188 @@
+/**
+ * `meta.start` — a template declares itself an onboarding start (A1).
+ *
+ * Pinned:
+ *  - a well-formed start validates with zero `start-*` errors;
+ *  - each `start-*` rule fires on a minimal broken fixture (and only it);
+ *  - the package door forwards a TOP-LEVEL `start`, never inside `_meta`;
+ *  - the catalog header accepts the shape and refuses it on a non-space kind.
+ */
+import { describe, expect, it } from "vitest";
+import { validateTemplate } from "./validate.js";
+import { toPackageDefinition } from "./define.js";
+import { INTENT_LABEL_MAX } from "./types.js";
+import type { TemplateProfile, TemplateStart, WorkspaceYaml } from "./types.js";
+import { manifestSchemaFor } from "../schema/index.ts";
+import { listWorkspaceTemplates } from "./templates.js";
+
+const deal: TemplateProfile = {
+  slug: "deal",
+  displayName: "Deal",
+  properties: [
+    { slug: "commercialStage", label: "Stage", valueType: "string", inputType: "select", enumValues: ["lead", "negotiating", "won"] },
+    { slug: "value", label: "Value", valueType: "number" },
+  ],
+} as TemplateProfile;
+
+const goodStart = (over: Partial<TemplateStart> = {}): TemplateStart => ({
+  order: 1,
+  label: "Sales",
+  promise: "Leads and deals, each with a dated next step.",
+  suggestFor: ["founder"],
+  profile: "deal",
+  views: ["deal-pipeline", "deals-table"],
+  example: [1, 2, 3, 4].map((n) => ({ title: `Deal ${n}`, values: { commercialStage: "negotiating", value: n * 1000 } })),
+  firstSession: { title: "Your live deals", goal: "Add the deals you are moving now." },
+  starters: ["a", "b", "c"],
+  ...over,
+});
+
+const make = (slug: string, start?: Partial<TemplateStart> | null, extra: Partial<WorkspaceYaml> = {}): WorkspaceYaml =>
+  ({
+    meta: { slug, name: slug, description: "d", icon: "box", color: "blue", ...(start === null ? {} : { start: goodStart(start) }) },
+    workspace: { name: slug, description: "d" },
+    profiles: [deal],
+    views: [
+      { name: "Pipeline", slug: "deal-pipeline", type: "kanban", scopeProfileSlug: "deal" },
+      { name: "Deals", slug: "deals-table", type: "table", scopeProfileSlugs: ["deal"] },
+      { name: "Other", slug: "other-table", type: "table", scopeProfileSlug: "task" },
+    ],
+    ...extra,
+  }) as unknown as WorkspaceYaml;
+
+const startErrors = (t: WorkspaceYaml, corpus?: WorkspaceYaml[]) =>
+  validateTemplate(t, { corpus }).errors.filter((e) => e.rule.startsWith("start-")).map((e) => e.rule);
+
+describe("meta.start — validator rules", () => {
+  it("a well-formed start passes", () => {
+    expect(startErrors(make("t"))).toEqual([]);
+  });
+
+  it("no start → no start-* error", () => {
+    expect(startErrors(make("t", null))).toEqual([]);
+  });
+
+  it("start-shape: a missing field", () => {
+    const t = make("t");
+    delete (t.meta.start as Partial<TemplateStart>).promise;
+    expect(startErrors(t)).toEqual(["start-shape"]);
+  });
+
+  it("start-no-workspace: an overlay owns no space", () => {
+    const t = make("t", {}, { dependencies: [{ slug: "base", relation: "compose" }] } as Partial<WorkspaceYaml>);
+    expect(startErrors(t)).toEqual(["start-no-workspace"]);
+  });
+
+  it("start-label: longer than INTENT_LABEL_MAX", () => {
+    expect(startErrors(make("t", { label: "x".repeat(INTENT_LABEL_MAX + 1) }))).toEqual(["start-label"]);
+  });
+
+  it("start-example-count and start-starters-count", () => {
+    expect(startErrors(make("t", { example: goodStart().example.slice(0, 3) }))).toEqual(["start-example-count"]);
+    expect(startErrors(make("t", { starters: ["a"] }))).toEqual(["start-starters-count"]);
+  });
+
+  it("start-views-count: none, or more than three", () => {
+    expect(startErrors(make("t", { views: [] }))).toEqual(["start-views-count"]);
+    expect(startErrors(make("t", { views: ["deal-pipeline", "deals-table", "deal-pipeline", "deals-table"] }))).toEqual(["start-views-count"]);
+  });
+
+  it("start-views-exist: a slug this template does not declare", () => {
+    expect(startErrors(make("t", { views: ["deal-pipeline", "nope"] }))).toEqual(["start-views-exist"]);
+  });
+
+  it("start-views-scope: a view scoped to another kind", () => {
+    expect(startErrors(make("t", { views: ["other-table"] }))).toEqual(["start-views-scope"]);
+  });
+
+  it("start-profile-unknown: a kind nobody declares", () => {
+    expect(startErrors(make("t", { profile: "ghost", views: [], example: goodStart().example.map((e) => ({ title: e.title })) }))).toContain("start-profile-unknown");
+  });
+
+  it("start-profile-unknown: the kind may come from the dependency closure", () => {
+    const dep = { meta: { slug: "dep", name: "dep", description: "d", icon: "b", color: "c" }, workspace: { name: "d", description: "d" }, profiles: [deal] } as unknown as WorkspaceYaml;
+    const t = make("t", { views: [] }, { profiles: [], views: [], dependencies: [{ slug: "dep", relation: "require" }] } as Partial<WorkspaceYaml>);
+    expect(startErrors(t, [t, dep])).toEqual(["start-views-count"]); // profile resolves; only the empty views fire
+  });
+
+  it("start-example-property: a key the kind does not have", () => {
+    const example = goodStart().example.map((e) => ({ ...e, values: { ...e.values, mood: "x" } }));
+    expect(startErrors(make("t", { example }))).toEqual(Array(4).fill("start-example-property"));
+  });
+
+  it("start-example-enum: a select value outside enumValues", () => {
+    const example = goodStart().example.map((e) => ({ ...e, values: { commercialStage: "dancing" } }));
+    expect(startErrors(make("t", { example }))).toEqual(Array(4).fill("start-example-enum"));
+  });
+
+  it("start-suggest-duplicate: an id twice in one start, and across starts", () => {
+    expect(startErrors(make("t", { suggestFor: ["founder", "founder"] }))).toEqual(["start-suggest-duplicate"]);
+    const a = make("a", { order: 1, suggestFor: ["founder"] });
+    const b = make("b", { order: 2, suggestFor: ["founder"] });
+    expect(startErrors(b, [a, b])).toEqual(["start-suggest-duplicate"]);
+  });
+
+  it("start-order-duplicate: two starts on one card slot", () => {
+    const a = make("a", { order: 1, suggestFor: ["x"] });
+    const b = make("b", { order: 1, suggestFor: ["y"] });
+    expect(startErrors(b, [a, b])).toEqual(["start-order-duplicate"]);
+    expect(startErrors(make("b", { order: 2, suggestFor: ["y"] }), [a, make("b", { order: 2, suggestFor: ["y"] })])).toEqual([]);
+  });
+});
+
+describe("meta.start — package door", () => {
+  it("carries a top-level start, never in _meta", () => {
+    const def = toPackageDefinition(make("t"));
+    expect(def.start).toEqual(goodStart());
+    expect("start" in def._meta).toBe(false);
+  });
+
+  it("no start → no field", () => {
+    expect("start" in toPackageDefinition(make("t", null))).toBe(false);
+  });
+});
+
+describe("meta.start — catalog header", () => {
+  const manifest = (kind: "workspace" | "skill", meta: Record<string, unknown>) => ({
+    apiVersion: "synap/v1",
+    kind,
+    meta: { slug: "t", name: "T", ...meta },
+    spec: kind === "workspace" ? { workspace: { name: "T", description: "d" }, profiles: [] } : { name: "t", content: "x" },
+  });
+
+  it("a workspace header accepts the shape and refuses an unknown key", () => {
+    expect(manifestSchemaFor("workspace").safeParse(manifest("workspace", { start: goodStart() })).success).toBe(true);
+    expect(manifestSchemaFor("workspace").safeParse(manifest("workspace", { start: { ...goodStart(), why: 1 } })).success).toBe(false);
+  });
+
+  it("is refused on a kind that is not a workspace", () => {
+    const r = manifestSchemaFor("skill").safeParse(manifest("skill", { start: goodStart() }));
+    expect(r.success).toBe(false);
+    expect(r.error?.issues.some((i) => i.path.join(".") === "meta.start")).toBe(true);
+  });
+});
+
+describe("meta.start — the shipped catalog (A2)", () => {
+  const all = listWorkspaceTemplates();
+  const starts = all.filter((t) => t.meta.start);
+
+  it("declares exactly the four starts, card orders 1-4", () => {
+    expect(starts.map((t) => [t.meta.start!.order, t.meta.slug]).sort()).toEqual([
+      [1, "builder-workspace"],
+      [2, "content-os"],
+      [3, "crm"],
+      [4, "operations"],
+    ]);
+  });
+
+  it("every start passes the start-* rules against the whole corpus", () => {
+    for (const t of starts) expect(startErrors(t, all), t.meta.slug).toEqual([]);
+  });
+
+  it("CRM has three deal views scoped to deal", () => {
+    const crm = all.find((t) => t.meta.slug === "crm")!;
+    const dealViews = (crm.views ?? []).filter((v) => v.scopeProfileSlug === "deal").map((v) => v.slug);
+    expect(dealViews).toEqual(["deal-pipeline", "deals-table", "deals-list"]);
+    expect(crm.meta.start!.views).toEqual(dealViews);
+  });
+});

package/src/stripe-capability.test.ts

@@ -0,0 +1,192 @@
+/**
+ * The Stripe capability (session 92e83544, "Stripe capability: read-write,
+ * governed"): reads run, every write is reviewed, and the call can only ever
+ * reach https://api.stripe.com/v1/.
+ *
+ * Pinned here, where the verbs are authored:
+ *  - a GET verb declares `metadata.readOnly: true` (the gate runs it at once);
+ *    a verb that writes (POST, DELETE) never does, so it stays on the propose
+ *    grant the pod seeds for every capability tool (`GRANT_DEFAULT_EXEC_MODE`)
+ *    and its provider call re-checks the tool gate (`isReadMethod`);
+ *  - a write verb declares no read intent (list_records / fetch_record), and
+ *    its name or description carries a whole-word write signal, so the pod's
+ *    `deriveVerbKind` files it as an `action`, never a `read`;
+ *  - the tool's host is fixed (`baseUrl`), its bodies are form-encoded
+ *    (`config.bodyEncoding: "form"`, Stripe v1 takes no JSON body);
+ *  - every path is under `/v1/`; the generic verbs take their resource path
+ *    through `encode: "path"` (the pod refuses "." / ".." / empty segments);
+ *  - every Stripe-native field travels through `bodyFrom` (`fields` on a typed
+ *    verb, `params` on a generic one), never a `body` template that would send
+ *    an absent optional as an empty value (which Stripe reads as "unset");
+ *  - the eight read verbs live pods already run are all still there.
+ *
+ * NOT covered: Stripe accepting the calls (checked against the API reference,
+ * docs.stripe.com/api, not the live account; no write is ever sent to it), and
+ * the pod's encoder and gate (backend: form-encode.test.ts,
+ * execute-provider-verb.body-from.test.ts, form-body.vault.test.ts).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const manifest = JSON.parse(
+  readFileSync(join(__dirname, "..", "capabilities", "stripe.capability.json"), "utf8"),
+);
+type Verb = {
+  name: string;
+  intent?: string;
+  kind: string;
+  description: string;
+  requires: string[];
+  parameters?: Record<string, string>;
+  metadata?: { readOnly?: boolean };
+  providerSpec: {
+    method: string;
+    pathTemplate: string;
+    body?: unknown;
+    bodyFrom?: string;
+    paramMapping?: Record<string, { encode?: string; required?: boolean }>;
+  };
+};
+const verbs: Verb[] = manifest.spec.skills;
+const isRead = (v: Verb) => /^(GET|HEAD)$/i.test(v.providerSpec.method);
+const reads = verbs.filter(isRead);
+const writes = verbs.filter((v) => !isRead(v));
+
+// A mirror of the pod's own word lists (synap-backend create-from-definition.ts
+// VERB_WRITE_SIGNALS / VERB_READ_SIGNALS): name first, then description,
+// whole words, write signals before read signals. Held equal to the pod's
+// source by the "mirror" describe below.
+const WRITE_SIGNALS = ["send", "invite", "post", "create", "write", "update", "delete", "reply", "message", "email", "publish", "comment", "add", "remove", "set", "run", "execute"];
+const READ_SIGNALS = ["search", "list", "get", "fetch", "read", "find", "lookup", "query", "pull"];
+const words = (t: string) => new Set(t.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+const classify = (t: string) => {
+  const w = words(t);
+  if (WRITE_SIGNALS.some((s) => w.has(s))) return "action";
+  if (READ_SIGNALS.some((s) => w.has(s))) return "read";
+  return null;
+};
+const derivedKind = (v: Verb) => classify(v.name) ?? classify(v.description) ?? "action";
+
+describe("stripe capability: reads run, writes are reviewed", () => {
+  it("has reads and writes", () => {
+    expect(reads.length).toBeGreaterThan(10);
+    expect(writes.length).toBeGreaterThan(10);
+  });
+
+  it("every GET verb is read-only (runs at once)", () => {
+    expect(reads.filter((v) => v.metadata?.readOnly !== true).map((v) => v.name)).toEqual([]);
+  });
+
+  it("no write verb is read-only: each stays on the propose grant", () => {
+    expect(writes.filter((v) => v.metadata?.readOnly === true).map((v) => v.name)).toEqual([]);
+  });
+
+  it("a write declares no read intent and the pod files it as an action", () => {
+    expect(writes.filter((v) => v.intent === "list_records" || v.intent === "fetch_record").map((v) => v.name)).toEqual([]);
+    expect(writes.filter((v) => derivedKind(v) !== "action").map((v) => v.name)).toEqual([]);
+    expect(reads.filter((v) => derivedKind(v) !== "read").map((v) => v.name)).toEqual([]);
+  });
+
+  it("covers what the founder asked for: tax settings, tax registrations, payment links, checkout, refunds, payouts", () => {
+    const has = (method: string, path: string) =>
+      writes.some((v) => v.providerSpec.method === method && v.providerSpec.pathTemplate === path);
+    expect(has("POST", "/v1/tax/settings")).toBe(true);
+    expect(has("POST", "/v1/tax/registrations")).toBe(true);
+    expect(has("POST", "/v1/payment_links")).toBe(true);
+    expect(has("POST", "/v1/checkout/sessions")).toBe(true);
+    expect(has("POST", "/v1/refunds")).toBe(true);
+    expect(has("POST", "/v1/payouts")).toBe(true);
+    expect(has("DELETE", "/v1/subscriptions/{{subscriptionId}}")).toBe(true);
+  });
+
+  it("keeps the eight read verbs live pods already run", () => {
+    const names = new Set(reads.map((v) => v.name));
+    for (const n of ["stripe_list_customers", "stripe_get_customer", "stripe_list_charges", "stripe_list_invoices", "stripe_list_subscriptions", "stripe_list_products", "stripe_list_payouts", "stripe_get_balance"])
+      expect(names.has(n), n).toBe(true);
+  });
+});
+
+describe("stripe capability: one host, form bodies, paths under /v1/", () => {
+  const tool = manifest.spec.tools.find((t: { name: string }) => t.name === "stripe");
+
+  it("the tool's host is fixed and its bodies are form-encoded", () => {
+    expect(tool.config.baseUrl).toBe("https://api.stripe.com");
+    expect(tool.config.bodyEncoding).toBe("form");
+    expect(tool.credentialRef).toBe("stripe");
+    expect(verbs.every((v) => v.requires.length === 1 && v.requires[0] === "stripe")).toBe(true);
+  });
+
+  it("every path starts with /v1/; every path parameter is encoded (uri for an id, path for a generic resource path)", () => {
+    for (const v of verbs) {
+      expect(v.providerSpec.pathTemplate.startsWith("/v1/"), v.name).toBe(true);
+      for (const [, name] of v.providerSpec.pathTemplate.matchAll(/\{\{(\w+)\}\}/g)) {
+        const m = v.providerSpec.paramMapping?.[name!];
+        expect(m?.required, `${v.name}.${name}`).toBe(true);
+        expect(["uri", "path"], `${v.name}.${name}`).toContain(m?.encode);
+      }
+    }
+  });
+
+  it("the generic verbs are one per method, each taking a /v1/-relative path", () => {
+    const generic = verbs.filter((v) => v.providerSpec.pathTemplate === "/v1/{{path}}");
+    expect(generic.map((v) => `${v.name} ${v.providerSpec.method}`).sort()).toEqual([
+      "stripe_api_delete DELETE",
+      "stripe_api_read GET",
+      "stripe_api_write POST",
+    ]);
+    for (const v of generic) {
+      expect(v.providerSpec.paramMapping?.path).toEqual({ required: true, encode: "path" });
+      expect(v.providerSpec.bodyFrom).toBe("params");
+    }
+  });
+
+  it("Stripe's own fields travel only through bodyFrom (no body template sending an absent optional as empty)", () => {
+    for (const v of verbs) expect(v.providerSpec.body, v.name).toBeUndefined();
+    for (const v of writes) {
+      expect(v.providerSpec.bodyFrom, v.name).toBeDefined();
+      expect(v.parameters?.[v.providerSpec.bodyFrom!], v.name).toMatch(/^object\??$/);
+    }
+  });
+
+  it("the connect copy names the restricted key and the permissions to grant", () => {
+    const param = manifest.spec.params.find((p: { name: string }) => p.name === "stripeApiKey");
+    expect(param.description).toMatch(/RESTRICTED/);
+    expect(param.description).toMatch(/Write only/);
+    expect(param.description).toMatch(/Tax Settings, Tax Registrations/);
+    expect(manifest.spec.description).toMatch(/ADAPTIVE PRICING/);
+  });
+});
+
+// ── The mirror: the word lists above equal the pod's ─────────────────────────
+// Read from synap-backend's source (a sibling checkout), so a word the pod
+// adds or drops turns this red instead of the classification above drifting
+// unseen. Skips, with the reason logged, when synap-backend is not a sibling.
+const POD_SOURCE = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../synap-backend/packages/api/src/services/capabilities/create-from-definition.ts",
+);
+const hasPodSource = existsSync(POD_SOURCE);
+if (!hasPodSource) console.warn(`[stripe signals mirror] SKIP: ${POD_SOURCE} is absent`);
+
+/** The string literals of `const <name> = [ ... ]` in `src`, in order. */
+function podList(src: string, name: string): string[] {
+  const m = new RegExp(`const ${name}\\s*=\\s*\\[([^\\]]*)\\]`).exec(src);
+  expect(m, `${name} is declared in create-from-definition.ts`).not.toBeNull();
+  return [...m![1]!.matchAll(/"([^"]+)"/g)].map((x) => x[1]!);
+}
+
+describe.skipIf(!hasPodSource)("stripe capability: the word lists mirror the pod's", () => {
+  const src = hasPodSource ? readFileSync(POD_SOURCE, "utf8") : "";
+  it("WRITE_SIGNALS equals VERB_WRITE_SIGNALS", () => {
+    const pod = podList(src, "VERB_WRITE_SIGNALS");
+    expect(pod.length).toBeGreaterThan(5);
+    expect(WRITE_SIGNALS).toEqual(pod);
+  });
+  it("READ_SIGNALS equals VERB_READ_SIGNALS", () => {
+    const pod = podList(src, "VERB_READ_SIGNALS");
+    expect(pod.length).toBeGreaterThan(3);
+    expect(READ_SIGNALS).toEqual(pod);
+  });
+});

package/src/task-intents.test.ts

@@ -0,0 +1,293 @@
+/**
+ * TRIPWIRE: `taskIntents` — the workspace's DECLARED task requirements.
+ *
+ * A template declares the intents (closed vocabulary) it needs to function, so
+ * an agent entering that space can be told what it is FOR without discovering
+ * it by failing. Three failure classes are guarded here, in increasing order of
+ * how quietly they would ship:
+ *
+ *   1. UNKNOWN SLUG — a `taskIntents` value outside the closed vocabulary. Caught
+ *      at authoring time by `validateTemplate`; asserted here over the whole
+ *      corpus so a seed added without ever running the validator still fails.
+ *   2. A TEMPLATE WITH NO DECLARATION — not an error by itself (a workspace
+ *      that needs no external capability declares nothing), but asserted
+ *      against a DERIVED set so a new template cannot silently ship undeclared.
+ *   3. CONTENT STUDIO SPECIFICALLY — the founder-specified reference list, and
+ *      the one template whose exact declaration is pinned as data in this file.
+ *
+ * WHAT IT PROVES: that the declared set is (a) inside the closed vocabulary,
+ * (b) free of duplicates, (c) agreed on by `validateTemplate` — the gate
+ * `build.mjs`, the CP publish path and the CLI actually call — and (d) exactly
+ * the founder-specified list for Content Studio. It REPORTS (never gates) how
+ * much of each declaration is currently backed by an installed pack; see the
+ * long note on that describe block for why a gap is a fact, not an error.
+ *
+ * WHAT IT DOES NOT PROVE: that any declared intent is the RIGHT requirement for
+ * a workspace — that is a judgement, not a derivable fact.
+ *
+ * ⚠️ THE SCAN IS DERIVED, NOT HAND-LISTED. The template set comes from
+ * `readYamlTemplates()` (the same reader `build.mjs` uses), so a template added
+ * tomorrow joins this scan BY EXISTING. A hand-written array of slugs is how a
+ * guard ends up holding only the entries that were already correct.
+ *
+ * ⚠️ NON-VACUITY IS ASSERTED EXPLICITLY, twice: the corpus must be non-empty,
+ * and the vocabulary must be a real closed set. A glob that matches zero files
+ * passes every "no unknown intent" assertion there is.
+ */
+
+import { describe, expect, it } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CAPABILITY_INTENTS } from "@synap-core/types/capability-intents";
+import { validateTemplate } from "./validate.js";
+import type { WorkspaceYaml } from "./types.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// The reference list the founder specified for Content Studio, now carried by
+// Content OS (content-studio retired into it, 2026-11-03). Pinned HERE as
+// data so the test states what "correct" is rather than reading it from the
+// file it is meant to police.
+const CONTENT_OS_INTENTS = [
+  "generate_media",
+  "manage_file",
+  "capture_into_pod",
+  "search_external",
+];
+
+// The catalog's own capability manifests (the CP keeps a byte-checked mirror
+// until its pin bump; see the CP's catalog-mirror.tripwire.test.ts).
+const CAPABILITY_TEMPLATES_DIR = join(HERE, "../capabilities");
+
+/** The closed vocabulary as a set, plus a readable unknown-value report. */
+const VOCABULARY = new Set<string>(CAPABILITY_INTENTS);
+
+/**
+ * The intents a capability pack actually provides, from its declared verb
+ * intents. Reads the catalog manifest (its `spec` is the CP seed JSON, kept
+ * identical by the mirror tripwire) — so "declared" here means what the seeder
+ * will really install.
+ *
+ * Returns null for a pack this checkout cannot read, which callers treat as
+ * "cannot check" rather than "provides nothing" — an unresolvable pack must not
+ * silently pass a subset assertion.
+ */
+function providedIntents(templateKey: string): Set<string> | null {
+  const file = join(CAPABILITY_TEMPLATES_DIR, `${templateKey}.capability.json`);
+  if (!existsSync(file)) return null;
+  const json = JSON.parse(readFileSync(file, "utf-8")) as unknown;
+  const intents = new Set<string>();
+  const walk = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(walk);
+      return;
+    }
+    if (node && typeof node === "object") {
+      for (const [key, value] of Object.entries(node)) {
+        if (key === "intent" && typeof value === "string") intents.add(value);
+        walk(value);
+      }
+    }
+  };
+  walk(json);
+  return intents;
+}
+
+/** Load the corpus through the ONE reader `build.mjs` uses. */
+function loadTemplates(): Array<{ file: string; slug: string; data: WorkspaceYaml }> {
+  // Imported lazily so this module's import cost is paid inside the tests, and
+  // so a YAML parse error surfaces as a test failure with context.
+  const { readYamlTemplates } = require("./generate.mjs") as {
+    readYamlTemplates: () => Array<{ file: string; slug: string; data: unknown }>;
+  };
+  return readYamlTemplates() as Array<{
+    file: string;
+    slug: string;
+    data: WorkspaceYaml;
+  }>;
+}
+
+const TEMPLATES = loadTemplates();
+const DECLARED = TEMPLATES.filter((t) => Array.isArray(t.data.taskIntents));
+
+describe("taskIntents — every declared slug is a known intent", () => {
+  it("non-vacuity: the scan actually found templates and a real vocabulary", () => {
+    // Without these, "no unknown intent" passes on an empty set.
+    expect(TEMPLATES.length).toBeGreaterThanOrEqual(10);
+    expect(CAPABILITY_INTENTS.length).toBeGreaterThanOrEqual(13);
+    expect(CAPABILITY_INTENTS.length).toBe(new Set(CAPABILITY_INTENTS).size);
+    expect(DECLARED.length).toBeGreaterThanOrEqual(5);
+    // The scan can still see a literal it hunts: prove the reader picks up a
+    // value rather than normalising it away.
+    expect(CONTENT_OS_INTENTS.filter((i) => VOCABULARY.has(i))).toHaveLength(
+      CONTENT_OS_INTENTS.length
+    );
+  });
+
+  it("no template declares an intent outside the closed vocabulary", () => {
+    const offenders: string[] = [];
+    for (const t of DECLARED) {
+      for (const intent of t.data.taskIntents as string[]) {
+        if (!VOCABULARY.has(intent)) {
+          offenders.push(`${t.file}: "${intent}"`);
+        }
+      }
+    }
+    expect(
+      offenders,
+      `Unknown taskIntents (closed vocabulary: ${CAPABILITY_INTENTS.join(", ")}):`
+    ).toEqual([]);
+  });
+
+  it("no template declares a duplicate intent", () => {
+    const offenders: string[] = [];
+    for (const t of DECLARED) {
+      const list = t.data.taskIntents as string[];
+      const dupes = list.filter((v, i) => list.indexOf(v) !== i);
+      if (dupes.length) offenders.push(`${t.file}: ${[...new Set(dupes)].join(", ")}`);
+    }
+    expect(offenders, "taskIntents must not repeat an intent").toEqual([]);
+  });
+
+  it("validateTemplate agrees with this scan (the authoring-time gate fires)", () => {
+    // The scanner above reads raw YAML; the validator is what build.mjs, the
+    // CP publish path and the CLI actually call. Assert the two cannot diverge
+    // on the case that matters — an unknown slug must be an ERROR there, not
+    // merely a warning this file swallowed.
+    const withUnknown: WorkspaceYaml = {
+      ...TEMPLATES[0].data,
+      taskIntents: ["generate_media", "definitely_not_an_intent"],
+    };
+    const result = validateTemplate(withUnknown);
+    const rule = result.errors.filter((e) => e.rule === "task-intent-unknown");
+    expect(rule).toHaveLength(1);
+    expect(rule[0].path).toContain("taskIntents");
+    // And a fully-valid list produces no taskIntents error at all.
+    const ok = validateTemplate({
+      ...TEMPLATES[0].data,
+      taskIntents: [...CONTENT_OS_INTENTS],
+    });
+    expect(ok.errors.filter((e) => e.rule.startsWith("task-intent"))).toEqual([]);
+  });
+});
+
+describe("taskIntents — declared requirements vs. what is installed today", () => {
+  /**
+   * ⚠️ THIS IS A REPORT, NOT A GATE — deliberately, and the reason is the point
+   * of the field.
+   *
+   * An earlier draft asserted `taskIntents ⊆ intents(provided by integrations)`
+   * as a hard failure. It went red immediately and was WRONG: the founder's
+   * reference declaration for Content Studio is
+   * `[generate_media, manage_file, capture_into_pod, search_external]`, while
+   * at the time its only installed pack (`remotion`, since retired) provided
+   * just `generate_media` — and today it ships NO pack at all (HyperFrames
+   * runs on the user's own agent, plan D9). A subset rule would have forbidden
+   * the specification itself.
+   *
+   * `taskIntents` is what a workspace NEEDS TO FUNCTION, not a snapshot of what
+   * it currently has. Declaring an intent ahead of the pack that serves it is
+   * the requirement doing its job — it is what a later install, or a Phase-3
+   * match, is checked against. So a gap is a FACT to surface, not an error to
+   * reject.
+   *
+   * What this therefore does NOT prove: that every requirement is satisfiable.
+   * A template could declare an intent nothing can ever provide, and this stays
+   * green. Only a human (or the Phase-3 resolver) can say a requirement is
+   * met; a structural check can only say whether it is currently backed.
+   *
+   * It DOES prove the reporting machinery works: the corpus is walked, packs are
+   * resolved for real, and an unresolvable pack is reported rather than counted
+   * as providing nothing — the "silently passing" failure this file exists to
+   * prevent.
+   */
+  it("reports each declaration's backing and its gaps", () => {
+    interface Coverage {
+      file: string;
+      declared: number;
+      backed: number;
+      gaps: string[];
+      unreadable: string[];
+    }
+    const coverage: Coverage[] = [];
+    for (const t of DECLARED) {
+      const installed = t.data.integrations ?? [];
+      const provided = new Set<string>();
+      const unreadable: string[] = [];
+      for (const integration of installed) {
+        const intents = providedIntents(integration.templateKey);
+        if (intents === null) {
+          unreadable.push(integration.templateKey);
+          continue;
+        }
+        intents.forEach((i) => provided.add(i));
+      }
+      const declared = t.data.taskIntents as string[];
+      coverage.push({
+        file: t.file,
+        declared: declared.length,
+        backed: declared.filter((i) => provided.has(i)).length,
+        gaps: declared.filter((i) => !provided.has(i)),
+        unreadable,
+      });
+    }
+
+    // Non-vacuity: the report is real — every declared template was walked and
+    // at least one pack resolved, so the gap list is measured, not empty-by-
+    // construction.
+    expect(coverage.length).toBeGreaterThanOrEqual(5);
+    const resolvable = coverage.filter((c) => c.unreadable.length < (c.declared ? 1 : 0));
+    expect(
+      coverage.some((c) => c.backed > 0),
+      "no declared intent matched any installed pack — the derivation is broken"
+    ).toBe(true);
+
+    // The only hard assertion: a template cannot claim MORE intents than it
+    // declared. (Trivially true by construction — kept as the shape check that
+    // fails if the coverage walk ever stops being total.)
+    for (const c of coverage) {
+      expect(c.backed).toBeLessThanOrEqual(c.declared);
+    }
+
+    if (process.env.SYNAP_REPORT_TASK_INTENTS === "1") {
+      for (const c of coverage) {
+        console.warn(
+          `[taskIntents] ${c.file}: ${c.backed}/${c.declared} backed` +
+            (c.gaps.length ? ` · gaps: ${c.gaps.join(", ")}` : "") +
+            (c.unreadable.length
+              ? ` · unreadable packs: ${c.unreadable.join(", ")}`
+              : "")
+        );
+      }
+    }
+  });
+});
+
+// Content OS carries the founder-specified intents over from the retired
+// content-studio (retired.yaml, 2026-11-03), with the video pipeline they describe.
+describe("taskIntents — Content OS is the reference declaration", () => {
+  it("declares exactly the founder-specified intents", () => {
+    const contentOs = TEMPLATES.find((t) => t.slug === "content-os");
+    expect(contentOs, "content-os template not found in src/*.yaml").toBeTruthy();
+    expect(contentOs?.data.taskIntents, "content-os must declare taskIntents")
+      .toEqual(CONTENT_OS_INTENTS);
+  });
+
+  it("every one of them is a real intent", () => {
+    for (const intent of CONTENT_OS_INTENTS) {
+      expect(VOCABULARY.has(intent), `"${intent}" is not a known intent`).toBe(
+        true
+      );
+    }
+  });
+
+  it("and the template itself validates", () => {
+    const contentOs = TEMPLATES.find((t) => t.slug === "content-os");
+    const result = validateTemplate(contentOs!.data);
+    expect(
+      result.errors.filter((e) => e.rule.startsWith("task-intent")),
+      "content-os failed taskIntents validation"
+    ).toEqual([]);
+  });
+});