@synap-core/workspace-templates 0.12.0 → 0.24.0

package/src/lifecycle-declarations.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Lifecycle DECLARATIONS (work model L1) — the catalog declares each kind's and
+ * role's ONE lifecycle, so no board, pipeline or governance rung has to guess
+ * what a status means from its name.
+ *
+ * Pinned:
+ *  - the validator's category list equals `@synap-core/types/lifecycle`;
+ *  - the mandatory declarations (deal, lead, client, the post that Produce
+ *    Content drives) carry the founder-confirmed categories;
+ *  - COVERAGE, derived: every non-system kind a playbook moves through
+ *    `subjectProfile.statusProperty` declares that property as its lifecycle;
+ *  - `humanOnly` = the binding playbooks' `humanOnlyStatuses` that stop, pause
+ *    or end the thing (category paused/done/lost) — never an invented one —
+ *    plus the exact ledger of founder-decided ACTIVE person-only options
+ *    (`PERSON_ONLY_ACTIVE`);
+ *  - the whole corpus validates with zero `lifecycle-*` errors, and each rule
+ *    fires on a broken clone (self-checks).
+ */
+import { describe, expect, it } from "vitest";
+import { LIFECYCLE_CATEGORIES as TYPES_CATEGORIES } from "@synap-core/types/lifecycle";
+import { LIFECYCLE_CATEGORIES, SYSTEM_PROFILES, validateTemplate } from "./validate.js";
+import type { TemplateLifecycle, WorkspaceYaml } from "./types.js";
+import { readYamlTemplates } from "./generate.mjs";
+
+const corpus = readYamlTemplates().map((t) => t.data as WorkspaceYaml);
+const tpl = (slug: string) => corpus.find((t) => t.meta.slug === slug)!;
+const lifecycleOf = (t: WorkspaceYaml, profile: string): TemplateLifecycle | undefined =>
+  t.profiles.find((p) => p.slug === profile)?.lifecycle;
+const categories = (lc: TemplateLifecycle | undefined) =>
+  Object.fromEntries((lc?.options ?? []).map((o) => [o.key, o.category]));
+const lifecycleErrors = (t: WorkspaceYaml, c: WorkspaceYaml[] = corpus) =>
+  validateTemplate(t, { corpus: c }).errors.filter((e) => e.rule.startsWith("lifecycle-"));
+
+describe("lifecycle declarations — the category vocabulary", () => {
+  it("the validator's mirror equals @synap-core/types/lifecycle", () => {
+    expect([...LIFECYCLE_CATEGORIES]).toEqual([...TYPES_CATEGORIES]);
+  });
+});
+
+describe("lifecycle declarations — the mandatory four", () => {
+  it("deal = commercialStage; lost is a person's call", () => {
+    for (const slug of ["crm"]) {
+      const lc = lifecycleOf(tpl(slug), "deal");
+      expect(lc?.property, slug).toBe("commercialStage");
+      expect(categories(lc)).toEqual({ draft: "open", proposed: "active", negotiating: "active", won: "done", lost: "lost" });
+      expect(lc?.options.filter((o) => o.humanOnly).map((o) => o.key)).toEqual(["lost"]);
+    }
+  });
+
+  it("lead = leadStage with the W15 categories", () => {
+    const lc = lifecycleOf(tpl("foundation"), "lead");
+    expect(lc?.property).toBe("leadStage");
+    expect(categories(lc)).toEqual({
+      new: "open",
+      researching: "open",
+      outreach: "open",
+      engaged: "active",
+      qualified: "active",
+      nurturing: "active",
+      converted: "done",
+      disqualified: "lost",
+    });
+  });
+
+  it("client = clientStatus, churned is a lost status (never a role)", () => {
+    for (const slug of ["foundation", "grants"]) {
+      const lc = lifecycleOf(tpl(slug), "client");
+      expect(lc?.property, slug).toBe("clientStatus");
+      expect(categories(lc).churned, slug).toBe("lost");
+    }
+  });
+
+  it("the post Produce Content drives declares post-status", () => {
+    const produce = tpl("content-os").playbooks!.find((p) => p.name === "Produce Content")!;
+    expect(produce.subjectProfile).toMatchObject({ profileSlug: "post", statusProperty: "post-status" });
+    const lc = lifecycleOf(tpl("content-os"), "post");
+    expect(lc?.property).toBe("post-status");
+    expect(categories(lc)).toMatchObject({ Idea: "open", Published: "done", Archived: "lost" });
+  });
+});
+
+/**
+ * Every (kind, statusProperty, playbook) a catalog playbook moves. `withSystem`
+ * false drops the pod's system kinds (task, decision, question…), whose
+ * lifecycle the pod seeds itself (`ensure-system-lifecycles.ts`) — except
+ * `deal`, a system kind whose lifecycle the CRM template owns.
+ */
+const TEMPLATE_OWNED_SYSTEM_LIFECYCLES = new Set(["deal"]);
+function playbookBindings({ withSystem = false } = {}) {
+  return corpus.flatMap((t) =>
+    (t.playbooks ?? [])
+      .filter(
+        (pb) =>
+          pb.subjectProfile?.statusProperty &&
+          (withSystem ||
+            !SYSTEM_PROFILES.has(pb.subjectProfile.profileSlug) ||
+            TEMPLATE_OWNED_SYSTEM_LIFECYCLES.has(pb.subjectProfile.profileSlug))
+      )
+      .map((pb) => ({ template: t, pb, kind: pb.subjectProfile!.profileSlug, property: pb.subjectProfile!.statusProperty! }))
+  );
+}
+
+describe("lifecycle declarations — the dev lifecycles (founder, 2026-10-13)", () => {
+  const shape = (profile: string) =>
+    lifecycleOf(tpl("builder-workspace"), profile)?.options.map((o) => [o.label, o.category, Boolean(o.humanOnly)]);
+
+  it("feature = featureStatus: Idea · Spec · Building · Review · Shipped · Dropped", () => {
+    expect(lifecycleOf(tpl("builder-workspace"), "devplane_feature")?.property).toBe("featureStatus");
+    expect(shape("devplane_feature")).toEqual([
+      ["Idea", "open", false],
+      ["Spec", "active", false],
+      ["Building", "active", false],
+      ["Review", "active", false],
+      ["Shipped", "done", false],
+      ["Dropped", "lost", true],
+    ]);
+  });
+
+  it("story = storyStatus: Draft · Ready · In feature · Done · Dropped", () => {
+    expect(lifecycleOf(tpl("builder-workspace"), "devplane_story")?.property).toBe("storyStatus");
+    expect(shape("devplane_story")).toEqual([
+      ["Draft", "open", false],
+      ["Ready", "active", false],
+      ["In feature", "active", false],
+      ["Done", "done", false],
+      ["Dropped", "lost", true],
+    ]);
+  });
+});
+
+describe("lifecycle declarations — coverage (derived from the playbooks)", () => {
+  it("non-vacuity: the scan sees the bindings it must", () => {
+    const kinds = new Set(playbookBindings().map((b) => b.kind));
+    expect(kinds.size).toBeGreaterThanOrEqual(14);
+    expect(kinds.has("post")).toBe(true);
+    expect(kinds.has("deal")).toBe(true);
+  });
+
+  it("every kind a playbook moves declares that property as its lifecycle, wherever it is declared", () => {
+    const missing: string[] = [];
+    for (const b of playbookBindings())
+      for (const t of corpus)
+        for (const p of t.profiles.filter((x) => x.slug === b.kind && x.properties.some((pr) => pr.slug === b.property)))
+          if (p.lifecycle?.property !== b.property) missing.push(`${t.meta.slug}:${b.kind}.${b.property}`);
+    expect([...new Set(missing)]).toEqual([]);
+  });
+
+  /**
+   * ACTIVE options a person must set, each a founder decision — the only place
+   * `humanOnly` may sit outside paused/done/lost. Still never invented: each
+   * must ALSO be in its binding playbook's `humanOnlyStatuses` (the rule below
+   * reads both). EXACT: an entry that is no longer humanOnly turns this red.
+   *  - ui-design.approved — the design review is a person's call; a coding
+   *    agent implements only from an approved design (DESIGN-DEV-XP-PLAN P6,
+   *    founder-approved 2026-10-12).
+   *  - outreach-touch.sent — the agent drafts, a person sends (founder decision
+   *    2026-10-20; the CRM absorbed Outreach & Comms 2026-10-23): no agent ever
+   *    marks a message sent, and the reply reader starts only once a person did.
+   */
+  const PERSON_ONLY_ACTIVE = new Set(["builder-workspace:ui-design.approved", "crm:outreach-touch.sent"]);
+
+  /**
+   * Person-only options the FOUNDER decided on a lifecycle no playbook moves
+   * yet (so no `humanOnlyStatuses` can carry them). Each one a dated decision;
+   * EXACT, like the ledger above.
+   *  - devplane_feature.cancelled / devplane_story.dropped — "Dropped (lost,
+   *    humanOnly)", object-first homes decision 2026-10-13.
+   */
+  const FOUNDER_HUMAN_ONLY = new Set([
+    "builder-workspace:devplane_feature.cancelled",
+    "builder-workspace:devplane_story.dropped",
+  ]);
+
+  it("humanOnly = the binding playbooks' humanOnlyStatuses that pause or end the thing", () => {
+    const drift: string[] = [];
+    const activeSeen: string[] = [];
+    const founderSeen: string[] = [];
+    for (const t of corpus)
+      for (const p of t.profiles) {
+        if (!p.lifecycle) continue;
+        const ho = new Set(
+          playbookBindings({ withSystem: true })
+            .filter((b) => b.kind === p.slug && b.property === p.lifecycle!.property)
+            .flatMap((b) => b.pb.humanOnlyStatuses ?? [])
+        );
+        for (const o of p.lifecycle.options) {
+          const id = `${t.meta.slug}:${p.slug}.${o.key}`;
+          const want =
+            (ho.has(o.key) && (["paused", "done", "lost"].includes(o.category) || PERSON_ONLY_ACTIVE.has(id))) ||
+            FOUNDER_HUMAN_ONLY.has(id);
+          if (want && PERSON_ONLY_ACTIVE.has(id)) activeSeen.push(id);
+          if (o.humanOnly && FOUNDER_HUMAN_ONLY.has(id)) founderSeen.push(id);
+          if (Boolean(o.humanOnly) !== want) drift.push(`${id} humanOnly=${Boolean(o.humanOnly)}`);
+        }
+      }
+    expect(drift).toEqual([]);
+    expect(activeSeen.sort()).toEqual([...PERSON_ONLY_ACTIVE].sort());
+    expect(founderSeen.sort()).toEqual([...FOUNDER_HUMAN_ONLY].sort());
+    // non-vacuity: the rule marks real options
+    expect(lifecycleOf(tpl("content-os"), "post")?.options.find((o) => o.key === "Archived")?.humanOnly).toBe(true);
+  });
+});
+
+describe("lifecycle declarations — the validator", () => {
+  it("the corpus has zero lifecycle errors", () => {
+    expect(corpus.flatMap((t) => lifecycleErrors(t).map((e) => `${t.meta.slug} ${e.rule}: ${e.message}`))).toEqual([]);
+  });
+
+  const clone = () => structuredClone(corpus);
+  const crmIn = (c: WorkspaceYaml[]) => c.find((t) => t.meta.slug === "crm")!;
+  const dealIn = (c: WorkspaceYaml[]) => crmIn(c).profiles.find((p) => p.slug === "deal")!;
+
+  it("self-check: options must be the enumValues, same order", () => {
+    const c = clone();
+    dealIn(c).lifecycle!.options.reverse();
+    expect(lifecycleErrors(crmIn(c), c).map((e) => e.rule)).toContain("lifecycle-options-mismatch");
+  });
+
+  it("self-check: an unknown category and an unknown property are refused", () => {
+    const c = clone();
+    (dealIn(c).lifecycle!.options[0] as { category: string }).category = "closed";
+    expect(lifecycleErrors(crmIn(c), c).map((e) => e.rule)).toContain("lifecycle-category");
+    dealIn(c).lifecycle!.property = "nope";
+    expect(lifecycleErrors(crmIn(c), c).map((e) => e.rule)).toContain("lifecycle-property-unknown");
+  });
+
+  it("self-check: two templates declaring one profile differently diverge", () => {
+    // `campaign` is declared with its lifecycle by marketing, content-os and crm
+    // (deal is declared with one only by crm since business-developer folded in).
+    const campaignIn = (c: WorkspaceYaml[], slug: string) =>
+      c.find((t) => t.meta.slug === slug)!.profiles.find((p) => p.slug === "campaign")!;
+    const c = clone();
+    campaignIn(c, "crm").lifecycle!.options[1].category = "open";
+    const marketing = c.find((t) => t.meta.slug === "marketing-campaign")!;
+    expect(lifecycleErrors(marketing, c).map((e) => e.rule)).toContain("lifecycle-diverges");
+    // dropping it from one declaration diverges too (reported where it is missing)
+    const c2 = clone();
+    delete campaignIn(c2, "crm").lifecycle;
+    expect(lifecycleErrors(crmIn(c2), c2).map((e) => e.rule)).toContain("lifecycle-diverges");
+  });
+
+  it("self-check: a playbook moving another property than the lifecycle is refused", () => {
+    const c = clone();
+    const produce = c.find((t) => t.meta.slug === "content-os")!.playbooks!.find((p) => p.name === "Produce Content")!;
+    const post = c.find((t) => t.meta.slug === "content-os")!.profiles.find((p) => p.slug === "post")!;
+    post.lifecycle!.property = "platform";
+    produce.subjectProfile!.statusProperty = "post-status";
+    expect(lifecycleErrors(c.find((t) => t.meta.slug === "content-os")!, c).map((e) => e.rule)).toContain(
+      "lifecycle-status-property"
+    );
+  });
+});