@synap-core/workspace-templates 0.12.0 → 0.23.0

package/src/validate.ts

@@ -31,6 +31,21 @@
  * so it is always present. It is DB-free (only `import type` internally), so it
  * needs no injection: the flow-node contract check runs for every caller
  * (build / check-converters / CLI / CP) automatically.
+ *
+ * A SECOND RUNTIME IMPORT: `@synap-core/types/capability-intents`, for the
+ * `taskIntents` membership check. This one resolves from the linked workspace
+ * package rather than a sibling file, and it is a LEAF with no generated
+ * dependency, so it is present under the type-stripper for the same reason
+ * `./validate-flow.ts` is. It is intentionally NOT injected like the
+ * converters: the intent vocabulary is a leaf VALUE, not a compiled template
+ * converter, and a validator that silently skips its check when a caller forgot
+ * to pass converters would be worse than one that resolves a constant.
+ *
+ * A THIRD RUNTIME IMPORT: `@synap-core/types/space-brief`, for the declared
+ * `skills[]` shape check. Same class as `capability-intents` — a pure,
+ * dependency-free leaf resolved from the linked workspace package. The rule is
+ * the SAME `validateSpaceSkillDeclaration` the pod's applier runs, so authoring
+ * and install cannot drift on what a skill declaration is.
  */
 
 import type {
@@ -41,6 +56,28 @@ import type {
 
 // eslint-disable-next-line import/extensions -- .ts extension is intentional; see header.
 import { validateFlowDefinition } from "./validate-flow.ts";
+// eslint-disable-next-line import/extensions -- .ts extension is intentional; see header.
+import { INTENT_LABEL_MAX, START_EXAMPLE_RANGE, START_STARTERS_RANGE, START_VIEWS_MAX } from "./types.ts";
+
+import {
+  CAPABILITY_INTENTS,
+  unknownIntents,
+} from "@synap-core/types/capability-intents";
+
+import { validateSpaceSkillDeclaration } from "@synap-core/types/space-brief";
+
+// A FOURTH runtime import, same leaf class as the two above: the ONE
+// presentation parser. `tsup.config.ts` BUNDLES this subpath into `dist/`
+// (`noExternal`), so a consumer whose resolved `@synap-core/types` predates
+// `./presentation` (the CP, the CLI) still loads the validator.
+import { declaredMediaSources, parseProfilePresentation } from "@synap-core/types/presentation";
+
+// A FIFTH runtime import, a sibling leaf like `./validate-flow.ts` (only
+// `import type` inside): the lifecycle preset compiler. Every rule below reads
+// the declaration the pod will store, so `adopts:` overlays and omitted
+// `enumValues` are compiled first (`validateTemplate`, "Lifecycle presets").
+// eslint-disable-next-line import/extensions -- .ts extension is intentional; see header.
+import { resolveLifecyclePresets } from "./lifecycle-presets.ts";
 
 // ── Result shape ─────────────────────────────────────────────────────────────
 
@@ -157,6 +194,8 @@ export const SYSTEM_PROFILES = new Set([
   // was simply missing from this hand-maintained list; the flow's
   // `create-report` node references it, so referential integrity needs it here.
   "report",
+  // Demand signal — a tool the user uses that Synap cannot connect yet
+  "tool_request",
 ]);
 
 /**
@@ -172,6 +211,19 @@ export const SYSTEM_PROFILES = new Set([
  * schema and its migration are owned by the backend seeder.
  */
 const TEMPLATE_FORBIDDEN_SYSTEM_PROFILE_SLUGS = new Set(["knowledge"]);
+/**
+ * Profile slugs the pod refuses on every profile write path, because the
+ * concept already has a first-class home elsewhere: projects live in the
+ * `projects` TABLE (migration 0151), not as an entity kind. A template that
+ * declares one can never install it — `ProfileRepository.create` throws — so
+ * the declaration is dead at best and a failed install at worst.
+ *
+ * MIRROR of `RESERVED_PROFILE_SLUGS` in
+ * `synap-backend/packages/database/src/utils/reserved-profile-slugs.ts` (this
+ * package cannot import `@synap/database`). `reserved-profile-slugs.test.ts`
+ * pins the two sets equal.
+ */
+export const RESERVED_PROFILE_SLUGS: ReadonlySet<string> = new Set(["project", "projects"]);
 const KNOWLEDGE_FORMS = new Set(["insight", "caution"]);
 const LEGACY_KNOWLEDGE_SEED_FIELDS = new Set(["ek_type", "type"]);
 
@@ -257,6 +309,34 @@ function collectProfileSlugRefs(
   }
 }
 
+/**
+ * `opts` with every corpus and dependency template compiled by
+ * `resolveLifecyclePresets`. Memoised per object, so the same authored template
+ * always maps to the same compiled one (`profileDeclarations` dedupes by
+ * identity) and `authored` maps to the `tpl` being validated.
+ */
+function withResolvedLifecycles(
+  opts: ValidateOptions,
+  authored: WorkspaceYaml,
+  tpl: WorkspaceYaml
+): ValidateOptions {
+  const compiled = new WeakMap<WorkspaceYaml, WorkspaceYaml>([[authored, tpl]]);
+  const compile = (t: WorkspaceYaml): WorkspaceYaml => {
+    let out = compiled.get(t);
+    if (!out) compiled.set(t, (out = resolveLifecyclePresets(t).template));
+    return out;
+  };
+  const { resolveDep } = opts;
+  return {
+    ...opts,
+    corpus: opts.corpus?.map(compile),
+    resolveDep: resolveDep && ((slug: string) => {
+      const t = resolveDep(slug);
+      return t && compile(t);
+    }),
+  };
+}
+
 function resolveDepFrom(
   opts: ValidateOptions
 ): (slug: string) => WorkspaceYaml | undefined {
@@ -272,6 +352,950 @@ function resolveDepFrom(
   return () => undefined;
 }
 
+// ── Shared-role references (W4a) ─────────────────────────────────────────────
+
+/** The template that owns the pod-wide shared ROLE vocabulary (concepts.md: Role). */
+export const SHARED_ROLE_SSOT_SLUG = "foundation";
+
+const isSharedRole = (p: TemplateProfile): boolean =>
+  isPodWideProfile(p) && p.profileKind === "role";
+
+/**
+ * A shared role declared WITHOUT `applicableKinds` is a REFERENCE: it names the
+ * one pod-wide role another template owns and adds at most workspace-overlay
+ * properties. The owner always declares `applicableKinds` (shared-role-ssot
+ * rule d), so its absence is the reference marker.
+ */
+const isRoleReference = (p: TemplateProfile): boolean =>
+  isSharedRole(p) && !(p.applicableKinds && p.applicableKinds.length > 0);
+
+/** Every template slug reachable through `dependencies` (compose + require, transitive). */
+export function collectDependencyClosure(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  seen = new Set<string>()
+): Set<string> {
+  for (const dep of tpl.dependencies || []) {
+    if (dep.relation !== "compose" && dep.relation !== "require") continue;
+    if (seen.has(dep.slug)) continue;
+    seen.add(dep.slug);
+    const base = resolveDep(dep.slug);
+    if (base) collectDependencyClosure(base, resolveDep, seen);
+  }
+  return seen;
+}
+
+/**
+ * A template that REFERENCES a shared role (or re-declares one of foundation's)
+ * must reach foundation through its dependency chain. The install engine keeps
+ * the pod-wide row's body from whichever template creates it FIRST, and deps
+ * install first — so without foundation in the chain a reference, installed on
+ * a pod that lacks foundation, would mint the pod-wide role with NO body (no
+ * applicableKinds ⇒ attachable to any kind, no properties).
+ */
+function checkSharedRoleReferences(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  add: (rule: string, path: string, message: string) => void
+): void {
+  if (tpl.meta?.slug === SHARED_ROLE_SSOT_SLUG) return;
+  const ssot = resolveDep(SHARED_ROLE_SSOT_SLUG);
+  const ssotRoles = new Set(
+    (ssot?.profiles ?? []).filter(isSharedRole).map((p) => p.slug)
+  );
+  const closure = collectDependencyClosure(tpl, resolveDep);
+  for (const p of tpl.profiles || []) {
+    if (!isSharedRole(p)) continue;
+    const reference = isRoleReference(p);
+    if (!reference && !ssotRoles.has(p.slug)) continue; // a role this template owns
+    if (!closure.has(SHARED_ROLE_SSOT_SLUG)) {
+      add(
+        "shared-role-reference-no-foundation",
+        `profiles.${p.slug}`,
+        `shared role "${p.slug}" is foundation's — "${SHARED_ROLE_SSOT_SLUG}" must be in this template's dependency chain (compose or require, transitively), else an install on a pod without it mints the role with no body`
+      );
+    }
+    if (reference && ssot && !ssotRoles.has(p.slug)) {
+      add(
+        "shared-role-reference-unknown",
+        `profiles.${p.slug}`,
+        `shared role "${p.slug}" is declared as a reference (no applicableKinds) but "${SHARED_ROLE_SSOT_SLUG}" does not define it — declare the full role (with applicableKinds) where it is owned`
+      );
+    }
+  }
+}
+
+// ── Step domains (W4a) ───────────────────────────────────────────────────────
+
+/** Same shape the pod's `playbookStageSchema.domain` accepts (playbook-stage.ts). */
+const STAGE_DOMAIN_SHAPE = /^@?[a-z0-9][a-z0-9._/-]*$/;
+const UUID_SHAPE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** A template that never owns a workspace: an overlay (compose) or a pack (suite). */
+function ownsNoWorkspace(t: WorkspaceYaml): string | null {
+  if ((t.dependencies ?? []).some((d) => d.relation === "compose"))
+    return "an overlay (it composes onto another workspace)";
+  if ((t.meta?.tags ?? []).includes("suite")) return "a pack";
+  return null;
+}
+
+/**
+ * `stage.domain` names the workspace TEMPLATE a step is worked in; the pod
+ * matches it against `workspaces.package_slug` (tracks/stage-domain.ts). So it
+ * must be slug-shaped (the pod door refuses anything else — failing here is
+ * cheaper than failing at install), name a template the corpus knows, and name
+ * one that OWNS a workspace: an overlay's or a pack's slug is never any
+ * workspace's package_slug, so such a step would always fall back to the
+ * project home.
+ */
+function checkStageDomains(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  add: (rule: string, path: string, message: string) => void
+): void {
+  for (const pb of tpl.playbooks || []) {
+    for (const stage of pb.stages || []) {
+      const domain = stage.domain;
+      if (domain === undefined) continue;
+      const path = `playbooks."${pb.name}".stages.${stage.key}.domain`;
+      if (
+        typeof domain !== "string" ||
+        !STAGE_DOMAIN_SHAPE.test(domain) ||
+        UUID_SHAPE.test(domain)
+      ) {
+        add(
+          "stage-domain-shape",
+          path,
+          `step domain "${String(domain)}" must be a workspace template slug (lowercase, e.g. "crm"), not a workspace id or name`
+        );
+        continue;
+      }
+      const target =
+        domain === tpl.meta?.slug ? tpl : resolveDep(domain);
+      if (!target) {
+        // Only knowable with a corpus; a lone-template validate cannot tell.
+        if (hasCorpus(resolveDep))
+          add(
+            "stage-domain-unknown",
+            path,
+            `step domain "${domain}" is not a workspace template in the corpus`
+          );
+        continue;
+      }
+      const why = ownsNoWorkspace(target);
+      if (why) {
+        add(
+          "stage-domain-not-a-domain",
+          path,
+          `step domain "${domain}" is ${why} — it never owns a workspace, so the step could never resolve; name the workspace template it lands on`
+        );
+      }
+    }
+  }
+}
+
+/**
+ * D8 (2026-09-25): a pack lists the WORKSPACE TEMPLATES it needs — never another
+ * pack. A pack-on-pack dependency hides which workspace templates are really
+ * installed and re-introduces the stray suite workspace D8 retired.
+ */
+function checkPackDependencies(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  add: (rule: string, path: string, message: string) => void
+): void {
+  if (!(tpl.meta?.tags ?? []).includes("suite")) return;
+  for (const dep of tpl.dependencies || []) {
+    const target = resolveDep(dep.slug);
+    if (target && (target.meta?.tags ?? []).includes("suite")) {
+      add(
+        "pack-requires-pack",
+        `dependencies.${dep.slug}`,
+        `pack "${tpl.meta?.slug}" depends on pack "${dep.slug}" — list the workspace templates "${dep.slug}" needs instead (D8)`
+      );
+    }
+  }
+}
+
+// ── Process contract (lifecycle-bound playbooks) ─────────────────────────────
+
+/** The `relationToSubject` value that deliberately writes no edge. */
+export const NO_SUBJECT_RELATION = "none";
+
+/**
+ * Every declaration of profile `slug` this template can see, own first: its
+ * own block, then its dependency closure, then (with a corpus) any template.
+ * A kind can be OWNED by a dependency (a `scope: shared` body), so the status
+ * property is not necessarily declared where the playbook is.
+ */
+function profileDeclarations(
+  slug: string,
+  tpl: WorkspaceYaml,
+  resolveDep: (s: string) => WorkspaceYaml | undefined,
+  corpus: WorkspaceYaml[] | undefined
+): TemplateProfile[] {
+  const sources: WorkspaceYaml[] = [tpl];
+  for (const dep of collectDependencyClosure(tpl, resolveDep)) {
+    const t = resolveDep(dep);
+    if (t) sources.push(t);
+  }
+  for (const t of corpus ?? []) if (!sources.includes(t)) sources.push(t);
+  return sources.flatMap((t) =>
+    (t.profiles ?? []).filter((p) => p.slug === slug)
+  );
+}
+
+/**
+ * The relation types this template can name: the corpus's `entityLinks[].type`
+ * and `relationDefs[].slug` (the defaults live in `base.yaml`'s relationDefs,
+ * mirrored by `__fixtures__/default-relation-defs.json`). Without a corpus:
+ * own + dependency closure + `base`.
+ */
+export function knownRelationTypes(
+  tpl: WorkspaceYaml,
+  resolveDep: (s: string) => WorkspaceYaml | undefined,
+  corpus: WorkspaceYaml[] | undefined
+): Set<string> {
+  const sources: WorkspaceYaml[] = corpus ? [...corpus] : [];
+  if (!sources.includes(tpl)) sources.push(tpl);
+  if (!corpus) {
+    for (const dep of collectDependencyClosure(tpl, resolveDep)) {
+      const t = resolveDep(dep);
+      if (t) sources.push(t);
+    }
+    const base = resolveDep("base");
+    if (base) sources.push(base);
+  }
+  const out = new Set<string>();
+  for (const t of sources) {
+    for (const el of t.entityLinks ?? []) if (el.type) out.add(el.type);
+    for (const rd of t.relationDefs ?? []) if (rd.slug) out.add(rd.slug);
+  }
+  return out;
+}
+
+/**
+ * The process contract a playbook declares on top of its stages:
+ *  - `subjectProfile.statusProperty` is a SELECT property of the subject kind;
+ *  - every `stages[].subjectStatus`, `activators[].status` and
+ *    `humanOnlyStatuses[]` is one of that property's enum values;
+ *  - `onFail.toStage` names a stage (key or name) of the same playbook;
+ *  - every `relationToSubject` (playbook- and stage-level outputs) is a
+ *    relation the corpus defines, or `none`.
+ * Each of these, if wrong, is stored by the pod and then silently never fires
+ * (a status write the select refuses, an activator rule on a value no entity
+ * ever enters, an edge type nothing renders).
+ */
+/**
+ * The most criteria a session keeps. MIRROR of `MAX_SESSION_CRITERIA` in
+ * `synap-backend/packages/playbooks/src/index.ts` (this package cannot import
+ * `@synap/playbooks`): `collectPlaybookCriteria` gathers the playbook-level list
+ * then every stage's, keeps a repeated key once, and `readCriteria` drops
+ * everything past this cap without a word. `process-contract.validate.test.ts`
+ * pins the two values equal.
+ */
+export const MAX_SESSION_CRITERIA = 12;
+
+/**
+ * The activator triggers the pod compiles (work model L4) — the schema's
+ * `ACTIVATOR_ON` (`schema/playbook.ts`), which this build cannot import
+ * (rootDir is `src`). `schema/mirror.tripwire.test.ts` pins the two equal,
+ * and both to the pod's `playbookActivatorSchema`.
+ */
+export const TEMPLATE_ACTIVATOR_ON = ["created", "enters_status", "count", "schedule", "manual"] as const;
+
+function checkProcessContract(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  corpus: WorkspaceYaml[] | undefined,
+  add: (rule: string, path: string, message: string) => void
+): void {
+  let relations: Set<string> | null = null;
+  const relationsOnce = () =>
+    (relations ??= knownRelationTypes(tpl, resolveDep, corpus));
+
+  for (const pb of tpl.playbooks || []) {
+    const at = `playbooks."${pb.name}"`;
+    const kind = pb.subjectProfile?.profileSlug;
+    const statusProperty = pb.subjectProfile?.statusProperty;
+
+    // Resolve the lifecycle vocabulary (null = no status property to check against).
+    let statuses: Set<string> | null = null;
+    if (statusProperty !== undefined) {
+      if (!kind) {
+        add(
+          "playbook-status-property-no-subject",
+          `${at}.subjectProfile.statusProperty`,
+          `playbook "${pb.name}" declares statusProperty "${statusProperty}" without a subjectProfile.profileSlug`
+        );
+      } else {
+        const decls = profileDeclarations(kind, tpl, resolveDep, corpus);
+        const prop = decls
+          .flatMap((p) => p.properties ?? [])
+          .find((pr) => pr.slug === statusProperty);
+        if (!prop) {
+          // A kind no declaration in reach carries (unknown kind is reported
+          // by playbook-ref-unknown; don't double-report it here).
+          if (decls.length > 0 || hasCorpus(resolveDep))
+            add(
+              "playbook-status-property-unknown",
+              `${at}.subjectProfile.statusProperty`,
+              `playbook "${pb.name}" statusProperty "${statusProperty}" is not a property of kind "${kind}"`
+            );
+        } else if (
+          prop.inputType !== "select" ||
+          !Array.isArray(prop.enumValues) ||
+          prop.enumValues.length === 0
+        ) {
+          add(
+            "playbook-status-property-not-select",
+            `${at}.subjectProfile.statusProperty`,
+            `playbook "${pb.name}" statusProperty "${kind}.${statusProperty}" must be a select property with enumValues (found inputType "${String(prop.inputType)}")`
+          );
+        } else {
+          statuses = new Set(prop.enumValues);
+        }
+      }
+    }
+    const checkStatus = (rule: string, path: string, value: unknown) => {
+      if (statusProperty === undefined) {
+        add(
+          `${rule}-no-property`,
+          path,
+          `${path} = "${String(value)}" needs subjectProfile.statusProperty — a status is a value OF that property`
+        );
+      } else if (statuses && !statuses.has(value as string)) {
+        add(
+          rule,
+          path,
+          `${path} = "${String(value)}" is not a value of ${kind}.${statusProperty} (${[...statuses].join(", ")})`
+        );
+      }
+    };
+
+    const stages = pb.stages ?? [];
+    const stageIds = new Set(stages.flatMap((s) => [s.key, s.name]));
+
+    const criterionKeys = new Set(
+      [...(pb.criteria ?? []), ...stages.flatMap((s) => s.criteria ?? [])]
+        .map((c) => (c as { key?: unknown } | null)?.key)
+        .filter((k): k is string => typeof k === "string" && k.trim() !== "")
+    );
+    if (criterionKeys.size > MAX_SESSION_CRITERIA)
+      add(
+        "playbook-criteria-over-session-cap",
+        `${at}.criteria`,
+        `playbook "${pb.name}" declares ${criterionKeys.size} criteria (playbook-level plus every stage's) — a session keeps ${MAX_SESSION_CRITERIA} and drops the rest silently`
+      );
+    for (const stage of stages) {
+      const sp = `${at}.stages.${stage.key}`;
+      if (stage.subjectStatus !== undefined)
+        checkStatus("stage-subject-status-unknown", `${sp}.subjectStatus`, stage.subjectStatus);
+      const toStage = stage.onFail?.toStage;
+      if (stage.onFail !== undefined && (!toStage || !stageIds.has(toStage)))
+        add(
+          "stage-onfail-unknown",
+          `${sp}.onFail.toStage`,
+          `stage "${stage.key}" onFail.toStage "${String(toStage)}" names no stage of playbook "${pb.name}"`
+        );
+    }
+
+    (pb.activators ?? []).forEach((a, i) => {
+      const ap = `${at}.activators[${i}]`;
+      if (!(TEMPLATE_ACTIVATOR_ON as readonly string[]).includes(a.on))
+        add("activator-on-invalid", `${ap}.on`, `${ap}.on "${String(a.on)}" must be one of ${TEMPLATE_ACTIVATOR_ON.join(", ")}`);
+      if (a.mode !== "run" && a.mode !== "propose")
+        add("activator-mode-invalid", `${ap}.mode`, `${ap}.mode "${String(a.mode)}" must be "run" or "propose"`);
+      if (!kind)
+        add("activator-no-subject", ap, `${ap} needs subjectProfile.profileSlug — an activator fires on an entity of that kind`);
+      if (a.on === "enters_status" || a.on === "count") {
+        if (a.status === undefined)
+          add("activator-status-required", `${ap}.status`, `${ap} on "${a.on}" names no status`);
+        else checkStatus("activator-status-unknown", `${ap}.status`, a.status);
+      } else if (a.on === "schedule") {
+        if (a.status !== undefined) checkStatus("activator-status-unknown", `${ap}.status`, a.status);
+      } else if (a.status !== undefined) {
+        add("activator-status-unexpected", `${ap}.status`, `${ap}.status is not read when on = "${a.on}"`);
+      }
+    });
+
+    (pb.humanOnlyStatuses ?? []).forEach((s, i) =>
+      checkStatus("human-only-status-unknown", `${at}.humanOnlyStatuses[${i}]`, s)
+    );
+
+    const outputs: Array<{ path: string; rel: unknown; optional: unknown; at: string }> = [
+      ...(pb.expectedOutputs ?? []).map((o, i) => ({
+        at: `${at}.expectedOutputs[${i}]`,
+        path: `${at}.expectedOutputs[${i}].relationToSubject`,
+        rel: o.relationToSubject,
+        optional: o.optional,
+      })),
+      ...stages.flatMap((s) =>
+        (s.expectedOutputs ?? []).map((o, i) => ({
+          at: `${at}.stages.${s.key}.expectedOutputs[${i}]`,
+          path: `${at}.stages.${s.key}.expectedOutputs[${i}].relationToSubject`,
+          rel: o.relationToSubject,
+          optional: o.optional,
+        }))
+      ),
+    ];
+    // `optional` is read STRICTLY by the pod (only a real `true` counts), so a
+    // quoted "true" would leave the slot owed and a quoted "false" looks like a
+    // decision nobody's code reads.
+    for (const o of outputs)
+      if (o.optional !== undefined && typeof o.optional !== "boolean")
+        add("output-optional-not-boolean", `${o.at}.optional`, `${o.at}.optional = ${JSON.stringify(o.optional)} must be true or false — the pod treats anything but a real true as required`);
+    for (const { path, rel } of outputs) {
+      if (rel === undefined || rel === NO_SUBJECT_RELATION) continue;
+      if (!kind) {
+        add("output-relation-no-subject", path, `${path} = "${String(rel)}" but playbook "${pb.name}" has no subject to relate to (use "${NO_SUBJECT_RELATION}")`);
+      } else if (typeof rel !== "string" || !relationsOnce().has(rel)) {
+        add("output-relation-unknown", path, `${path} = "${String(rel)}" is not a relation the corpus defines (entityLinks[].type / relationDefs[].slug)`);
+      }
+    }
+  }
+}
+
+// ── Lifecycle declarations (work model L1) ──────────────────────────────────
+
+/**
+ * The fixed lifecycle categories. MIRROR of `LIFECYCLE_CATEGORIES` in
+ * `@synap-core/types/lifecycle` (and the pod's `utils/lifecycle-model.ts`):
+ * this validator also runs from the published dist on the CP, whose resolved
+ * `@synap-core/types` may predate the `./lifecycle` subpath, so it is not
+ * imported. `lifecycle-declarations.test.ts` pins the two lists equal.
+ */
+export const LIFECYCLE_CATEGORIES = ["open", "active", "paused", "done", "lost"] as const;
+
+/** MIRROR of the pod's `STUCK_AFTER_DAYS_MAX` (`utils/lifecycle-model.ts`), same reason as above. */
+export const STUCK_AFTER_DAYS_MAX = 3650;
+
+/**
+ * The fields of a lifecycle option and of a step's declared wait. MIRROR of
+ * `LifecycleOption` / `LifecycleOptionWaits` (`@synap-core/types/lifecycle`,
+ * `option.ts`), same reason as above; `lifecycle-waits.parity.test.ts` pins
+ * them to that source and to the pod's parser.
+ */
+export const LIFECYCLE_OPTION_FIELDS = [
+  "key",
+  "label",
+  "category",
+  "tone",
+  "humanOnly",
+  "stuckAfterDays",
+  "dateBinding",
+  "waits",
+] as const;
+export const LIFECYCLE_OPTION_WAITS_FIELDS = ["on", "waitKind", "refFrom", "dateBinding"] as const;
+
+/**
+ * What a step may say it waits on: MIRROR of the pod's `HOLD_ON` without
+ * `unspecified` (`parseOptionWaits`, `utils/lifecycle-model.ts`: a step that
+ * says `unspecified` says nothing, and the pod refuses it).
+ */
+export const LIFECYCLE_WAITS_ON = ["person", "agent", "external", "thing", "decision", "date", "nobody"] as const;
+
+/** MIRROR of `WAIT_KINDS` (`@synap-core/types/units`, `wait-kind.ts`), same reason as above. */
+export const LIFECYCLE_WAIT_KINDS = [
+  "answer",
+  "approval",
+  "send",
+  "try_it",
+  "access",
+  "decide",
+  "their_reply",
+  "their_document",
+  "signature",
+  "payment",
+  "vendor",
+  "agent_work",
+  "agent_stopped",
+  "ci",
+  "devbox_job",
+  "merge_queue",
+  "red_main",
+  "deploy",
+  "another_work",
+  "date",
+  "nobody",
+] as const;
+
+/**
+ * A property an option names (`dateBinding`, `waits.refFrom`,
+ * `waits.dateBinding`): its slug. MIRROR of the pod's `DATE_BINDING`
+ * (`utils/lifecycle-model.ts`).
+ */
+export const LIFECYCLE_PROPERTY_SLUG = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+/**
+ * The problems of one option's `dateBinding` and `waits`, in the pod's words
+ * and by the pod's rules (`parseLifecycleOptions` / `parseOptionWaits`): a
+ * property slug, never on a done/lost option; `waits.on` one of
+ * {@link LIFECYCLE_WAITS_ON}, `waitKind` one of {@link LIFECYCLE_WAIT_KINDS},
+ * `refFrom` / `dateBinding` property slugs, no other field. Exactly what the
+ * pod accepts: nothing more (it does not check that the property exists).
+ */
+export function lifecycleOptionWaitsProblems(option: {
+  key?: unknown;
+  category?: unknown;
+  dateBinding?: unknown;
+  waits?: unknown;
+}): Array<{ field: "dateBinding" | "waits"; message: string }> {
+  const out: Array<{ field: "dateBinding" | "waits"; message: string }> = [];
+  const key = String(option.key);
+  const finished = option.category === "done" || option.category === "lost";
+  if (option.dateBinding !== undefined) {
+    if (typeof option.dateBinding !== "string" || !LIFECYCLE_PROPERTY_SLUG.test(option.dateBinding))
+      out.push({
+        field: "dateBinding",
+        message: `option "${key}" dateBinding must name a date property (its slug, e.g. "dueDate")`,
+      });
+    else if (finished)
+      out.push({
+        field: "dateBinding",
+        message: `option "${key}" is ${String(option.category)}: a finished thing cannot be late (dateBinding is for open, active or paused options)`,
+      });
+  }
+  const w = option.waits;
+  if (w === undefined) return out;
+  const fail = (message: string) => {
+    out.push({ field: "waits", message });
+    return out;
+  };
+  if (!w || typeof w !== "object" || Array.isArray(w))
+    return fail(`option "${key}" waits must be an object { on, waitKind?, refFrom?, dateBinding? }`);
+  if (finished)
+    return fail(
+      `option "${key}" is ${String(option.category)}: a finished thing waits on nothing (waits is for open, active or paused options)`
+    );
+  const waits = w as Record<string, unknown>;
+  if (typeof waits.on !== "string" || !(LIFECYCLE_WAITS_ON as readonly string[]).includes(waits.on))
+    return fail(`option "${key}" waits.on must be one of ${LIFECYCLE_WAITS_ON.join(" | ")}`);
+  if (
+    waits.waitKind !== undefined &&
+    (typeof waits.waitKind !== "string" || !(LIFECYCLE_WAIT_KINDS as readonly string[]).includes(waits.waitKind))
+  )
+    return fail(`option "${key}" waits.waitKind is not a wait kind (WAIT_KINDS)`);
+  for (const field of ["refFrom", "dateBinding"] as const) {
+    const v = waits[field];
+    if (v !== undefined && (typeof v !== "string" || !LIFECYCLE_PROPERTY_SLUG.test(v)))
+      return fail(
+        `option "${key}" waits.${field} must name a property (its slug, e.g. "${field === "refFrom" ? "contactId" : "nextActionAt"}")`
+      );
+  }
+  const unknown = Object.keys(waits).filter(
+    (k) => !(LIFECYCLE_OPTION_WAITS_FIELDS as readonly string[]).includes(k)
+  );
+  if (unknown.length > 0) return fail(`option "${key}" waits has unknown field(s): ${unknown.join(", ")}`);
+  return out;
+}
+
+/** Key-sorted JSON, so two equal declarations compare equal whatever the YAML key order. */
+function stableJson(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(stableJson).join(",")}]`;
+  if (v && typeof v === "object")
+    return `{${Object.keys(v as Record<string, unknown>)
+      .filter((k) => (v as Record<string, unknown>)[k] !== undefined)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stableJson((v as Record<string, unknown>)[k])}`)
+      .join(",")}}`;
+  return JSON.stringify(v);
+}
+
+/**
+ * A profile's `lifecycle` must be installable as declared. The pod folds the
+ * options onto the property (REPLACING its enum with the option keys) and
+ * refuses an uncategorized option, so:
+ *  - `property` is a select of this profile with `enumValues` (a YAML may omit
+ *    them: `resolveLifecyclePresets` generates them from the options before
+ *    this rule runs, so a missing list only reaches here on a non-select);
+ *  - the option keys ARE those enumValues, same order (an option missing from
+ *    the list would silently drop a value the select accepts; an extra one
+ *    would add a value no picker in the YAML shows);
+ *  - every option has one of the five categories; `humanOnly` is a boolean;
+ *    `stuckAfterDays` is a whole number of days (1–3650) on an option that
+ *    can still move (never done/lost — the pod refuses it there too);
+ *    `dateBinding` and a step's `waits` follow the pod's own rules
+ *    ({@link lifecycleOptionWaitsProblems}).
+ * With a corpus: every template that declares this profile WITH the lifecycle
+ * property declares the SAME lifecycle — the pod declares it from whichever
+ * template installs first, so two different declarations would make a pod's
+ * lifecycle depend on install order. And a playbook binding the kind reads the
+ * lifecycle property as its `statusProperty`.
+ */
+function checkLifecycleDeclarations(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  corpus: WorkspaceYaml[] | undefined,
+  add: (rule: string, path: string, message: string) => void
+): void {
+  const categories = new Set<string>(LIFECYCLE_CATEGORIES);
+  for (const profile of tpl.profiles ?? []) {
+    const lc = profile.lifecycle;
+    const at = `profiles.${profile.slug}.lifecycle`;
+    if (lc !== undefined) {
+      const prop = (profile.properties ?? []).find((p) => p.slug === lc?.property);
+      if (!prop || prop.inputType !== "select" || !Array.isArray(prop.enumValues) || prop.enumValues.length === 0) {
+        add(
+          "lifecycle-property-unknown",
+          `${at}.property`,
+          `lifecycle property "${String(lc?.property)}" must be a select property of "${profile.slug}" with enumValues`
+        );
+      } else {
+        const options = Array.isArray(lc.options) ? lc.options : [];
+        const keys = options.map((o) => o?.key);
+        if (stableJson(keys) !== stableJson(prop.enumValues))
+          add(
+            "lifecycle-options-mismatch",
+            `${at}.options`,
+            `lifecycle options [${keys.join(", ")}] must be "${profile.slug}.${prop.slug}" enumValues [${prop.enumValues.join(", ")}], same order`
+          );
+        options.forEach((o, i) => {
+          if (!categories.has(o?.category as string))
+            add(
+              "lifecycle-category",
+              `${at}.options[${i}].category`,
+              `option "${String(o?.key)}" category "${String(o?.category)}" is not one of ${LIFECYCLE_CATEGORIES.join(" · ")}`
+            );
+          if (o?.humanOnly !== undefined && typeof o.humanOnly !== "boolean")
+            add("lifecycle-option-shape", `${at}.options[${i}].humanOnly`, `option "${String(o?.key)}" humanOnly must be a boolean`);
+          const stuck = (o as { stuckAfterDays?: unknown } | undefined)?.stuckAfterDays;
+          if (stuck !== undefined) {
+            if (typeof stuck !== "number" || !Number.isInteger(stuck) || stuck < 1 || stuck > STUCK_AFTER_DAYS_MAX)
+              add(
+                "lifecycle-option-shape",
+                `${at}.options[${i}].stuckAfterDays`,
+                `option "${String(o?.key)}" stuckAfterDays must be a whole number of days from 1 to ${STUCK_AFTER_DAYS_MAX}`
+              );
+            else if (o?.category === "done" || o?.category === "lost")
+              add(
+                "lifecycle-option-shape",
+                `${at}.options[${i}].stuckAfterDays`,
+                `option "${String(o?.key)}" is ${o.category}: a finished thing cannot be stuck`
+              );
+          }
+          for (const p of lifecycleOptionWaitsProblems(o ?? {}))
+            add("lifecycle-option-shape", `${at}.options[${i}].${p.field}`, p.message);
+        });
+      }
+    }
+
+    if (!corpus) continue;
+    // Every declaration of this profile that carries the lifecycle property
+    // must declare the same lifecycle (absent counts as different).
+    const own = stableJson(profile.lifecycle ?? null);
+    const other = profileDeclarations(profile.slug, tpl, resolveDep, corpus)
+      .filter((p) => p !== profile)
+      .map((p) => p.lifecycle)
+      .find(
+        (l) =>
+          l !== undefined &&
+          stableJson(l) !== own &&
+          (profile.properties ?? []).some((p) => p.slug === l.property)
+      );
+    if (other)
+      add(
+        "lifecycle-diverges",
+        `profiles.${profile.slug}.lifecycle`,
+        `"${profile.slug}" declares "${other.property}" here ${profile.lifecycle ? "with a different lifecycle than" : "without the lifecycle"} another template declares — the pod keeps whichever installs first, so every declaration must be identical`
+      );
+  }
+
+  // A playbook moving a kind with a declared lifecycle moves THAT property.
+  for (const pb of tpl.playbooks ?? []) {
+    const kind = pb.subjectProfile?.profileSlug;
+    const statusProperty = pb.subjectProfile?.statusProperty;
+    if (!kind || statusProperty === undefined) continue;
+    const lc = profileDeclarations(kind, tpl, resolveDep, corpus)
+      .map((p) => p.lifecycle)
+      .find((l) => l !== undefined);
+    if (lc && lc.property !== statusProperty)
+      add(
+        "lifecycle-status-property",
+        `playbooks."${pb.name}".subjectProfile.statusProperty`,
+        `playbook "${pb.name}" moves "${kind}.${statusProperty}" but "${kind}"'s lifecycle is "${lc.property}" — a kind has ONE lifecycle`
+      );
+  }
+}
+
+// ── Presentation declarations (entity rendering, decision 8) ────────────────
+
+/**
+ * A profile's `presentation` must be installable as declared. The pod judges
+ * it with the SAME parser (`parseProfilePresentation`) and stores it as
+ * `uiHints.presentation`, so:
+ *  - it parses (family, exactly one media source, field caps);
+ *  - every property it names — `media.source` / each `media.fallbacks` entry
+ *    (`property`, `entityRef`)
+ *    and each `fields.card` / `fields.row` slug — is a property of THIS
+ *    declaration (`documentId: true` names the entity's own linked document,
+ *    not a property); an `entityRef` property is an `entity_id`;
+ * With a corpus: every declaration of the slug that carries a presentation
+ * declares the SAME one — the pod converges to whichever template applies
+ * last, so two different ones would make a kind's look depend on apply order.
+ * A declaration WITHOUT one is fine: absent leaves the pod's value alone.
+ */
+function checkPresentationDeclarations(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  corpus: WorkspaceYaml[] | undefined,
+  add: (rule: string, path: string, message: string) => void
+): void {
+  for (const profile of tpl.profiles ?? []) {
+    if (profile.presentation === undefined) continue;
+    const at = `profiles.${profile.slug}.presentation`;
+    const parsed = parseProfilePresentation(profile.presentation);
+    if (!parsed.ok) {
+      for (const issue of parsed.issues)
+        add(
+          "presentation-invalid",
+          `profiles.${profile.slug}.${issue.path}`,
+          `"${profile.slug}" ${issue.path}: ${issue.message}`
+        );
+      continue;
+    }
+    const props = new Map((profile.properties ?? []).map((p) => [p.slug, p]));
+    const named: Array<{ path: string; slug: string; entityRef?: boolean }> = [];
+    // `source` then each fallback: every home of the media must exist here.
+    declaredMediaSources(parsed.value).forEach((source, i) => {
+      const where = i === 0 ? `${at}.media.source` : `${at}.media.fallbacks[${i - 1}]`;
+      if ("property" in source) named.push({ path: `${where}.property`, slug: source.property });
+      if ("entityRef" in source)
+        named.push({ path: `${where}.entityRef`, slug: source.entityRef, entityRef: true });
+    });
+    for (const alt of ["card", "row"] as const)
+      (parsed.value.fields?.[alt] ?? []).forEach((slug, i) =>
+        named.push({ path: `${at}.fields.${alt}[${i}]`, slug })
+      );
+    for (const n of named) {
+      const prop = props.get(n.slug);
+      if (!prop)
+        add(
+          "presentation-property-unknown",
+          n.path,
+          `"${profile.slug}" presentation names "${n.slug}", which is not a property of "${profile.slug}" here`
+        );
+      else if (n.entityRef && prop.valueType !== "entity_id")
+        add(
+          "presentation-entityref-type",
+          n.path,
+          `"${profile.slug}" presentation entityRef "${n.slug}" must be an entity_id property (it is ${prop.valueType})`
+        );
+    }
+
+    if (!corpus) continue;
+    const own = stableJson(parsed.value);
+    const other = profileDeclarations(profile.slug, tpl, resolveDep, corpus)
+      .filter((p) => p !== profile && p.presentation !== undefined)
+      .find((p) => {
+        const o = parseProfilePresentation(p.presentation);
+        return !o.ok || stableJson(o.value) !== own;
+      });
+    if (other)
+      add(
+        "presentation-diverges",
+        at,
+        `"${profile.slug}" declares a different presentation than another template does — the pod keeps whichever applies last, so every declaration must be identical (or omit it)`
+      );
+  }
+}
+
+// ── Intent: what a space produces (object-first homes H0) ───────────────────
+
+/**
+ * `meta.intent = { label, produces: [{ profile }] }` names what the space
+ * PRODUCES, in order; no `produces` makes it a library. Rules:
+ *  - `label` is a non-empty string of at most {@link INTENT_LABEL_MAX} chars;
+ *  - each `profile` is declared by this template or by a template in its
+ *    dependency closure (a role/kind it depends on), and is named once;
+ *  - each produced profile DECLARES a lifecycle (in one of those
+ *    declarations) — a home counts things by lifecycle category, and a kind
+ *    without one cannot be counted;
+ *  - only a template that OWNS a space declares it (never an overlay or a
+ *    pack — `ownsNoWorkspace`).
+ * The dependency half needs the closure: a profile neither own nor reachable
+ * because a dependency did not resolve is not judged (no corpus to see it).
+ */
+function checkIntent(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  add: (rule: string, path: string, message: string) => void
+): void {
+  const intent = tpl.meta?.intent as unknown;
+  if (intent === undefined) return;
+  // An overlay layers onto its base's space and a pack owns none: an intent
+  // there would overwrite the base space's (the pod merges it into the space
+  // it lands on) or land nowhere. The space's own template names it.
+  const why = ownsNoWorkspace(tpl);
+  if (why) {
+    add(
+      "intent-no-workspace",
+      "meta.intent",
+      `"${tpl.meta.slug}" is ${why} — it owns no space, so it cannot name what a space produces; the template that owns the space declares meta.intent`
+    );
+    return;
+  }
+  if (!intent || typeof intent !== "object" || Array.isArray(intent)) {
+    add("intent-shape", "meta.intent", "meta.intent must be { label, produces?: [{ profile }] }");
+    return;
+  }
+  const { label, produces } = intent as { label?: unknown; produces?: unknown };
+  if (typeof label !== "string" || !label.trim() || label.trim().length > INTENT_LABEL_MAX)
+    add(
+      "intent-label",
+      "meta.intent.label",
+      `meta.intent.label must be a non-empty string of at most ${INTENT_LABEL_MAX} characters (got ${JSON.stringify(label)})`
+    );
+  if (produces === undefined) return;
+  if (!Array.isArray(produces)) {
+    add("intent-shape", "meta.intent.produces", "meta.intent.produces must be a list of { profile }");
+    return;
+  }
+  const closure = [...collectDependencyClosure(tpl, resolveDep)];
+  const sources = [tpl, ...closure.map(resolveDep).filter((t): t is WorkspaceYaml => !!t)];
+  const unresolved = closure.some((d) => !resolveDep(d));
+  const seen = new Set<string>();
+  produces.forEach((entry, i) => {
+    const at = `meta.intent.produces[${i}]`;
+    const slug = (entry as { profile?: unknown } | null)?.profile;
+    if (typeof slug !== "string" || !slug) {
+      add("intent-shape", `${at}.profile`, `${at} must be { profile: <profile slug> }`);
+      return;
+    }
+    if (seen.has(slug)) add("intent-duplicate", `${at}.profile`, `"${slug}" is produced twice`);
+    seen.add(slug);
+    const decls = sources.flatMap((t) => (t.profiles ?? []).filter((p) => p.slug === slug));
+    if (decls.length === 0) {
+      if (!unresolved)
+        add(
+          "intent-profile-unknown",
+          `${at}.profile`,
+          `"${slug}" is produced but neither "${tpl.meta.slug}" nor a template it depends on declares it`
+        );
+      return;
+    }
+    if (!decls.some((p) => p.lifecycle !== undefined))
+      add(
+        "intent-no-lifecycle",
+        `${at}.profile`,
+        `"${slug}" is produced but declares no lifecycle — a space home counts what it produces by lifecycle; declare "${slug}"'s lifecycle or leave it out of produces`
+      );
+  });
+}
+
+// ── Start: a space offered as an onboarding start ───────────────────────────
+
+/**
+ * `meta.start` (see `TemplateStart`). Rules, all `start-*`:
+ *  - only a template that OWNS a space declares one (`start-no-workspace`);
+ *  - the shape is complete (`start-shape`); label ≤ {@link INTENT_LABEL_MAX}
+ *    (`start-label`); example and starters sizes (`start-example-count`,
+ *    `start-starters-count`);
+ *  - `views` are 1-{@link START_VIEWS_MAX} slugs of THIS template's views,
+ *    each scoped to `profile` (`start-views-count`, `start-views-exist`,
+ *    `start-views-scope`);
+ *  - `profile` is the template's own kind or one from its dependency closure
+ *    (`start-profile-unknown`);
+ *  - `example` keys are properties of `profile` and select values are among its
+ *    `enumValues` (`start-example-property`, `start-example-enum`);
+ *  - with a corpus: `order` and every `suggestFor` id belong to ONE start
+ *    (`start-order-duplicate`, `start-suggest-duplicate`).
+ * The profile half needs the closure: an unresolved dependency is not judged.
+ */
+function checkStart(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  corpus: WorkspaceYaml[] | undefined,
+  add: (rule: string, path: string, message: string) => void
+): void {
+  const raw = tpl.meta?.start as unknown;
+  if (raw === undefined) return;
+  const why = ownsNoWorkspace(tpl);
+  if (why) {
+    add("start-no-workspace", "meta.start", `"${tpl.meta.slug}" is ${why} — it owns no space, so it cannot be an onboarding start`);
+    return;
+  }
+  const isStr = (v: unknown): v is string => typeof v === "string" && v.trim().length > 0;
+  const strList = (v: unknown): v is string[] => Array.isArray(v) && v.every(isStr);
+  const st = raw as Record<string, any>;
+  const fs = st?.firstSession;
+  const shapeOk =
+    !!st && typeof st === "object" && !Array.isArray(st) &&
+    Number.isInteger(st.order) && st.order > 0 && isStr(st.label) && isStr(st.promise) &&
+    strList(st.suggestFor) && isStr(st.profile) && strList(st.views) && strList(st.starters) &&
+    Array.isArray(st.example) && st.example.every((e: any) => e && isStr(e.title) && (e.values === undefined || (typeof e.values === "object" && e.values !== null && !Array.isArray(e.values)))) &&
+    !!fs && isStr(fs.title) && isStr(fs.goal);
+  if (!shapeOk) {
+    add("start-shape", "meta.start", "meta.start must be { order (int ≥ 1), label, promise, suggestFor[], profile, views[], example[{ title, values? }], firstSession{ title, goal }, starters[] }");
+    return;
+  }
+  const start = st as import("./types.ts").TemplateStart;
+  if (start.label.trim().length > INTENT_LABEL_MAX)
+    add("start-label", "meta.start.label", `meta.start.label must be at most ${INTENT_LABEL_MAX} characters (got ${JSON.stringify(start.label)})`);
+  const [exMin, exMax] = START_EXAMPLE_RANGE;
+  if (start.example.length < exMin || start.example.length > exMax)
+    add("start-example-count", "meta.start.example", `meta.start.example needs ${exMin}-${exMax} rows (got ${start.example.length})`);
+  const [stMin, stMax] = START_STARTERS_RANGE;
+  if (start.starters.length < stMin || start.starters.length > stMax)
+    add("start-starters-count", "meta.start.starters", `meta.start.starters needs ${stMin}-${stMax} chips (got ${start.starters.length})`);
+
+  // Views: this template's own, scoped to the produced kind.
+  if (start.views.length < 1 || start.views.length > START_VIEWS_MAX)
+    add("start-views-count", "meta.start.views", `meta.start.views needs 1-${START_VIEWS_MAX} view slugs (got ${start.views.length})`);
+  start.views.forEach((slug, i) => {
+    const at = `meta.start.views[${i}]`;
+    const view = (tpl.views ?? []).find((v) => v.slug === slug);
+    if (!view) {
+      add("start-views-exist", at, `"${slug}" is not a view (by slug) of "${tpl.meta.slug}"`);
+      return;
+    }
+    const scope = [view.scopeProfileSlug, ...(view.scopeProfileSlugs ?? [])].filter(Boolean);
+    if (!scope.includes(start.profile))
+      add("start-views-scope", at, `view "${slug}" is not scoped to "${start.profile}" (scope: ${scope.join(", ") || "none"})`);
+  });
+
+  // Profile + example against the declarations in the closure.
+  const closure = [...collectDependencyClosure(tpl, resolveDep)];
+  const sources = [tpl, ...closure.map(resolveDep).filter((t): t is WorkspaceYaml => !!t)];
+  const decls = sources.flatMap((t) => (t.profiles ?? []).filter((p) => p.slug === start.profile));
+  if (decls.length === 0) {
+    if (!closure.some((d) => !resolveDep(d)))
+      add("start-profile-unknown", "meta.start.profile", `"${start.profile}" is neither declared by "${tpl.meta.slug}" nor by a template it depends on`);
+  } else {
+    const props = new Map(decls.flatMap((p) => p.properties ?? []).map((p) => [p.slug, p] as const));
+    start.example.forEach((row, i) => {
+      for (const [key, value] of Object.entries(row.values ?? {})) {
+        const at = `meta.start.example[${i}].values.${key}`;
+        const prop = props.get(key);
+        if (!prop) add("start-example-property", at, `"${key}" is not a property of "${start.profile}"`);
+        else if (prop.enumValues?.length && !prop.enumValues.includes(value as string))
+          add("start-example-enum", at, `${JSON.stringify(value)} is not one of ${start.profile}.${key}: ${prop.enumValues.join(", ")}`);
+      }
+    });
+  }
+
+  // Catalog-wide: one start per card slot and per identity.
+  const ids = new Set<string>();
+  start.suggestFor.forEach((id, i) => {
+    if (ids.has(id)) add("start-suggest-duplicate", `meta.start.suggestFor[${i}]`, `identity "${id}" is listed twice`);
+    ids.add(id);
+  });
+  for (const other of corpus ?? []) {
+    const o = other.meta?.start;
+    if (!o || other.meta.slug === tpl.meta.slug) continue;
+    if (o.order === start.order)
+      add("start-order-duplicate", "meta.start.order", `order ${start.order} is also used by "${other.meta.slug}"`);
+    for (const id of o.suggestFor ?? [])
+      if (ids.has(id)) add("start-suggest-duplicate", "meta.start.suggestFor", `identity "${id}" is also suggested by "${other.meta.slug}"`);
+  }
+}
+
+/** True when the resolver is backed by a real corpus (it resolves foundation). */
+function hasCorpus(resolveDep: (slug: string) => WorkspaceYaml | undefined): boolean {
+  return resolveDep(SHARED_ROLE_SSOT_SLUG) !== undefined;
+}
+
 // ── The validator ────────────────────────────────────────────────────────────
 
 /**
@@ -284,13 +1308,21 @@ function resolveDepFrom(
  * when `opts.converters` is supplied).
  */
 export function validateTemplate(
-  tpl: WorkspaceYaml,
-  opts: ValidateOptions = {}
+  authored: WorkspaceYaml,
+  authoredOpts: ValidateOptions = {}
 ): ValidateResult {
   const errors: ValidationError[] = [];
   const add = (rule: string, path: string, message: string) =>
     errors.push({ rule, path, message });
 
+  // ── Lifecycle presets ──────────────────────────────────────────────────────
+  // Compile `adopts:` overlays and generate omitted lifecycle `enumValues`
+  // (lifecycle-presets.ts) before any rule reads them — in this template and in
+  // every corpus / dependency template it is compared with.
+  const { template: tpl, problems } = resolveLifecyclePresets(authored);
+  for (const p of problems) add("lifecycle-adopts", p.path, p.message);
+  const opts = withResolvedLifecycles(authoredOpts, authored, tpl);
+
   // ── Required fields ────────────────────────────────────────────────────────
   if (!tpl.meta) add("meta-required", "meta", "Missing required field: meta");
   else {
@@ -311,6 +1343,33 @@ export function validateTemplate(
         );
     }
   }
+  // ── taskIntents ───────────────────────────────────────────────────────────
+  // A template's DECLARED task requirements, each of which must be a slug of the
+  // closed vocabulary. This is the ONE runtime import in this file (the values
+  // cannot be type-only): it is what keeps `taskIntents` from becoming a second
+  // hand-written intent list. The vocabulary is the pod's `capability_intents`
+  // table, mirrored into `@synap-core/types/capability-intents` because the pod
+  // cannot import that package — a parity guard re-derives the pod's seed
+  // migrations there, so a slug added to the pod without a mirror update fails
+  // THAT test rather than silently making every template below invalid.
+  if (tpl.taskIntents !== undefined) {
+    if (!Array.isArray(tpl.taskIntents)) {
+      add(
+        "task-intents-not-an-array",
+        "taskIntents",
+        "taskIntents must be an array of intent slugs"
+      );
+    } else {
+      const unknown = unknownIntents(tpl.taskIntents);
+      for (const slug of unknown) {
+        add(
+          "task-intent-unknown",
+          `taskIntents[${tpl.taskIntents.indexOf(slug)}]`,
+          `"${slug}" is not a known intent. The closed vocabulary is: ${CAPABILITY_INTENTS.join(", ")}.`
+        );
+      }
+    }
+  }
   // A template earns validity by declaring a data-schema profile OR by carrying
   // operational defaults (relation vocabulary / commands / automations). The
   // `base` template is the latter: pod-wide operational config with no
@@ -323,9 +1382,20 @@ export function validateTemplate(
     (tpl.relationDefs && tpl.relationDefs.length > 0) ||
     (tpl.commands && tpl.commands.length > 0) ||
     (tpl.automations && tpl.automations.length > 0);
+  // A PACK (tag `suite`) is never a workspace of its own (founder decision D8,
+  // 2026-09-25): install layers it onto its primary required domain, so it
+  // needs no profile shell — it earns validity by requiring ≥1 workspace.
+  const isPackRequiringDomains =
+    (tpl.meta?.tags ?? []).includes('suite') &&
+    (tpl.dependencies ?? []).some(
+      (d) =>
+        (d.kind ?? 'workspace') === 'workspace' &&
+        (d.relation ?? 'require') === 'require'
+    );
   if (
     (!tpl.profiles || tpl.profiles.length === 0) &&
-    !carriesOperationalDefaults
+    !carriesOperationalDefaults &&
+    !isPackRequiringDomains
   ) {
     add(
       "profiles-required",
@@ -406,6 +1476,49 @@ export function validateTemplate(
     }
   }
 
+  // ── Space package: the space's own code, and the cell that opens it ───────
+  // A package cell installs as `cell:<meta.slug>:<key>` (the pod's
+  // `packageCellTypeKey`). A space whose entry names a namespaced cell its own
+  // template does not build would open "Unknown cell" on every install.
+  const packageCellKeys = new Set<string>();
+  for (const [i, cell] of (tpl.spacePackage?.cells ?? []).entries()) {
+    const at = `spacePackage.cells[${i}]`;
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(cell.key ?? "")) {
+      add("space-package-cell-key", `${at}.key`, "A space package cell needs a kebab-case key");
+    } else if (packageCellKeys.has(cell.key)) {
+      add("space-package-cell-key-duplicate", `${at}.key`, `Space package cell key "${cell.key}" is declared twice`);
+    } else {
+      packageCellKeys.add(cell.key);
+    }
+    const source = cell.source ?? "";
+    if (
+      !source.startsWith("packages/web/src/space-packages/") ||
+      source.split("/").includes("..") ||
+      !/\.tsx?$/.test(source)
+    ) {
+      add(
+        "space-package-cell-source",
+        `${at}.source`,
+        "A space package cell is built from the shared components: its source is a .ts/.tsx file under packages/web/src/space-packages/"
+      );
+    }
+  }
+  const entryCellKeys: Array<[string, string | undefined]> = [
+    ["app.cellKey", tpl.app?.kind === "stored" ? tpl.app.cellKey : undefined],
+    ["layout.primarySurface.cellKey", authoredPrimary?.kind === "cell" ? authoredPrimary.cellKey : undefined],
+  ];
+  for (const [path, cellKey] of entryCellKeys) {
+    if (!cellKey?.startsWith("cell:")) continue;
+    const own = `cell:${tpl.meta?.slug}:`;
+    if (!cellKey.startsWith(own) || !packageCellKeys.has(cellKey.slice(own.length))) {
+      add(
+        "space-package-entry-unknown",
+        path,
+        `"${cellKey}" is not a cell this template installs: declare it in spacePackage.cells (installed as ${own}<key>)`
+      );
+    }
+  }
+
   // ── Referential integrity: build the known-profile predicate ──────────────
   const baseProfileSlugs = collectBaseProfileSlugs(tpl, resolveDepFrom(opts));
   const slugs = new Set((tpl.profiles || []).map((p) => p.slug));
@@ -426,6 +1539,18 @@ export function validateTemplate(
     );
   }
 
+  // ── Reserved slugs ──────────────────────────────────────────────────────
+  // The pod refuses these at every profile write path; a reference to one then
+  // fails referential integrity below, so refusing the declaration is enough.
+  for (const profile of tpl.profiles || []) {
+    if (!RESERVED_PROFILE_SLUGS.has(String(profile.slug).trim().toLowerCase())) continue;
+    add(
+      "profile-slug-reserved",
+      `profiles.${profile.slug}`,
+      `Profile slug "${profile.slug}" is reserved: projects live in the pod's projects table, not as an entity kind. Drop the profile; agents create projects through the project door (synap_create_project) and file entities into one with file_into_project (the belongs_to_project relation).`
+    );
+  }
+
   // Views: structured views need a scope; scoped profiles must resolve.
   for (const v of tpl.views || []) {
     const type = String(v.type || "").toLowerCase();
@@ -489,11 +1614,34 @@ export function validateTemplate(
         `entityLink ${el.sourceProfileSlug}→${el.targetProfileSlug} is missing its \`type\` (the predicate)`
       );
     }
+    // `required` is a boolean or absent. The pod's reconcile marks a link
+    // required on any truthy value and clears it on `false`
+    // (`withRequiredLinkMark`, synap-backend), so `"yes"` or `1` would reach a
+    // pod as a rule nobody wrote as one.
+    const required = (el as { required?: unknown }).required;
+    if (required !== undefined && typeof required !== "boolean") {
+      add(
+        "entitylink-required-not-boolean",
+        "entityLinks",
+        `entityLink ${el.sourceProfileSlug}→${el.targetProfileSlug} (${String(el.type)}) has \`required: ${JSON.stringify(required)}\`; write true or false`
+      );
+    }
   }
 
   const onboarding = tpl.onboarding;
   if (onboarding) {
-    if (typeof onboarding.goal !== "string" || onboarding.goal.trim() === "") {
+    // The brief has two modes. The INTERVIEW (goal / openingQuestions /
+    // doneWhen) needs a persona to run it and something to collect; a
+    // steady-state brief (purpose / anchors / fetch) needs neither — a space
+    // can tell agents how to work in it without ever interviewing anyone.
+    const interview =
+      onboarding.goal !== undefined ||
+      onboarding.openingQuestions !== undefined ||
+      onboarding.doneWhen !== undefined;
+    if (
+      interview &&
+      (typeof onboarding.goal !== "string" || onboarding.goal.trim() === "")
+    ) {
       add(
         "onboarding-goal-empty",
         "onboarding.goal",
@@ -501,8 +1649,9 @@ export function validateTemplate(
       );
     }
     if (
-      typeof onboarding.framing !== "string" ||
-      onboarding.framing.trim() === ""
+      (interview || onboarding.framing !== undefined) &&
+      (typeof onboarding.framing !== "string" ||
+        onboarding.framing.trim() === "")
     ) {
       add(
         "onboarding-framing-empty",
@@ -510,13 +1659,106 @@ export function validateTemplate(
         "onboarding.framing must be a non-empty string"
       );
     }
-    if (!Array.isArray(onboarding.collect) || onboarding.collect.length === 0) {
+    if (
+      (interview || onboarding.collect !== undefined) &&
+      (!Array.isArray(onboarding.collect) || onboarding.collect.length === 0)
+    ) {
       add(
         "onboarding-collect-empty",
         "onboarding.collect",
         "onboarding.collect must contain at least one structured target"
       );
     }
+    if (
+      onboarding.purpose !== undefined &&
+      (typeof onboarding.purpose !== "string" ||
+        onboarding.purpose.trim() === "")
+    ) {
+      add(
+        "onboarding-purpose-empty",
+        "onboarding.purpose",
+        "onboarding.purpose must be a non-empty string"
+      );
+    }
+    if (!interview && !onboarding.purpose) {
+      add(
+        "onboarding-brief-empty",
+        "onboarding",
+        "a brief without an interview (goal) must state its purpose"
+      );
+    }
+
+    const seedTitles = new Map<string, number>();
+    for (const e of tpl.seedEntities || []) {
+      seedTitles.set(e.title, (seedTitles.get(e.title) ?? 0) + 1);
+    }
+    const seedAnswersTo = (ref: string) =>
+      (tpl.seedEntities || []).some(
+        (e) =>
+          `${e.profileSlug}:${e.title}` === ref ||
+          (e.title === ref && seedTitles.get(ref) === 1)
+      );
+    let roots = 0;
+    for (const [i, a] of (onboarding.anchors || []).entries()) {
+      const where = `onboarding.anchors.${i}`;
+      if (!a || typeof a.profileSlug !== "string" || !known(a.profileSlug)) {
+        add(
+          "onboarding-anchor-invalid",
+          where,
+          `anchor references unknown profile "${String(a?.profileSlug)}"`
+        );
+        continue;
+      }
+      if (a.role !== "root" && a.role !== "context") {
+        add(
+          "onboarding-anchor-invalid",
+          `${where}.role`,
+          `anchor role must be "root" or "context"`
+        );
+      }
+      if (a.role === "root") roots++;
+      if (a.seedRef !== undefined && !seedAnswersTo(a.seedRef)) {
+        add(
+          "onboarding-anchor-seedref-unknown",
+          `${where}.seedRef`,
+          `anchor seedRef "${a.seedRef}" names no seed entity (use "kind:Title" or a unique title)`
+        );
+      }
+      if (
+        a.limit !== undefined &&
+        !(Number.isInteger(a.limit) && a.limit > 0)
+      ) {
+        add(
+          "onboarding-anchor-invalid",
+          `${where}.limit`,
+          "anchor limit must be a positive integer"
+        );
+      }
+    }
+    if (roots > 1) {
+      add(
+        "onboarding-anchor-invalid",
+        "onboarding.anchors",
+        "a brief has at most one root anchor"
+      );
+    }
+    for (const [i, f] of (onboarding.fetch || []).entries()) {
+      const hasKind = typeof f?.profileSlug === "string" && f.profileSlug;
+      const hasQuery = typeof f?.query === "string" && f.query.trim();
+      if (!hasKind && !hasQuery) {
+        add(
+          "onboarding-fetch-invalid",
+          `onboarding.fetch.${i}`,
+          "a fetch hint needs a profileSlug or a query"
+        );
+      } else if (hasKind && !known(f.profileSlug!)) {
+        add(
+          "onboarding-fetch-invalid",
+          `onboarding.fetch.${i}.profileSlug`,
+          `fetch hint references unknown profile "${f.profileSlug}"`
+        );
+      }
+    }
 
     const expertise = onboarding.expertise;
     for (const [field, values] of [
@@ -595,6 +1837,13 @@ export function validateTemplate(
         `onboarding.collect target "${c.profileSlug}" keyFields must contain only non-empty strings`
       );
     }
+    if (c.min !== undefined && !(Number.isInteger(c.min) && c.min > 0)) {
+      add(
+        "onboarding-collect-min-invalid",
+        `onboarding.collect.${c.profileSlug}.min`,
+        `onboarding.collect target "${c.profileSlug}" min must be a positive integer`
+      );
+    }
     if (!known(c.profileSlug))
       add(
         "onboarding-ref-unknown",
@@ -602,6 +1851,75 @@ export function validateTemplate(
         `onboarding.collect references unknown profile "${c.profileSlug}"`
       );
   }
+
+  // Template rules — each becomes a rule row in the space; `key` is its
+  // identity across template versions, so it must be present and unique.
+  const ruleKeys = new Set<string>();
+  for (const [i, r] of (tpl.rules || []).entries()) {
+    const where = `rules.${i}`;
+    if (typeof r?.key !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(r.key)) {
+      add(
+        "rule-key-invalid",
+        `${where}.key`,
+        "a template rule needs a kebab-case `key` (its identity across versions)"
+      );
+    } else if (ruleKeys.has(r.key)) {
+      add("rule-key-duplicate", `${where}.key`, `duplicate rule key "${r.key}"`);
+    } else {
+      ruleKeys.add(r.key);
+    }
+    if (typeof r?.intent !== "string" || r.intent.trim() === "") {
+      add(
+        "rule-intent-empty",
+        `${where}.intent`,
+        "a template rule needs a non-empty `intent`"
+      );
+    }
+  }
+
+  // Declared skills — each is LINKED to the space at install, so a malformed
+  // one installs a space that cannot load the skill it was told to trust. The
+  // SHAPE rule is shared with the pod's applier (`validateSpaceSkillDeclaration`)
+  // so author time and install time cannot disagree. A duplicate slug is
+  // rejected: two modes for one skill is an ambiguous declaration, not a merge.
+  const skillSlugs = new Set<string>();
+  for (const [i, s] of (tpl.skills || []).entries()) {
+    const where = `skills.${i}`;
+    const reason = validateSpaceSkillDeclaration(s);
+    if (reason) {
+      add("skill-invalid", where, reason);
+      continue;
+    }
+    if (skillSlugs.has(s.slug)) {
+      add("skill-duplicate", `${where}.slug`, `duplicate skill slug "${s.slug}"`);
+    } else {
+      skillSlugs.add(s.slug);
+    }
+  }
+
+  // ── A LINK needs an INSTALL ──────────────────────────────────────────────
+  // `skills:` names what this space ACTIVATES; `dependencies[]` is what the pod
+  // INSTALLS. A linked skill that no dependency brings — and that is not in the
+  // seeded `system/` namespace, which every pod already has — installs cleanly
+  // and activates NOTHING: a missing dependency is non-fatal by design (the
+  // resolver reports `required-absent` and carries on), so the only symptom is
+  // an agent that never gets the skill. That silence is exactly the failure this
+  // rule makes LOUD, at author time, on every door (build, CLI validate, publish).
+  const installedSkillSlugs = new Set(
+    (tpl.dependencies ?? [])
+      .filter((d) => (d.kind ?? "workspace") === "skill")
+      .map((d) => d.slug)
+  );
+  for (const [i, s] of (tpl.skills || []).entries()) {
+    // `system/…` is the seeded namespace — present on every pod, no install needed.
+    if (s.slug.startsWith("system/")) continue;
+    if (installedSkillSlugs.has(s.slug)) continue;
+    add(
+      "skill-linked-without-install",
+      `skills.${i}.slug`,
+      `"${s.slug}" is LINKED but nothing INSTALLS it — add \`dependencies: [{ slug: ${s.slug}, kind: skill, relation: require }]\` (and publish that skill package), or reference the seeded \`system/…\` namespace instead. As written the install succeeds and the link does NOTHING.`
+    );
+  }
   for (const s of tpl.seedEntities || []) {
     if (!known(s.profileSlug))
       add(
@@ -714,6 +2032,16 @@ export function validateTemplate(
       );
   }
 
+  // ── Shared-role references + step domains (concept consolidation W4a) ─────
+  checkSharedRoleReferences(tpl, resolveDepFrom(opts), add);
+  checkStageDomains(tpl, resolveDepFrom(opts), add);
+  checkProcessContract(tpl, resolveDepFrom(opts), opts.corpus, add);
+  checkLifecycleDeclarations(tpl, resolveDepFrom(opts), opts.corpus, add);
+  checkPresentationDeclarations(tpl, resolveDepFrom(opts), opts.corpus, add);
+  checkIntent(tpl, resolveDepFrom(opts), add);
+  checkStart(tpl, resolveDepFrom(opts), opts.corpus, add);
+  checkPackDependencies(tpl, resolveDepFrom(opts), add);
+
   // ── Overlay-safety: an overlay (compose relation) is layered additively onto
   // its base's workspace. The additive reconcile OVERWRITES workspace-level
   // settings, so an overlay MUST set workspace.subtype to its compose-base's slug