@growthub/cli 0.14.8 → 0.14.10

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-stale-surfaces.js

@@ -0,0 +1,217 @@
+/**
+ * Growthub Workspace Stale-Surfaces V1 — freshness-aware impact deriver.
+ *
+ * Answers the question the spine (`deriveBlastRadius`) cannot answer on its
+ * own: *given the changes the graph already records, which downstream surfaces
+ * are stale RIGHT NOW?* — with no change-event argument required.
+ *
+ * The metadata graph already timestamps the only nodes whose freshness is
+ * observable: `run.ranAt`, `sourceRecord.fetchedAt`, and
+ * `pipelineHealth.latestRanAt`. When one of those upstream nodes changes, the
+ * surfaces that DEPEND on it (its reverse-edge closure) are the surfaces now
+ * showing old data. This module seeds the EXISTING `deriveBlastRadius` closure
+ * from those freshly-changed nodes and labels the reachable dependents stale.
+ *
+ * It builds NO new graph and NO second traversal engine — it composes the
+ * shipped blast-radius deriver and the timestamps the graph already carries.
+ * Pure: no React, no fetch, no fs, no writes, no secrets. Deterministic:
+ * results are ordered (distance → type → id) and the union de-duplicates, so
+ * the output diffs cleanly between calls.
+ *
+ * Relationship to `selectStaleMetadataGroups` (single-hop, group-level): that
+ * selector answers "given THIS change event, which metadata GROUPS reload?".
+ * This deriver answers "given the timestamps already in the graph, which
+ * specific NODES are stale, transitively?". They are complementary; this one
+ * is node-level and needs no caller-supplied event.
+ */
+
+import { deriveBlastRadius } from "./workspace-metadata-impact.js";
+
+const STALE_SURFACES_KIND = "growthub-workspace-stale-surfaces-v1";
+const STALE_SURFACES_VERSION = 1;
+
+const DEFAULT_MAX_NODES = 500;
+
+// Summary fields that observably timestamp a node's last refresh. Ordered by
+// the precision of "this node changed at T". The newest of these wins.
+const FRESHNESS_FIELDS = ["ranAt", "fetchedAt", "latestRanAt"];
+
+function safeString(value) {
+  if (value == null) return "";
+  return typeof value === "string" ? value : String(value);
+}
+
+/**
+ * Parse a node's last-known-fresh timestamp (ms epoch) from its summary, or
+ * null when the node carries no observable freshness. Never throws.
+ */
+function nodeFreshAt(node) {
+  const summary = node && typeof node === "object" ? node.summary : null;
+  if (!summary || typeof summary !== "object") return null;
+  let newest = null;
+  for (const field of FRESHNESS_FIELDS) {
+    const raw = summary[field];
+    if (!raw) continue;
+    const ms = Date.parse(safeString(raw));
+    if (Number.isNaN(ms)) continue;
+    if (newest == null || ms > newest) newest = ms;
+  }
+  return newest;
+}
+
+/**
+ * Compute the surfaces that are stale given the freshness already recorded in
+ * the graph.
+ *
+ * @param {object} graph a `buildWorkspaceMetadataGraph` envelope
+ * @param {object} [options]
+ * @param {string|number} [options.since] only treat nodes changed at/after
+ *        this instant (ISO string or ms epoch) as seeds. Omit to seed from
+ *        every node that carries a freshness timestamp.
+ * @param {string[]} [options.seedIds] explicit seed node ids (e.g. the nodes a
+ *        just-applied PATCH touched). When given, `since` is ignored and these
+ *        ids are the change set — this is the preflight/`plan` entry point.
+ * @param {number} [options.maxNodes=500] hard cap on stale surfaces.
+ * @returns {object} `{ kind, version, since, seeds[], staleSurfaces[], byType, total, truncated, summary, warnings }`
+ */
+function deriveStaleSurfaces(graph, options = {}) {
+  const maxNodes = Number.isFinite(options.maxNodes) && options.maxNodes > 0
+    ? Math.floor(options.maxNodes)
+    : DEFAULT_MAX_NODES;
+
+  const empty = (warning) => ({
+    kind: STALE_SURFACES_KIND,
+    version: STALE_SURFACES_VERSION,
+    since: null,
+    seeds: [],
+    staleSurfaces: [],
+    byType: {},
+    total: 0,
+    truncated: false,
+    summary: "No stale surfaces computed.",
+    warnings: warning ? [warning] : []
+  });
+
+  if (!graph || typeof graph !== "object" || !Array.isArray(graph.nodes)) {
+    return empty("graph missing or malformed");
+  }
+
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+
+  // ── Resolve the change set (the seeds) ──────────────────────────────────
+  let sinceMs = null;
+  let seeds = [];
+  const explicit = Array.isArray(options.seedIds) ? options.seedIds.map(safeString).filter(Boolean) : null;
+
+  if (explicit && explicit.length) {
+    for (const id of explicit) {
+      const node = nodesById.get(id);
+      if (node) seeds.push({ node, changedAtMs: nodeFreshAt(node) });
+    }
+  } else {
+    if (options.since != null) {
+      const raw = options.since;
+      sinceMs = typeof raw === "number" ? raw : Date.parse(safeString(raw));
+      if (Number.isNaN(sinceMs)) sinceMs = null;
+    }
+    for (const node of graph.nodes) {
+      const changedAtMs = nodeFreshAt(node);
+      if (changedAtMs == null) continue;
+      if (sinceMs != null && changedAtMs < sinceMs) continue;
+      seeds.push({ node, changedAtMs });
+    }
+  }
+
+  if (!seeds.length) {
+    const out = empty();
+    out.since = sinceMs;
+    out.summary = "No recently-changed nodes — nothing is stale.";
+    return out;
+  }
+
+  // ── Union the reverse closures of every seed (reuse the spine) ──────────
+  // A downstream node is stale relative to a seed when its own last-fresh
+  // timestamp predates the seed's change (or it carries none — it cannot prove
+  // freshness, so it is reported stale honestly rather than silently fresh).
+  const staleById = new Map();
+  for (const { node: seedNode, changedAtMs } of seeds) {
+    const blast = deriveBlastRadius(graph, seedNode.id, { maxNodes });
+    for (const impacted of blast.impacted) {
+      const target = nodesById.get(impacted.id);
+      const targetFreshAt = nodeFreshAt(target);
+      const isStale = changedAtMs == null
+        ? true
+        : targetFreshAt == null || targetFreshAt < changedAtMs;
+      if (!isStale) continue;
+      const existing = staleById.get(impacted.id);
+      // Keep the nearest / most-recent reason for each stale surface.
+      if (!existing || impacted.distance < existing.distance) {
+        staleById.set(impacted.id, {
+          id: impacted.id,
+          type: impacted.type,
+          label: impacted.label,
+          metadataId: impacted.metadataId,
+          distance: impacted.distance,
+          viaRelation: impacted.viaRelation,
+          staleSinceSeed: seedNode.id,
+          lastFreshAt: targetFreshAt != null ? new Date(targetFreshAt).toISOString() : null
+        });
+      }
+    }
+  }
+
+  let staleSurfaces = Array.from(staleById.values());
+  let truncated = false;
+  if (staleSurfaces.length > maxNodes) {
+    staleSurfaces = staleSurfaces.slice(0, maxNodes);
+    truncated = true;
+  }
+
+  staleSurfaces.sort((a, b) =>
+    a.distance - b.distance ||
+    a.type.localeCompare(b.type) ||
+    a.id.localeCompare(b.id)
+  );
+
+  const byType = {};
+  for (const entry of staleSurfaces) {
+    byType[entry.type] = (byType[entry.type] || 0) + 1;
+  }
+
+  return {
+    kind: STALE_SURFACES_KIND,
+    version: STALE_SURFACES_VERSION,
+    since: sinceMs,
+    seeds: seeds.map(({ node }) => ({ id: node.id, type: node.type, label: node.label, metadataId: node.metadataId })),
+    staleSurfaces,
+    byType,
+    total: staleSurfaces.length,
+    truncated,
+    summary: summarizeStaleSurfaces(seeds, staleSurfaces, byType, truncated),
+    warnings: []
+  };
+}
+
+/**
+ * One human sentence for the inspector chip / preflight line / CLI output.
+ * Pure string assembly — never throws.
+ */
+function summarizeStaleSurfaces(seeds, staleSurfaces, byType, truncated) {
+  if (!staleSurfaces.length) {
+    return `${seeds.length} recent change(s) — no downstream surface is stale.`;
+  }
+  const parts = Object.keys(byType)
+    .sort()
+    .map((type) => `${byType[type]} ${type}`);
+  const tail = truncated ? " (truncated)" : "";
+  return `${seeds.length} recent change(s) leave ${staleSurfaces.length} surface(s) stale: ${parts.join(", ")}${tail}.`;
+}
+
+export {
+  STALE_SURFACES_KIND,
+  STALE_SURFACES_VERSION,
+  DEFAULT_MAX_NODES,
+  deriveStaleSurfaces,
+  summarizeStaleSurfaces,
+  nodeFreshAt
+};

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-workflow-impact.js

@@ -0,0 +1,170 @@
+/**
+ * Growthub Workspace Workflow-Impact V1 — outcome-level impact deriver.
+ *
+ * `deriveBlastRadius` answers "what nodes depend on X?". For a workflow step
+ * the operationally important question is one hop further: *if I change this
+ * step, which RUNS re-execute and which promotable DELIVERABLES go stale?* —
+ * i.e. roll the reverse closure up to the outcome boundary the governance
+ * plane actually cares about (runs, run outputs, output artifacts, and the
+ * `promotable` ones among them).
+ *
+ * This composes two shipped primitives, building NO new graph:
+ *   1. `deriveBlastRadius` (reverse closure) → the workflows + runs that depend
+ *      on the changed step.
+ *   2. `findDependencies` (one forward hop) from each affected run → the
+ *      artifacts that run PRODUCED (`producedArtifact` / `producedRunOutput`),
+ *      which are the deliverables now potentially invalidated.
+ *
+ * Pure, deterministic, bounded, cycle-safe (inherits those from the spine),
+ * secret-free. Output is a compact, ordered view-model for swarm preflight,
+ * the CEO cockpit readiness lens, and the CLI `plan` command.
+ */
+
+import { deriveBlastRadius } from "./workspace-metadata-impact.js";
+import { findDependencies } from "./workspace-metadata-graph.js";
+
+const WORKFLOW_IMPACT_KIND = "growthub-workspace-workflow-impact-v1";
+const WORKFLOW_IMPACT_VERSION = 1;
+
+const DEFAULT_MAX_NODES = 500;
+
+// Node types that represent an end-to-end OUTCOME (vs. an intermediate config
+// node). Reaching one of these means the change has outcome-level consequences.
+const OUTCOME_TYPES = new Set(["run", "runOutput", "outputArtifact", "workflow"]);
+
+// Forward relations from a run to the things it produced.
+const PRODUCTION_RELATIONS = new Set(["producedArtifact", "producedRunOutput", "materializedAs"]);
+
+function safeString(value) {
+  if (value == null) return "";
+  return typeof value === "string" ? value : String(value);
+}
+
+function summarizeNode(node) {
+  if (!node || typeof node !== "object") return null;
+  return { id: node.id, type: node.type, label: node.label, metadataId: node.metadataId };
+}
+
+/**
+ * @param {object} graph a `buildWorkspaceMetadataGraph` envelope
+ * @param {string} originId the metadataId of the step being changed
+ * @param {object} [options]
+ * @param {number} [options.maxNodes=500]
+ * @returns {object} `{ kind, version, origin, affectedRuns[], affectedWorkflows[],
+ *   staleDeliverables[], promotableAtRisk, total, truncated, summary, warnings }`
+ */
+function deriveWorkflowImpact(graph, originId, options = {}) {
+  const maxNodes = Number.isFinite(options.maxNodes) && options.maxNodes > 0
+    ? Math.floor(options.maxNodes)
+    : DEFAULT_MAX_NODES;
+
+  const empty = (warning) => ({
+    kind: WORKFLOW_IMPACT_KIND,
+    version: WORKFLOW_IMPACT_VERSION,
+    origin: null,
+    affectedRuns: [],
+    affectedWorkflows: [],
+    staleDeliverables: [],
+    promotableAtRisk: 0,
+    total: 0,
+    truncated: false,
+    summary: "No workflow impact computed.",
+    warnings: warning ? [warning] : []
+  });
+
+  if (!graph || typeof graph !== "object" || !Array.isArray(graph.nodes)) {
+    return empty("graph missing or malformed");
+  }
+  const id = safeString(originId).trim();
+  if (!id) return empty("originId missing");
+
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const originNode = nodesById.get(id);
+  if (!originNode) return empty(`origin "${id}" not found in graph`);
+
+  // ── 1. reverse closure → affected workflows + runs (reuse the spine) ────
+  const blast = deriveBlastRadius(graph, id, { maxNodes });
+  const affectedRuns = [];
+  const affectedWorkflows = [];
+  for (const impacted of blast.impacted) {
+    if (impacted.type === "run") affectedRuns.push(impacted);
+    else if (impacted.type === "workflow") affectedWorkflows.push(impacted);
+  }
+
+  // ── 2. one forward hop from each affected run → produced deliverables ────
+  const deliverablesById = new Map();
+  let promotableAtRisk = 0;
+  for (const run of affectedRuns) {
+    const produced = findDependencies(graph, run.id);
+    for (const { node, relation } of produced) {
+      if (!PRODUCTION_RELATIONS.has(relation)) continue;
+      if (deliverablesById.has(node.id)) continue;
+      const promotable = Boolean(node.summary && node.summary.promotable);
+      if (promotable) promotableAtRisk += 1;
+      deliverablesById.set(node.id, {
+        id: node.id,
+        type: node.type,
+        label: node.label,
+        metadataId: node.metadataId,
+        viaRun: run.id,
+        viaRelation: relation,
+        promotable
+      });
+    }
+  }
+
+  let staleDeliverables = Array.from(deliverablesById.values());
+  let truncated = blast.truncated;
+  if (staleDeliverables.length > maxNodes) {
+    staleDeliverables = staleDeliverables.slice(0, maxNodes);
+    truncated = true;
+  }
+
+  const order = (a, b) => a.type.localeCompare(b.type) || a.id.localeCompare(b.id);
+  affectedRuns.sort(order);
+  affectedWorkflows.sort(order);
+  staleDeliverables.sort((a, b) =>
+    Number(b.promotable) - Number(a.promotable) || order(a, b)
+  );
+
+  const total = affectedWorkflows.length + affectedRuns.length + staleDeliverables.length;
+
+  return {
+    kind: WORKFLOW_IMPACT_KIND,
+    version: WORKFLOW_IMPACT_VERSION,
+    origin: summarizeNode(originNode),
+    affectedWorkflows,
+    affectedRuns,
+    staleDeliverables,
+    promotableAtRisk,
+    total,
+    truncated,
+    summary: summarizeWorkflowImpact(originNode, affectedWorkflows, affectedRuns, staleDeliverables, promotableAtRisk, truncated),
+    warnings: []
+  };
+}
+
+function summarizeWorkflowImpact(originNode, workflows, runs, deliverables, promotableAtRisk, truncated) {
+  const label = originNode?.label || originNode?.id || "step";
+  if (!workflows.length && !runs.length && !deliverables.length) {
+    return `Changing "${label}" has no outcome-level impact — no workflow, run, or deliverable depends on it.`;
+  }
+  const parts = [];
+  if (workflows.length) parts.push(`${workflows.length} workflow(s)`);
+  if (runs.length) parts.push(`${runs.length} run(s)`);
+  if (deliverables.length) {
+    const promo = promotableAtRisk ? `, ${promotableAtRisk} promotable` : "";
+    parts.push(`${deliverables.length} deliverable(s)${promo}`);
+  }
+  const tail = truncated ? " (truncated)" : "";
+  return `Changing "${label}" reaches ${parts.join(", ")}${tail}.`;
+}
+
+export {
+  WORKFLOW_IMPACT_KIND,
+  WORKFLOW_IMPACT_VERSION,
+  DEFAULT_MAX_NODES,
+  OUTCOME_TYPES,
+  deriveWorkflowImpact,
+  summarizeWorkflowImpact
+};

package/assets/worker-kits/growthub-custom-workspace-starter-v1/kit.json

@@ -107,6 +107,13 @@
     "apps/workspace/lib/workspace-metadata-store.js",
     "apps/workspace/lib/workspace-metadata-graph.js",
     "apps/workspace/lib/workspace-metadata-selectors.js",
+    "apps/workspace/lib/workspace-metadata-impact.js",
+    "apps/workspace/lib/workspace-stale-surfaces.js",
+    "apps/workspace/lib/workspace-workflow-impact.js",
+    "apps/workspace/lib/workspace-provenance-lineage.js",
+    "apps/workspace/lib/workspace-app-readiness.js",
+    "apps/workspace/lib/workspace-contract-compliance.js",
+    "apps/workspace/lib/workspace-patch-impact.js",
     "apps/workspace/app/api/workspace/metadata-graph/route.js",
     "apps/workspace/app/api/workspace/swarm-condition/route.js",
     "apps/workspace/app/data-model/components/WorkspaceGraphInspectorPanel.jsx",

package/assets/worker-kits/growthub-custom-workspace-starter-v1/skills/governed-workspace-mutation/SKILL.md

@@ -161,6 +161,19 @@ Every mutation lane emits the **same canonical receipt** (`@growthub/api-contrac
 
 **First-session continuation:** before acting, read the stream. Cite `receiptId`s, continue from `nextActions`, and inspect `rollbackRef` (previous version + delta index for publishes; sourceId for runs) before redoing anyone's work. Rejections come with `repairPlan[]` — follow it instead of retrying variations.
 
+**Outcome completion:** for regular user work, do not stop at "proposal created" or "run attempted" when the requested business outcome requires deliverables. The completion proof must live in governed state: successful run ids or source ids, connected output rows, durable storage/reference paths where applicable, review status, and a concise documentation/receipt trail. Failed or partial rows stay as evidence, but they do not count as delivered outputs. Human-review states remain explicit; an agent can execute and persist, but it does not silently approve or launch work that requires workspace-admin or super-admin judgment.
+
+## Intelligence layer — graph + blast radius (read-only)
+
+After a mutation lands, the platform **understands** it. Two read-only, secret-free surfaces:
+
+- **World model** — `GET /api/workspace/metadata-graph` projects the live config + source-record sidecar into a typed node/edge graph (`buildWorkspaceMetadataStore → buildWorkspaceMetadataGraph`, `lib/workspace-metadata-graph.js`); the Workspace Map (`/workspace-map`) renders the same graph. Every governed object becomes nodes; every dependency a deterministic edge (`bindsToObject`, `usesField`, `containsWidget`, `readsObject`/`writesObject`, `materializes`, …). A landed mutation expands this graph — the workspace knows more about itself than before.
+- **Causal impact** — the graph ships single-hop `findDependents(graph, nodeId)`; the transitive closure (the real blast radius) is `deriveBlastRadius(graph, nodeId)` in `lib/workspace-metadata-impact.js` — a deterministic, cycle-safe BFS of incoming edges returning every reachable dependent with hop distance and via-relation. This is the difference between *"what directly uses this field?"* (catalog) and *"if this field changes, which widgets, dashboards, and delivered workspace kits go stale?"* (intelligence). Verified live: editing `customers.mrr` → widget (`usesField`) → dashboard (`containsWidget`) → workerKit (`materializes`). Conceptual map: `docs/OPERATING_THE_GOVERNED_UNIVERSE_V1.md` in the source repo.
+
+Both are derived projections — they own no state and mutate nothing. `deriveBlastRadius` is the spine of a pure deriver family (stale surfaces, workflow impact, provenance lineage, app readiness, contract compliance, and `derivePatchImpact` — the shared add/modify/**remove** impact model). Use them to size a change *before* you PATCH (pair with `patch/preflight`) and to explain what an accepted mutation affects.
+
+These same derivers are surfaced to external agents (Codex / Claude Code) through the **agent-facing MCP console** (`growthub serve --mcp`, a CLI surface — note this workspace skill declares no `mcpTools`): **read + dry-run (`preflight_patch`) + governed hand-off (`next_actions`), never a mutation tool.** The console reads this graph, dry-runs against Law, and emits the exact governed call — reality still changes only through the routes above. Canonical contract: `docs/GOVERNED_MCP_CONSOLE_V1.md` in the source repo.
+
 ## Applications as governed entities (Control Plane V1)
 
 Applications are first-class governed objects, not loose files. The source of truth is the `workspace-app-registry` Data Model object (objectType `"app-surface"`, preset ships in the Data Model) — one row per application, referencing its governed parts by id: `dashboardIds`, `workflowRefs` (`objectId:RowName`), `dataSourceIds`, `registryIds`. Rows mutate through the normal PATCH lane (policy + receipts apply).