@growthub/cli 0.14.9 → 0.14.10

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

@@ -108,6 +108,12 @@
     "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

@@ -170,7 +170,9 @@ After a mutation lands, the platform **understands** it. Two read-only, secret-f
 - **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. Use them to size a change *before* you PATCH (pair with `patch/preflight`) and to explain what an accepted mutation affects.
+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)