@synap-core/workspace-templates 0.11.0 → 0.12.0

package/src/civic-france.yaml

@@ -0,0 +1,102 @@
+# France civic open-data research overlay — STUB (enhance later)
+#
+# Thin overlay that composes onto research-base for investigating French public
+# data (open data / Licence Ouverte). NOT a government product, NOT a marketplace
+# civic-tech app. Private workspace template only.
+#
+# Data access: consume official APIs only — data.gouv.fr, api.gouv.fr, PISTE.
+# Never scrape HTML. Do not invent a public pod host or resource_shares.
+# No automations that fetch the web in this stub.
+
+meta:
+  slug: civic-france
+  domain: knowledge
+  name: France Civic Research
+  description: Overlay for investigating French public data (open data / Licence Ouverte). Composes onto Research. Not a government product — a private research stub.
+  icon: landmark
+  color: "#1D4ED8"
+  tags: [research, civic, france, open-data, licence-ouverte]
+  isPublic: false
+
+workspace:
+  name: Research
+  description: Adds a French civic open-data lens onto the Research substrate — track public datasets consulted during investigations.
+  subtype: research-base
+
+# Layer additively onto the research-base workspace (no second workspace).
+# Visibility and capabilities OMITTED so the base Research workspace keeps its own.
+dependencies:
+  - slug: research-base
+    relation: compose
+    reason: France civic research is a research method — it needs the Research substrate (question / research / source) to work over.
+
+profiles:
+  # Slugs this overlay reuses from research-base — declared for the per-file
+  # validator (base owns their full schema; the applier skips already-existing
+  # properties). Mirror research-decision's reuse pattern.
+  - slug: question
+    displayName: Question
+    icon: help-circle
+    color: blue
+    description: An open question driving a civic-data investigation.
+    properties:
+      - slug: questionStatus
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues: [open, exploring, answered, abandoned]
+        constraints: { defaultValue: open }
+
+  - slug: research
+    displayName: Research
+    icon: microscope
+    color: violet
+    description: An investigation into French public data — sources, findings, conclusion.
+    properties:
+      - slug: researchStatus
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues: [ongoing, concluded, abandoned]
+        constraints: { defaultValue: ongoing }
+
+  - slug: source
+    displayName: Source
+    icon: file-text
+    color: cyan
+    description: Anything consulted — API payload, dataset page, decree, report.
+    properties:
+      - slug: url
+        label: URL
+        valueType: string
+        inputType: url
+
+  # Workspace-owned catalog entry for a French public dataset (thin stub).
+  - slug: public_dataset
+    displayName: Public dataset
+    icon: database
+    color: blue
+    description: A French public dataset consulted via official open-data APIs (data.gouv.fr / api.gouv.fr / PISTE) — never scraped HTML.
+    scope: WORKSPACE
+    properties:
+      - slug: sourceUrl
+        label: Source URL
+        valueType: string
+        inputType: url
+      - slug: license
+        label: License
+        valueType: string
+        inputType: text
+      - slug: publisher
+        label: Publisher
+        valueType: string
+        inputType: text
+
+views:
+  - name: Public datasets
+    slug: civic-france-public-datasets
+    type: table
+    scopeProfileSlug: public_dataset
+    description: French public datasets tracked in this research workspace.
+    config:
+      columns: [title, publisher, license, sourceUrl]

package/src/dist-freshness.test.ts

@@ -0,0 +1,97 @@
+/**
+ * FRESHNESS GATE for the BUILT `dist/` artifact.
+ *
+ * WHY (read before deleting):
+ * `templates-freshness.test.ts` (sibling file) proves `src/templates.ts`
+ * matches `src/*.yaml`. That is necessary but not sufficient: `dist/` — built
+ * by `tsup` from `src/templates.ts` — is what `synap-backend` and every other
+ * consumer actually imports as the published `@synap-core/workspace-templates`
+ * npm dependency (see this package's `exports` field: `dist/index.js`).
+ * Nothing regenerates `dist/` automatically, and it is committed independently
+ * of `src/templates.ts`. A YAML edit can reach `src/templates.ts` (green on
+ * the sibling test) and NOT reach `dist/` — the sibling test stays green while
+ * the backend keeps reading stale data, because it never looks at `dist/` at
+ * all. That gap is exactly what happened on 2026-09-05.
+ *
+ * This test closes it by importing the BUILT `dist/index.js` module (not
+ * re-parsing its text — a bundled/minified file has no byte-for-byte
+ * relationship to `src/templates.ts`) and asserting its exported
+ * `WORKSPACE_TEMPLATES` deep-equals what `src/*.yaml` renders to right now.
+ * That is the same non-vacuous shape as the sibling test: it re-derives the
+ * expected value from the YAML source on every run rather than trusting any
+ * stored marker, and it asserts the corpus is non-empty so a broken import
+ * can't silently compare `{}` to `{}`.
+ */
+
+import { describe, expect, it } from "vitest";
+import { readYamlTemplates } from "./generate.mjs";
+
+const FIX_COMMAND =
+  "cd synap-app/packages/workspace-templates && pnpm build";
+
+describe("dist/ freshness", () => {
+  it("dist/index.js's WORKSPACE_TEMPLATES matches what src/*.yaml renders to", async () => {
+    const expectedEntries = readYamlTemplates().map((t) => [t.slug, t.data]);
+    const expected = Object.fromEntries(expectedEntries);
+
+    // Guard against a vacuous pass: if the YAML corpus itself came back empty
+    // (a broken readdir, an emptied src/ directory), an empty-vs-empty
+    // comparison below would prove nothing. Fail loudly instead.
+    if (expectedEntries.length === 0) {
+      throw new Error(
+        "readYamlTemplates() returned zero templates — src/*.yaml did not " +
+          "parse. This test cannot verify dist/ freshness against an empty " +
+          "expected corpus; fix the YAML read before trusting this gate.",
+      );
+    }
+
+    let dist: { WORKSPACE_TEMPLATES?: Record<string, unknown> };
+    try {
+      // dist/index.js is the BUILT artifact — import it live so we're
+      // comparing against exactly what a consumer (synap-backend, the CLI)
+      // resolves via this package's `exports` field, not a re-parse of its
+      // source text.
+      dist = await import("../dist/index.js");
+    } catch (err) {
+      throw new Error(
+        [
+          "",
+          "❌ dist/index.js could not be imported — it is missing or fails to load.",
+          "",
+          `   FIX — build it:`,
+          `     ${FIX_COMMAND}`,
+          "",
+          `   (original error: ${(err as Error).message})`,
+          "",
+        ].join("\n"),
+      );
+    }
+
+    const actual = dist.WORKSPACE_TEMPLATES;
+    if (!actual || Object.keys(actual).length === 0) {
+      throw new Error(
+        "dist/index.js loaded but exported no WORKSPACE_TEMPLATES (or an " +
+          `empty object) — it is stale or broken.\n\n   FIX:\n     ${FIX_COMMAND}\n`,
+      );
+    }
+
+    if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+      throw new Error(
+        [
+          "",
+          "❌ dist/index.js is STALE — its WORKSPACE_TEMPLATES no longer matches",
+          "   what src/*.yaml renders to. synap-backend and every other consumer",
+          "   resolve this package to dist/, not src/, so a stale dist/ means the",
+          "   backend is reading templates that no longer exist on disk — even",
+          "   though src/templates.ts (and templates-freshness.test.ts) are fresh.",
+          "",
+          "   FIX — rebuild and commit the result:",
+          `     ${FIX_COMMAND}`,
+          "",
+        ].join("\n"),
+      );
+    }
+
+    expect(actual).toEqual(expected);
+  });
+});

package/src/foundation.yaml

@@ -528,6 +528,68 @@ profiles:
         valueType: string
         inputType: textarea
 
+  # ── Roles the BUSINESS MODEL needs, and why they live here ─────────────────
+  # `porteur` and `funder` are hats, not kinds: the same person entity is a
+  # porteur of one venture and a funder of another, and the hat is revocable
+  # while the person is not. They are declared HERE because foundation.yaml is
+  # the shared-role SSOT (`shared-role-ssot.test.ts` derives the guarded
+  # vocabulary from this file) — declaring them in business-model.yaml instead
+  # would fork a second identity for a hat the whole pod refers to.
+  - slug: porteur
+    displayName: Porteur
+    icon: user-check
+    color: amber
+    description: The person carrying a venture — the one whose commitment, skills, and constraints the model actually rests on. Distinct from `client` (who pays) and `partner` (who collaborates).
+    scope: shared
+    profileKind: role
+    applicableKinds:
+      - person
+    properties:
+      - slug: brings
+        label: What They Bring
+        valueType: string
+        inputType: textarea
+        description: The specific competence, network, capital, or legitimacy this person contributes that the model depends on.
+      - slug: commitmentLevel
+        label: Commitment
+        valueType: string
+        inputType: select
+        enumValues: [full-time, part-time, advisory, intermittent]
+      - slug: constraints
+        label: Constraints
+        valueType: string
+        inputType: textarea
+        description: What limits this porteur — time, cash runway, geography, non-compete, family. A model that ignores these is fiction.
+  - slug: funder
+    displayName: Funder
+    icon: banknote
+    color: green
+    description: A source of non-revenue money or subsidy — a bank, a public scheme, an investor, a grantor. A hat worn by a company or a person, never a kind of its own.
+    scope: shared
+    profileKind: role
+    applicableKinds:
+      - company
+      - person
+    properties:
+      - slug: fundingType
+        label: Funding Type
+        valueType: string
+        inputType: select
+        enumValues: [grant, subsidy, loan, equity, guarantee, prize, other]
+      - slug: amountCommitted
+        label: Amount Committed
+        valueType: number
+        inputType: number
+      - slug: eligibilityConditions
+        label: Eligibility Conditions
+        valueType: string
+        inputType: textarea
+        description: The conditions the venture must satisfy to keep this money. These are the constraints most often discovered too late.
+      - slug: decisionDate
+        label: Decision Date
+        valueType: date
+        inputType: date
+
 views:
   - name: Mission & Vision
     slug: mission-vision

package/src/grants.yaml

@@ -1020,15 +1020,26 @@ playbooks:
     params:
       - { name: contract, type: entity, profileSlug: contract, label: Engagement, required: true }
       - { name: grantProgram, type: entity, profileSlug: grant-program, label: Grant Program, required: true }
+    # A grant pursuit is an ENGAGEMENT with a before/during/after lifecycle that
+    # outlives any one working session (drafting, then weeks of waiting on the
+    # funder, then tranche delivery), so this is a PROJECT template: its stages
+    # coordinate a long-running container rather than script one focus session.
+    scope: project
     # Generic stages, mapped onto grant_submission's own stage/status/outcome +
     # tranche vocab so the run can maintain the card as it advances.
+    # `category` is the closed rollup bucket (backlog|planned|started|paused|
+    # completed|canceled), chosen by MEANING: `identify` is pre-commitment
+    # scoping (planned); `awaiting` is genuinely blocked on the funder (paused);
+    # `awarded` stays `started` because delivery follows an award — a rejected
+    # pursuit's terminality lives on the submission's own `outcome` field, not
+    # here.
     stages:
-      - { key: identify, name: Identify, description: "Understand the project and which of the program's submission tracks fit — before any writing.", goal: "A clear project understanding and the fitting submission track; submission stage = scope." }
-      - { key: draft, name: Draft, description: "Write the abstract, then the full proposal, from the client's real material.", goal: "Abstract then full proposal drafted; submission stage abstract → build with body fields filled." }
-      - { key: submit, name: Submit, description: "Finalize against the program deadline and submit the application.", goal: "Application submitted on time; submission stage = awaiting-results." }
-      - { key: awaiting, name: Awaiting, description: "Track the decision and keep the client status current.", goal: "Submission status reflects where the decision stands (in-review / waiting-client / needs-document / blocked)." }
-      - { key: awarded, name: Awarded, description: "Record the funder's decision and the awarded amount.", goal: "Submission outcome set (awarded / rejected / partial) with the awarded amount." }
-      - { key: delivering, name: Delivering, description: "Work the program's tranche model — ship and record each tranche.", goal: "Tranche deliverables filled and trancheCompletion updated as milestones ship." }
+      - { key: identify, name: Identify, category: planned, description: "Understand the project and which of the program's submission tracks fit — before any writing.", goal: "A clear project understanding and the fitting submission track; submission stage = scope." }
+      - { key: draft, name: Draft, category: started, description: "Write the abstract, then the full proposal, from the client's real material.", goal: "Abstract then full proposal drafted; submission stage abstract → build with body fields filled." }
+      - { key: submit, name: Submit, category: started, description: "Finalize against the program deadline and submit the application.", goal: "Application submitted on time; submission stage = awaiting-results." }
+      - { key: awaiting, name: Awaiting, category: paused, description: "Track the decision and keep the client status current.", goal: "Submission status reflects where the decision stands (in-review / waiting-client / needs-document / blocked)." }
+      - { key: awarded, name: Awarded, category: started, description: "Record the funder's decision and the awarded amount.", goal: "Submission outcome set (awarded / rejected / partial) with the awarded amount." }
+      - { key: delivering, name: Delivering, category: started, description: "Work the program's tranche model — ship and record each tranche.", goal: "Tranche deliverables filled and trancheCompletion updated as milestones ship." }
     executor: is-agent
     grants:
       - entity.create

package/src/life-os.yaml

@@ -731,6 +731,16 @@ profiles:
         inputType: text
 
 views:
+  # Knowledge is the pod-owned, validated-memory kind. Notes remain the
+  # workspace's capture inbox; this view deliberately reuses the system
+  # contract instead of recreating a competing knowledge schema here.
+  - name: Knowledge
+    slug: knowledge
+    type: table
+    scopeProfileSlug: knowledge
+    description: Validated insights and cautions, with their long-form context and evidence kept in the graph.
+    config:
+      columns: [title, knowledgeForm]
   - name: All Notes
     type: table
     scopeProfileSlug: note
@@ -1160,6 +1170,10 @@ layout:
       appId: dashboard
       label: Brain Home
       icon: Home
+    - kind: profile
+      profileSlug: knowledge
+      label: Knowledge
+      icon: Brain
     - kind: profile
       profileSlug: note
       label: Notes

package/src/seed-obligation.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Seed-obligation guard.
+ *
+ * THE BUG THIS EXISTS TO STOP, stated plainly: the applier has supported
+ * `seedEntities` and `suggestedRelations` since
+ * `create-workspace-from-definition.ts` learned to read them, and for 31 of 31
+ * shipped templates that support was exercised exactly zero times. The
+ * observable result is a workspace that installs 15 views over 0 entities —
+ * every board empty, every chart blank, and the user left to guess what the
+ * pack was for. Two real workspaces in the field reproduced this identically,
+ * which is the signature of a template defect rather than user behaviour.
+ *
+ * The rule: a template that ships VIEWS over profiles it OWNS must also ship
+ * at least one seed entity, so the workspace opens with something in it.
+ *
+ * The escape hatch is deliberate and narrow. `SEEDLESS_BY_DESIGN` lists the
+ * templates that predate this guard, each with the reason it is still empty.
+ * Adding a line there is legal; adding one silently is not, because the list is
+ * asserted to be exact — a template that gains seeds must leave the list in the
+ * same commit. That is what turns this from a lint into a shrinking backlog.
+ *
+ * What a seed is NOT: filler. Seeding three fake companies teaches nothing and
+ * gets deleted in the first minute. Seed the QUESTIONS, the stages, the
+ * checklist — the reusable part of the method. See `business-model.yaml`, which
+ * seeds the nine interrogations rather than an example business.
+ */
+
+import { describe, expect, it } from "vitest";
+import { WORKSPACE_TEMPLATES } from "./templates.js";
+import type { WorkspaceYaml } from "./types.js";
+
+/**
+ * Templates that ship views over their own profiles and NO seed entities.
+ *
+ * Every entry is a workspace that currently installs empty. Keep the reason
+ * honest — "not done yet" is a valid reason and a useful one, because it reads
+ * as debt instead of as a decision.
+ */
+const SEEDLESS_BY_DESIGN: Record<string, string> = {
+  "agent-fleet": "Pre-dates this guard. Fleet contents are per-pod; needs a seed pass.",
+  base: "Pod substrate, not a workspace a user opens. Seeds would land in every workspace.",
+  "blockchain-ecosystem": "Pre-dates this guard; needs a seed pass.",
+  "brand-library": "Pre-dates this guard; brand assets are inherently per-company.",
+  "builder-workspace": "Pre-dates this guard; needs a seed pass.",
+  "business-developer": "Pre-dates this guard; overlay on CRM, seeds belong on the base.",
+  "civic-france": "Pre-dates this guard; needs a seed pass.",
+  communication: "Pre-dates this guard; needs a seed pass.",
+  "content-os": "Pre-dates this guard; needs a seed pass.",
+  "content-studio": "Pre-dates this guard; needs a seed pass.",
+  crm: "Pre-dates this guard; needs a seed pass.",
+  "dev-dashboard": "Pre-dates this guard; needs a seed pass.",
+  ecosystem: "Pre-dates this guard; needs a seed pass.",
+  "enterprise-os": "Pre-dates this guard; needs a seed pass.",
+  finance:
+    "Pre-dates this guard. Confirmed empty in the field: 15 views, 6 profiles, 0 entities. First candidate for a seed pass — a chart of accounts and a metric set are genuinely reusable.",
+  foundation:
+    "Pre-dates this guard. Strategic DNA is company-specific, but the INTERROGATION is not — see business-model.yaml, which seeds it as an overlay.",
+  grants: "Pre-dates this guard; needs a seed pass.",
+  hr: "Pre-dates this guard; needs a seed pass.",
+  "internal-runbook": "Pre-dates this guard; needs a seed pass.",
+  legal: "Pre-dates this guard; needs a seed pass.",
+  "life-os": "Pre-dates this guard; needs a seed pass.",
+  "marketing-campaign": "Pre-dates this guard; needs a seed pass.",
+  "meetings-knowledge": "Pre-dates this guard; needs a seed pass.",
+  networking: "Pre-dates this guard; needs a seed pass.",
+  operations: "Pre-dates this guard; needs a seed pass.",
+  "outreach-comms": "Pre-dates this guard; needs a seed pass.",
+  "project-management": "Pre-dates this guard; needs a seed pass.",
+  "research-base":
+    "Pre-dates this guard. Radar reproduced the empty-workspace pathology on top of this substrate; seed pass wanted.",
+  "research-decision": "Overlay on research-base; the method is a playbook, not entities.",
+  social: "Pre-dates this guard; needs a seed pass.",
+  "the-arch": "Pre-dates this guard; needs a seed pass.",
+};
+
+/** Slugs of profiles this template declares itself (owned or re-declared). */
+function declaredProfileSlugs(tpl: WorkspaceYaml): Set<string> {
+  const profiles = (tpl as { profiles?: Array<{ slug?: string }> }).profiles ?? [];
+  return new Set(profiles.map((p) => p.slug).filter((s): s is string => Boolean(s)));
+}
+
+/** Views whose scope is a profile the template declares. */
+function viewsOverOwnProfiles(tpl: WorkspaceYaml): number {
+  const declared = declaredProfileSlugs(tpl);
+  const views =
+    (tpl as { views?: Array<{ scopeProfileSlug?: string; scopeProfileSlugs?: string[] }> })
+      .views ?? [];
+  return views.filter((v) => {
+    const scoped = [v.scopeProfileSlug, ...(v.scopeProfileSlugs ?? [])].filter(Boolean);
+    return scoped.some((s) => declared.has(s as string));
+  }).length;
+}
+
+function seedCount(tpl: WorkspaceYaml): number {
+  const t = tpl as {
+    seedEntities?: unknown[];
+    suggestedEntities?: unknown[];
+  };
+  return (t.seedEntities?.length ?? 0) + (t.suggestedEntities?.length ?? 0);
+}
+
+const slugOf = (slug: string, tpl: WorkspaceYaml) =>
+  (tpl as { meta?: { slug?: string } }).meta?.slug ?? slug;
+
+describe("workspace-templates — seed obligation (corpus)", () => {
+  it("every template with views over its own profiles ships seeds, or is declared seedless", () => {
+    const undeclared: string[] = [];
+
+    for (const [key, tpl] of Object.entries(WORKSPACE_TEMPLATES)) {
+      const slug = slugOf(key, tpl);
+      if (viewsOverOwnProfiles(tpl) === 0) continue;
+      if (seedCount(tpl) > 0) continue;
+      if (slug in SEEDLESS_BY_DESIGN) continue;
+      undeclared.push(
+        `${slug}: ships ${viewsOverOwnProfiles(tpl)} view(s) over its own profiles and 0 seed entities. ` +
+          `Add seedEntities (seed the METHOD, not fake data), or add "${slug}" to SEEDLESS_BY_DESIGN with a reason.`
+      );
+    }
+
+    expect(
+      undeclared,
+      `Templates would install a workspace of empty views:\n  - ${undeclared.join("\n  - ")}`
+    ).toEqual([]);
+  });
+
+  it("the seedless allowlist is exact — a template that gains seeds must leave it", () => {
+    const stale: string[] = [];
+
+    for (const [key, tpl] of Object.entries(WORKSPACE_TEMPLATES)) {
+      const slug = slugOf(key, tpl);
+      if (!(slug in SEEDLESS_BY_DESIGN)) continue;
+      if (seedCount(tpl) > 0) {
+        stale.push(`${slug}: now seeds ${seedCount(tpl)} entity(ies) — remove it from SEEDLESS_BY_DESIGN`);
+      }
+    }
+
+    const corpusSlugs = new Set(
+      Object.entries(WORKSPACE_TEMPLATES).map(([key, tpl]) => slugOf(key, tpl))
+    );
+    for (const slug of Object.keys(SEEDLESS_BY_DESIGN)) {
+      if (!corpusSlugs.has(slug)) {
+        stale.push(`${slug}: listed in SEEDLESS_BY_DESIGN but no such template exists`);
+      }
+    }
+
+    expect(stale, `Stale seedless allowlist:\n  - ${stale.join("\n  - ")}`).toEqual([]);
+  });
+
+  it("every seeded relation names entities seeded in the same template", () => {
+    // A suggested relation whose ref matches no seeded title fails SILENTLY at
+    // apply time — the workspace installs, the edge does not, and nothing says
+    // so. Catch the typo here instead of in a user's pod.
+    const dangling: string[] = [];
+
+    for (const [key, tpl] of Object.entries(WORKSPACE_TEMPLATES)) {
+      const slug = slugOf(key, tpl);
+      const t = tpl as {
+        seedEntities?: Array<{ title?: string }>;
+        suggestedEntities?: Array<{ title?: string }>;
+        suggestedRelations?: Array<{ sourceRef?: string; targetRef?: string; type?: string }>;
+      };
+      const rels = t.suggestedRelations ?? [];
+      if (rels.length === 0) continue;
+
+      const titles = new Set(
+        [...(t.seedEntities ?? []), ...(t.suggestedEntities ?? [])]
+          .map((e) => e.title)
+          .filter((x): x is string => Boolean(x))
+      );
+
+      for (const rel of rels) {
+        for (const ref of [rel.sourceRef, rel.targetRef]) {
+          if (!ref || titles.has(ref)) continue;
+          dangling.push(`${slug}: relation "${rel.type}" references unseeded entity "${ref}"`);
+        }
+      }
+    }
+
+    expect(dangling, `Dangling seeded relations:\n  - ${dangling.join("\n  - ")}`).toEqual([]);
+  });
+});

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

@@ -122,8 +122,11 @@ describe("workspace-templates — shared ecosystem role SSOT (corpus)", () => {
     // Guards the derivation itself: if foundation ever stops declaring its
     // shared roles, rule (a) would silently guard nothing.
     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.
     expect([...SHARED_ROLE_SLUGS].sort()).toEqual(
-      ["churned", "client", "lead", "partner", "sponsor"]
+      ["churned", "client", "funder", "lead", "partner", "porteur", "sponsor"]
     );
   });