@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/lib/design/fixtures/foundation.json

@@ -0,0 +1,133 @@
+{
+  "v": 2,
+  "colors": [
+    { "name": "Ink", "value": "#0d0d0d", "dark": "#f5f5f4" },
+    { "name": "Paper", "value": "#ffffff", "dark": "#0b0b0c" },
+    { "name": "Primary · Moss", "value": "#2d5be3", "dark": "#7ea0ff" },
+    { "name": "Muted", "value": "#6b7280" },
+    { "name": "Accent · Amber", "value": "#c9851f" },
+    { "name": "Line", "value": "#e7e5e4", "dark": "#26262a" }
+  ],
+  "fonts": { "display": "Outfit", "body": "Inter", "mono": "JetBrains Mono" },
+  "type": [
+    { "role": "Display", "size": 76, "weight": 600 },
+    { "role": "Heading", "size": 38, "weight": 600 },
+    { "role": "Body", "size": 14, "weight": 400 },
+    { "role": "Small", "size": 11.5, "weight": 500 }
+  ],
+  "space": [
+    { "name": "xs", "value": 4 },
+    { "name": "sm", "value": 8 },
+    { "name": "md", "value": 12 },
+    { "name": "lg", "value": 16 },
+    { "name": "xl", "value": 22 }
+  ],
+  "radii": [
+    { "name": "chip", "value": 8 },
+    { "name": "field", "value": 9 },
+    { "name": "card", "value": 13 },
+    { "name": "modal", "value": 14 },
+    { "name": "pill", "value": 999 }
+  ],
+  "shadow": [
+    { "name": "sm", "value": "0 1px 2px rgba(13,13,13,0.06)" },
+    { "name": "md", "value": "0 18px 50px rgba(13,13,13,0.13)" }
+  ],
+  "border": [
+    { "name": "hairline", "value": "1px solid #e7e5e4" },
+    { "name": "strong", "value": "1px solid #d6d3d1" }
+  ],
+  "voice": "Concise, specific, accountable. Write like a capable peer — no hype, no emoji, no hedging.",
+  "positioning": "The operating system for companies that run on agents as well as people.",
+  "taglines": ["Work that runs itself.", "One company, many hands."],
+  "toneTraits": ["Plain", "Exact", "Unhurried"],
+  "logos": {
+    "brandIcon": "https://assets.example.test/icon.png",
+    "wordmark": "https://assets.example.test/wordmark.svg",
+    "favicon": null
+  },
+  "examples": { "hero": "A crew at first light.", "cta": "Start the walkthrough" },
+  "visualLanguage": {
+    "v": 2,
+    "source": "generated",
+    "imagery": {
+      "needsImagery": true,
+      "medium": "photography",
+      "secondaryMedia": ["diagram"],
+      "colorGrade": "natural",
+      "grain": "fine",
+      "crop": "wide",
+      "aspectRatios": ["16/9", "1/1"],
+      "subjects": ["hands at work", "quiet rooms"],
+      "mood": ["calm", "considered"],
+      "composition": "off-centre, generous negative space",
+      "duotone": { "shadow": "#12213f", "highlight": "#f3ede1" }
+    },
+    "iconography": { "style": "line", "weight": "1.5px", "corner": "rounded", "grid": 24 },
+    "motion": {
+      "character": "settled",
+      "easing": "cubic-bezier(0.2, 0, 0, 1)",
+      "durationMs": 220,
+      "principles": ["Move once, arrive.", "Never animate what a person is reading."]
+    },
+    "texture": { "surfaces": ["paper", "frosted glass"], "background": "flat", "notes": "No gradients behind text." },
+    "guardrails": {
+      "dos": ["Let type carry the page.", "Use one accent per view."],
+      "donts": ["No stock handshakes.", "No drop shadows on text."]
+    },
+    "promptSeed": "quiet rooms, natural light, fine grain",
+    "seedLocked": true,
+    "negativeSeed": "neon, lens flare",
+    "references": ["moodboard/2026-03"]
+  },
+  "system": {
+    "typography": {
+      "families": {
+        "display": { "family": "Outfit", "category": "sans", "weights": [500, 600] },
+        "heading": { "family": "Outfit", "category": "sans", "weights": [600] },
+        "body": { "family": "Inter", "category": "sans", "weights": [400, 500] },
+        "mono": { "family": "JetBrains Mono", "category": "mono", "weights": [400] }
+      },
+      "scale": [
+        { "role": "Display", "size": 76, "weight": 600, "leading": 1.05, "tracking": -0.02 },
+        { "role": "Heading", "size": 38, "weight": 600, "leading": 1.15, "tracking": -0.01 },
+        { "role": "Body", "size": 14, "weight": 400, "leading": 1.5 },
+        { "role": "Caption", "size": 11, "weight": 500, "leading": 1.4, "tracking": 0.04 }
+      ],
+      "pairingRationale": "One geometric face for structure, one humanist face for reading.",
+      "usageRules": ["Display only above 32px.", "Never set body copy below 13px."]
+    },
+    "color": {
+      "roles": {
+        "primary": { "name": "Signal Blue", "value": "#2d5be3", "dark": "#7ea0ff" },
+        "accent": { "name": "Amber", "value": "#c9851f" }
+      },
+      "neutralRamp": [
+        { "step": 100, "value": "#f5f5f4" },
+        { "step": 500, "value": "#78716c" },
+        { "step": 900, "value": "#1c1917" }
+      ],
+      "semantic": { "success": "#177245", "warning": "#c9851f", "danger": "#a11d1d" },
+      "usageRules": ["One primary per view.", "Semantic colour is for state, never decoration."]
+    },
+    "imagery": {
+      "medium": "documentary photography",
+      "style": "unstaged",
+      "treatment": "warm highlights, cool shadows",
+      "mood": "assured",
+      "subjects": ["workshops", "field crews"],
+      "donts": ["stock handshakes", "isolated laptops"]
+    },
+    "motifs": ["A single hairline rule.", "Numbers set in the mono face."],
+    "iconography": "Line icons on a 24px grid, 1.5px stroke.",
+    "layoutPrinciples": ["Left-align everything that reads.", "One idea per band."],
+    "voice": {
+      "voice": "Concise, specific, accountable.",
+      "toneTraits": ["Plain", "Direct"],
+      "lexicon": { "use": ["decide", "ship", "owe"], "avoid": ["leverage", "synergy", "unlock"] },
+      "exampleCopy": "Two invoices need a decision today. Both are under £5,000."
+    }
+  },
+  "elevationCurve": { "0": "none", "1": "0 1px 2px rgba(0,0,0,0.05)" },
+  "gridUnit": 4
+}

package/lib/design/refresh-gate.mjs

@@ -0,0 +1,154 @@
+/**
+ * lib/design/refresh-gate.mjs — WHEN the seat re-syncs its brand foundation
+ * (WP-M7 mechanic 4). Pure; the daemon does the I/O.
+ *
+ * Two triggers, one gate:
+ *
+ *   1. **The foundation moved.** `branding.getFoundation` returns a version id
+ *      (`headVersionId`). A read whose version differs from the one on disk is
+ *      a change, and DESIGN.md must follow it immediately — a designer working
+ *      from a stale palette is the exact failure this whole work package
+ *      exists to prevent.
+ *   2. **The clock.** Absent any signal, poll every 15 minutes. hq has no cheap
+ *      "has the foundation changed?" ETag the way `integration.toolsetVersion`
+ *      does for tools, so the version comparison in (1) can only happen AFTER a
+ *      read — the interval is what bounds how often that read happens.
+ *
+ * The daemon calls this twice per tick: once with `currentVersion` unknown (may
+ * I spend a read?) and once with the version the read returned (did anything
+ * actually change?). That is why `currentVersion` being null/undefined is not a
+ * change — an unknown version must never look like a new one, or every tick
+ * would rewrite the files.
+ *
+ * A `lastAt` in the FUTURE also refreshes: a clock that went backwards must not
+ * be able to freeze the foundation on disk forever.
+ *
+ * Node builtins only (none needed). ESM.
+ *
+ * @module lib/design/refresh-gate
+ */
+
+"use strict";
+
+/** The poll interval, per the design spec: 15 minutes. */
+export const DESIGN_REFRESH_INTERVAL_MS = 15 * 60_000;
+
+/** Where the seat keeps the last synced foundation, relative to the agent root. */
+export const DESIGN_STATE_REL = "state/design/foundation.json";
+
+/** The two generated files, relative to the output directory. */
+export const DESIGN_FILES = ["DESIGN.md", "PRODUCT.md"];
+
+/**
+ * Should the foundation be re-synced now? Pure.
+ *
+ * @param {object} o
+ * @param {string|null} [o.lastVersion]    version id recorded on disk (null = never synced)
+ * @param {string|null} [o.currentVersion] version id just read from hq (null/undefined = not known yet)
+ * @param {string|number|null} [o.lastAt]  when the last sync happened (ISO or epoch ms)
+ * @param {number} o.now                   epoch ms
+ * @param {number} [o.intervalMs]          poll interval (default {@link DESIGN_REFRESH_INTERVAL_MS})
+ * @returns {{refresh:boolean, reason:"never"|"version-changed"|"interval"|"clock-skew"|"fresh"}}
+ */
+export function shouldRefreshDesign(o = {}) {
+  const now = Number.isFinite(o.now) ? o.now : 0;
+  const intervalMs = Number.isFinite(o.intervalMs) && o.intervalMs > 0 ? o.intervalMs : DESIGN_REFRESH_INTERVAL_MS;
+  const last = toMs(o.lastAt);
+  if (last === null) return { refresh: true, reason: "never" };
+  const current = version(o.currentVersion);
+  if (current !== null && current !== version(o.lastVersion)) return { refresh: true, reason: "version-changed" };
+  if (last > now) return { refresh: true, reason: "clock-skew" };
+  if (now - last >= intervalMs) return { refresh: true, reason: "interval" };
+  return { refresh: false, reason: "fresh" };
+}
+
+/**
+ * The version identity of a `branding.getFoundation` result. `headVersionId` is
+ * the etag hq itself uses for compare-and-swap; `version.id` is the fallback
+ * when retention has pruned the head's snapshot row. An org that has never
+ * saved a foundation reads as `"unversioned"` — a stable identity, so an
+ * un-versioned workspace does not re-render on every poll.
+ *
+ * @param {unknown} result the `result` of the read
+ * @returns {string|null} null when the frame carries no foundation at all
+ */
+export function foundationVersion(result) {
+  if (!result || typeof result !== "object") return null;
+  const r = /** @type {Record<string, unknown>} */ (result);
+  if (typeof r.headVersionId === "string" && r.headVersionId) return r.headVersionId;
+  const v = r.version;
+  if (v && typeof v === "object" && typeof (/** @type {any} */ (v).id) === "string" && (/** @type {any} */ (v).id)) {
+    return String(/** @type {any} */ (v).id);
+  }
+  if (r.foundation && typeof r.foundation === "object") return "unversioned";
+  return null;
+}
+
+/**
+ * Has this workspace ever SAVED a brand foundation?
+ *
+ * WHY THIS IS NOT `!result.foundation`. hq never returns a null foundation. An
+ * org that has never saved one reads back `dsDefaults()` — the hq product's own
+ * palette and typefaces — with `unversioned: true` and `headVersionId: null`
+ * (`loadSavedFoundation` → `loadFoundationHead` → `coerceFoundation(null)`). A
+ * caller that guards on the foundation being absent therefore NEVER fires, and
+ * happily renders a DESIGN.md whose own prose calls that palette "the source of
+ * truth for colour, type, radius and spacing". Every design skill on the seat
+ * then grounds on another product's defaults believing they are the brand: a
+ * wrong palette that looks authoritative, which is precisely the failure this
+ * whole work package exists to prevent. So the seat writes nothing until a
+ * human has saved a foundation.
+ *
+ * `unversioned` is trusted when hq states it; an older hq that omits the field
+ * falls back to "no version identity of any kind", which is the same condition.
+ *
+ * @param {unknown} result the `result` of a `branding.getFoundation` read
+ * @returns {boolean}
+ */
+export function isUnversionedFoundation(result) {
+  if (!result || typeof result !== "object") return false;
+  const r = /** @type {Record<string, unknown>} */ (result);
+  if (r.unversioned === true) return true;
+  if (r.unversioned === false) return false;
+  return foundationVersion(r) === "unversioned";
+}
+
+/**
+ * The human label of the read's version, for the provenance footer. `""` when
+ * there is none — the renderer omits the line rather than inventing one.
+ * @param {unknown} result
+ * @returns {string}
+ */
+export function foundationVersionLabel(result) {
+  const v = result && typeof result === "object" ? /** @type {any} */ (result).version : null;
+  if (!v || typeof v !== "object") return "";
+  const label = typeof v.label === "string" ? v.label.trim() : "";
+  const seq = Number.isFinite(v.seq) ? `V2.${v.seq}` : "";
+  return label || seq;
+}
+
+/** ISO string or epoch ms → epoch ms, or null. */
+function toMs(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.trim()) {
+    const n = Date.parse(v);
+    if (Number.isFinite(n)) return n;
+  }
+  return null;
+}
+
+/** A version id as a comparable string, or null. */
+function version(v) {
+  if (typeof v === "string" && v) return v;
+  return null;
+}
+
+export default {
+  shouldRefreshDesign,
+  foundationVersion,
+  isUnversionedFoundation,
+  foundationVersionLabel,
+  DESIGN_REFRESH_INTERVAL_MS,
+  DESIGN_STATE_REL,
+  DESIGN_FILES,
+};

package/lib/design/refresh-gate.test.mjs

@@ -0,0 +1,144 @@
+/**
+ * refresh-gate.test.mjs — WHEN a seat re-syncs its brand foundation
+ * (WP-M7 mechanic 4). The gate is pure, so every case here is a table row.
+ *
+ * The two rules worth stating in prose because they are the ones a reader
+ * would get wrong:
+ *
+ *   · An UNKNOWN current version is not a change. The daemon asks the gate
+ *     twice per tick — before the read (version unknown) and after it — and if
+ *     "unknown" counted as a new version, the pre-read call would say yes on
+ *     every tick and the interval would mean nothing.
+ *   · A `lastAt` in the FUTURE refreshes. A clock that jumped backwards (or a
+ *     state file copied from another box) must not be able to freeze DESIGN.md
+ *     on disk until the wall clock catches up.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  isUnversionedFoundation,
+  shouldRefreshDesign,
+  foundationVersion,
+  foundationVersionLabel,
+  DESIGN_REFRESH_INTERVAL_MS,
+  DESIGN_STATE_REL,
+  DESIGN_FILES,
+} from "./refresh-gate.mjs";
+
+const NOW = Date.parse("2026-09-08T12:00:00Z");
+
+test("the interval is 15 minutes and the paths are the ones the CLI and daemon write", () => {
+  assert.equal(DESIGN_REFRESH_INTERVAL_MS, 15 * 60_000);
+  assert.equal(DESIGN_STATE_REL, "state/design/foundation.json");
+  assert.deepEqual(DESIGN_FILES, ["DESIGN.md", "PRODUCT.md"]);
+});
+
+test("never synced → refresh", () => {
+  assert.deepEqual(shouldRefreshDesign({ now: NOW }), { refresh: true, reason: "never" });
+  assert.deepEqual(shouldRefreshDesign({ lastAt: null, now: NOW }), { refresh: true, reason: "never" });
+  assert.deepEqual(shouldRefreshDesign({ lastAt: "not a date", now: NOW }), { refresh: true, reason: "never" });
+});
+
+test("inside the interval with an unchanged version → no refresh", () => {
+  assert.deepEqual(
+    shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - 60_000, now: NOW }),
+    { refresh: false, reason: "fresh" },
+  );
+});
+
+test("a changed version refreshes immediately, however recent the last sync", () => {
+  assert.deepEqual(
+    shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_2", lastAt: NOW - 1_000, now: NOW }),
+    { refresh: true, reason: "version-changed" },
+  );
+  // First-ever version on a seat that had synced an unversioned org.
+  assert.deepEqual(
+    shouldRefreshDesign({ lastVersion: null, currentVersion: "bv_1", lastAt: NOW - 1_000, now: NOW }),
+    { refresh: true, reason: "version-changed" },
+  );
+});
+
+test("an UNKNOWN current version is not a change — the pre-read call must not always say yes", () => {
+  for (const currentVersion of [null, undefined, "", 7, {}]) {
+    assert.deepEqual(
+      shouldRefreshDesign({ lastVersion: "bv_1", currentVersion, lastAt: NOW - 60_000, now: NOW }),
+      { refresh: false, reason: "fresh" },
+      `currentVersion=${JSON.stringify(currentVersion)}`,
+    );
+  }
+});
+
+test("the interval fires at the boundary and after it, not before", () => {
+  const at = (dt) => shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - dt, now: NOW });
+  assert.equal(at(DESIGN_REFRESH_INTERVAL_MS - 1).refresh, false);
+  assert.deepEqual(at(DESIGN_REFRESH_INTERVAL_MS), { refresh: true, reason: "interval" });
+  assert.deepEqual(at(DESIGN_REFRESH_INTERVAL_MS * 10), { refresh: true, reason: "interval" });
+});
+
+test("a lastAt in the future refreshes rather than freezing the seat", () => {
+  assert.deepEqual(
+    shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW + 86_400_000, now: NOW }),
+    { refresh: true, reason: "clock-skew" },
+  );
+});
+
+test("lastAt is accepted as an ISO string or epoch ms", () => {
+  const iso = shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: "2026-09-08T11:59:00Z", now: NOW });
+  const ms = shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - 60_000, now: NOW });
+  assert.deepEqual(iso, ms);
+});
+
+test("a bad or absent intervalMs falls back to the 15-minute default", () => {
+  for (const intervalMs of [undefined, null, 0, -5, NaN, "soon"]) {
+    const r = shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - 14 * 60_000, now: NOW, intervalMs });
+    assert.equal(r.refresh, false, `intervalMs=${String(intervalMs)}`);
+  }
+  assert.equal(
+    shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - 60_000, now: NOW, intervalMs: 30_000 }).reason,
+    "interval",
+    "an explicit shorter interval is honoured",
+  );
+});
+
+test("foundationVersion prefers headVersionId, then version.id, then a stable 'unversioned'", () => {
+  assert.equal(foundationVersion({ headVersionId: "bv_1", version: { id: "bv_0" }, foundation: {} }), "bv_1");
+  assert.equal(foundationVersion({ headVersionId: null, version: { id: "bv_0" }, foundation: {} }), "bv_0");
+  assert.equal(foundationVersion({ headVersionId: null, version: null, foundation: {} }), "unversioned");
+  assert.equal(foundationVersion({}), null, "a frame with no foundation has no version identity");
+  assert.equal(foundationVersion(null), null);
+  assert.equal(foundationVersion("nope"), null);
+});
+
+test("'unversioned' is STABLE, so an org that never saved a foundation does not re-render every poll", () => {
+  const frame = { headVersionId: null, version: null, foundation: { colors: [] } };
+  const v = foundationVersion(frame);
+  assert.equal(shouldRefreshDesign({ lastVersion: v, currentVersion: foundationVersion(frame), lastAt: NOW - 60_000, now: NOW }).refresh, false);
+});
+
+test("foundationVersionLabel reads the label, falls back to V2.<seq>, and never invents", () => {
+  assert.equal(foundationVersionLabel({ version: { label: "Palette refresh", seq: 7 } }), "Palette refresh");
+  assert.equal(foundationVersionLabel({ version: { seq: 7 } }), "V2.7");
+  assert.equal(foundationVersionLabel({ version: { label: "   " } }), "");
+  assert.equal(foundationVersionLabel({ version: null }), "");
+  assert.equal(foundationVersionLabel(null), "");
+});
+
+test("isUnversionedFoundation catches the frame hq ACTUALLY sends for a workspace with no brand", () => {
+  // hq's `loadSavedFoundation` falls back to `dsDefaults()`, so the foundation
+  // is never null. `unversioned` is the only truthful signal, and an older hq
+  // that omits it is judged by having no version identity at all.
+  const stock = { foundation: { colors: [] }, version: null, headVersionId: null, unversioned: true };
+  assert.equal(isUnversionedFoundation(stock), true);
+  assert.equal(isUnversionedFoundation({ ...stock, unversioned: undefined }), true, "older hq: no version identity of any kind");
+
+  const saved = { foundation: { colors: [] }, version: { id: "bv_1", seq: 3 }, headVersionId: "bv_1", unversioned: false };
+  assert.equal(isUnversionedFoundation(saved), false);
+  // hq is trusted when it states the field, even where retention pruned the
+  // snapshot row and only the etag survives.
+  assert.equal(isUnversionedFoundation({ foundation: {}, version: null, headVersionId: "bv_9", unversioned: false }), false);
+
+  assert.equal(isUnversionedFoundation(null), false, "an absent frame is a read failure, not an unversioned workspace");
+  assert.equal(isUnversionedFoundation({}), false);
+});