@hobocode/thought-layer 0.7.0 → 0.8.6

package/core/notion.ts

@@ -0,0 +1,438 @@
+// Pure mapping from a ProgressState (+ the delivered-artifacts manifest) to a
+// Notion "wiki" plan: a root page, one child page per workflow area, and an
+// Artifacts database. No fetch, no fs - the notion-io layer turns this plan into
+// API calls. Kept pure so the block construction and the API-limit chunking are
+// unit-testable without a token.
+//
+// Notion API limits this encodes: rich_text content max 2000 chars (chunkRichText),
+// at most 100 children per append (chunkChildren), and at most 2 levels of block
+// nesting per create/append (withinDepth guards it; we keep tables/toggles to one
+// nested level). Notion has no upsert, so the io layer find-or-creates by stored id.
+
+import { computeProjection, fmtMoney, type Assumptions } from "./model.ts";
+import {
+  brandGuideMarkdown, requirementsMarkdown, glossaryMarkdown, swotMarkdown,
+  type Brand, type Grill, type Swot, type ArtifactManifest,
+} from "./artifacts.ts";
+import type { ProgressState } from "./progress.ts";
+
+// Notion's free-tier single-file upload ceiling. Larger files link to GitHub.
+export const NOTION_FREE_FILE_LIMIT = 5 * 1024 * 1024;
+const RICH_TEXT_MAX = 2000;
+const CHILDREN_MAX = 100;
+
+export type Annotations = Partial<Record<"bold" | "italic" | "strikethrough" | "underline" | "code", boolean>> & { color?: string };
+export interface RichText { type: "text"; text: { content: string; link?: { url: string } | null }; annotations?: Annotations; }
+export type Block = Record<string, unknown>;
+
+const obj = (v: unknown): Record<string, unknown> => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+// ---- rich text (with the 2000-char split) ------------------------------------
+
+const rtSeg = (content: string, ann?: Annotations, link?: string): RichText => ({
+  type: "text",
+  text: { content, ...(link ? { link: { url: link } } : {}) },
+  ...(ann ? { annotations: ann } : {}),
+});
+
+// Split a string into rich_text segments no longer than 2000 chars each.
+export function chunkRichText(text: string, ann?: Annotations, link?: string): RichText[] {
+  const s = String(text ?? "");
+  if (s.length <= RICH_TEXT_MAX) return [rtSeg(s, ann, link)];
+  const out: RichText[] = [];
+  for (let i = 0; i < s.length; i += RICH_TEXT_MAX) out.push(rtSeg(s.slice(i, i + RICH_TEXT_MAX), ann, link));
+  return out;
+}
+
+// Minimal inline markdown: **bold** and `code`. Everything else is plain text.
+// Every segment is itself chunked to the 2000-char limit.
+function inline(text: string): RichText[] {
+  const out: RichText[] = [];
+  const re = /\*\*([^*]+)\*\*|`([^`]+)`/g;
+  let last = 0;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text))) {
+    if (m.index > last) out.push(...chunkRichText(text.slice(last, m.index)));
+    if (m[1] != null) out.push(...chunkRichText(m[1], { bold: true }));
+    else if (m[2] != null) out.push(...chunkRichText(m[2], { code: true }));
+    last = re.lastIndex;
+  }
+  if (last < text.length) out.push(...chunkRichText(text.slice(last)));
+  return out.length ? out : [rtSeg("")];
+}
+
+// ---- block builders ----------------------------------------------------------
+
+const para = (text: string): Block => ({ object: "block", type: "paragraph", paragraph: { rich_text: inline(text) } });
+const heading = (level: 1 | 2 | 3, text: string): Block => {
+  const t = `heading_${level}`;
+  return { object: "block", type: t, [t]: { rich_text: inline(text) } };
+};
+const bullet = (text: string): Block => ({ object: "block", type: "bulleted_list_item", bulleted_list_item: { rich_text: inline(text) } });
+const numbered = (text: string): Block => ({ object: "block", type: "numbered_list_item", numbered_list_item: { rich_text: inline(text) } });
+const quote = (text: string): Block => ({ object: "block", type: "quote", quote: { rich_text: inline(text) } });
+const callout = (text: string, emoji = "💡"): Block => ({ object: "block", type: "callout", callout: { rich_text: inline(text), icon: { type: "emoji", emoji } } });
+const divider = (): Block => ({ object: "block", type: "divider", divider: {} });
+const codeBlock = (text: string, language = "plain text"): Block => ({ object: "block", type: "code", code: { rich_text: chunkRichText(text), language } });
+export const bookmark = (url: string): Block => ({ object: "block", type: "bookmark", bookmark: { url } });
+export const externalImage = (url: string): Block => ({ object: "block", type: "image", image: { type: "external", external: { url } } });
+
+function table(headers: string[], rows: string[][]): Block {
+  const toRow = (cells: string[]): Block => ({ object: "block", type: "table_row", table_row: { cells: cells.map((c) => chunkRichText(c)) } });
+  return {
+    object: "block",
+    type: "table",
+    table: { table_width: headers.length, has_column_header: true, has_row_header: false, children: [toRow(headers), ...rows.map(toRow)] },
+  };
+}
+
+// ---- markdown -> blocks (the workhorse; all artifacts are markdown) ----------
+
+export function markdownToBlocks(md: string): Block[] {
+  const lines = String(md ?? "").split("\n");
+  const out: Block[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const raw = lines[i] ?? "";
+    const t = raw.trim();
+    if (t.startsWith("```")) {
+      const buf: string[] = [];
+      i++;
+      while (i < lines.length && !(lines[i] ?? "").trim().startsWith("```")) { buf.push(lines[i] ?? ""); i++; }
+      i++; // skip closing fence
+      out.push(codeBlock(buf.join("\n")));
+      continue;
+    }
+    if (!t) { i++; continue; }
+    if (t === "---" || t === "***" || t === "___") { out.push(divider()); i++; continue; }
+    const mh = t.match(/^(#{1,6})\s+(.*)$/);
+    if (mh) { out.push(heading(Math.min(3, mh[1]!.length) as 1 | 2 | 3, mh[2]!)); i++; continue; }
+    if (t.startsWith("> ")) { out.push(quote(t.slice(2))); i++; continue; }
+    const mb = t.match(/^[-*]\s+(.*)$/);
+    if (mb) { out.push(bullet(mb[1]!)); i++; continue; }
+    const mn = t.match(/^\d+\.\s+(.*)$/);
+    if (mn) { out.push(numbered(mn[1]!)); i++; continue; }
+    out.push(para(t));
+    i++;
+  }
+  return out;
+}
+
+// ---- blocks -> markdown (the inverse; the agent-replayable wiki plan) ---------
+
+// Reverse rich_text segments to inline markdown. Adjacent segments that share
+// formatting are merged first (undoing the 2000-char split), so a long bold run
+// renders as one **...** rather than several.
+function richTextToMarkdown(rt: RichText[]): string {
+  if (!rt || !rt.length) return "";
+  const sig = (s: RichText): string => {
+    const a = s.annotations || {};
+    return `${a.bold ? 1 : 0}${a.italic ? 1 : 0}${a.code ? 1 : 0}|${s.text.link?.url || ""}`;
+  };
+  const merged: RichText[] = [];
+  for (const s of rt) {
+    const prev = merged[merged.length - 1];
+    if (prev && sig(prev) === sig(s)) prev.text.content += s.text.content;
+    else merged.push({ type: "text", text: { content: s.text.content, ...(s.text.link ? { link: s.text.link } : {}) }, ...(s.annotations ? { annotations: { ...s.annotations } } : {}) });
+  }
+  return merged
+    .map((seg) => {
+      const a = seg.annotations || {};
+      let t = seg.text.content;
+      if (a.code) t = "`" + t + "`";
+      else {
+        if (a.bold) t = `**${t}**`;
+        if (a.italic) t = `*${t}*`;
+      }
+      const link = seg.text.link?.url;
+      return link ? `[${t}](${link})` : t;
+    })
+    .join("");
+}
+
+// The plain (unformatted) concatenation of a rich_text run, for code blocks and
+// table cells where inline markdown would be wrong.
+function richTextToPlain(rt: RichText[]): string {
+  return (rt || []).map((s) => s.text.content).join("");
+}
+
+function tableToMarkdown(tbl: Record<string, unknown>): string {
+  const rows = ((tbl["children"] as Block[]) || []).map((r) =>
+    (((obj(r["table_row"])["cells"]) as RichText[][]) || []).map((c) =>
+      richTextToPlain(c).replace(/\|/g, "\\|").replace(/\n+/g, " ").trim(),
+    ),
+  );
+  if (!rows.length) return "";
+  const width = Math.max(...rows.map((r) => r.length));
+  const pad = (r: string[]): string[] => { const c = r.slice(); while (c.length < width) c.push(""); return c; };
+  const line = (cells: string[]): string => `| ${cells.join(" | ")} |`;
+  const [header, ...body] = rows;
+  const out = [line(pad(header!)), line(pad(header!).map(() => "---"))];
+  for (const r of body) out.push(line(pad(r)));
+  return out.join("\n");
+}
+
+// Render a flat block array back to GitHub-flavored markdown: the inverse of
+// markdownToBlocks plus the synthesized blocks buildWikiPlan adds (callouts,
+// tables). Consecutive list items stay tight; other blocks get a blank line.
+export function blocksToMarkdown(blocks: Block[]): string {
+  const isList = (t: string): boolean => t === "bulleted_list_item" || t === "numbered_list_item";
+  const parts: string[] = [];
+  let prevType = "";
+  let numbered = 0;
+  for (const b of blocks || []) {
+    const type = str(b["type"]);
+    const data = obj(b[type]);
+    const rt = (data["rich_text"] as RichText[]) || [];
+    if (type !== "numbered_list_item") numbered = 0;
+    let rendered: string;
+    switch (type) {
+      case "heading_1": rendered = `# ${richTextToMarkdown(rt)}`; break;
+      case "heading_2": rendered = `## ${richTextToMarkdown(rt)}`; break;
+      case "heading_3": rendered = `### ${richTextToMarkdown(rt)}`; break;
+      case "bulleted_list_item": rendered = `- ${richTextToMarkdown(rt)}`; break;
+      case "numbered_list_item": rendered = `${++numbered}. ${richTextToMarkdown(rt)}`; break;
+      case "quote": rendered = `> ${richTextToMarkdown(rt)}`; break;
+      case "callout": {
+        const emoji = str(obj(data["icon"])["emoji"]);
+        rendered = `> ${emoji ? `${emoji} ` : ""}${richTextToMarkdown(rt)}`;
+        break;
+      }
+      case "divider": rendered = "---"; break;
+      case "code": {
+        const lang = str(data["language"]);
+        rendered = "```" + (lang && lang !== "plain text" ? lang : "") + "\n" + richTextToPlain(rt) + "\n```";
+        break;
+      }
+      case "table": rendered = tableToMarkdown(data); break;
+      case "bookmark": rendered = str(data["url"]); break;
+      case "image": { const u = str(obj(data["external"])["url"]); rendered = u ? `![](${u})` : ""; break; }
+      case "paragraph": rendered = richTextToMarkdown(rt); break;
+      default: rendered = richTextToMarkdown(rt);
+    }
+    if (!rendered && type !== "divider") continue;
+    const sep = parts.length === 0 ? "" : isList(type) && isList(prevType) ? "\n" : "\n\n";
+    parts.push(sep + rendered);
+    prevType = type;
+  }
+  return parts.join("");
+}
+
+// ---- API-limit helpers (unit-tested) -----------------------------------------
+
+// Split a children array into <=100-block append batches.
+export function chunkChildren(blocks: Block[], size = CHILDREN_MAX): Block[][] {
+  const out: Block[][] = [];
+  for (let i = 0; i < blocks.length; i += size) out.push(blocks.slice(i, i + size));
+  return out.length ? out : [[]];
+}
+
+// True when no block nests deeper than maxDepth levels (Notion allows 2 per
+// create/append). We keep tables/toggles to a single nested level, so this holds.
+export function withinDepth(blocks: Block[], maxDepth = 2): boolean {
+  const depth = (bs: Block[], d: number): number => {
+    let max = d;
+    for (const b of bs) {
+      const t = b["type"] as string;
+      const inner = (obj(b[t])["children"]) as Block[] | undefined;
+      if (Array.isArray(inner) && inner.length) max = Math.max(max, depth(inner, d + 1));
+    }
+    return max;
+  };
+  return depth(blocks, 1) <= maxDepth;
+}
+
+// ---- artifact references (link vs upload decision) ---------------------------
+
+export function artifactCategory(path: string): string {
+  if (path.startsWith("Brand/")) return "Brand";
+  if (path.startsWith("Deploy/")) return "Deploy";
+  if (path.startsWith("LandingPage/")) return "Landing";
+  if (path.endsWith(".svg")) return "Infographic";
+  if (path === "BuildPrompt.md") return "Build prompt";
+  return "Doc";
+}
+
+// Decide how an artifact appears in the wiki: upload to Notion when small enough
+// and an uploadable type, else link to its GitHub copy.
+export function artifactRef(bytes: number, hasGithubUrl: boolean): "upload" | "link" {
+  return bytes <= NOTION_FREE_FILE_LIMIT && !hasGithubUrl ? "upload" : hasGithubUrl ? "link" : "upload";
+}
+
+// ---- the wiki plan -----------------------------------------------------------
+
+export interface WikiArtifact { name: string; path: string; category: string; bytes: number; url?: string; }
+export interface WikiArea { key: string; title: string; emoji: string; blocks: Block[]; }
+export interface WikiPlan { title: string; icon: string; overview: Block[]; areas: WikiArea[]; artifacts: WikiArtifact[]; }
+
+export interface WikiBuildOptions {
+  manifest?: ArtifactManifest | null;
+  urls?: Record<string, string>; // artifact relpath -> GitHub blob URL
+}
+
+// The 8 workflow areas, in order, with their emoji.
+export const WIKI_AREAS: Array<{ key: string; title: string; emoji: string }> = [
+  { key: "big-idea", title: "The Big Idea", emoji: "💡" },
+  { key: "business-model", title: "Business Model", emoji: "💰" },
+  { key: "brand", title: "Brand", emoji: "🎨" },
+  { key: "market-research", title: "Market Research", emoji: "📊" },
+  { key: "strategy", title: "Strategy", emoji: "📈" },
+  { key: "product", title: "Product (PRD)", emoji: "📋" },
+  { key: "compliance", title: "Compliance & Tax", emoji: "⚖️" },
+  { key: "decision-science", title: "Decision Science", emoji: "🧭" },
+  { key: "library", title: "Library", emoji: "📚" },
+];
+
+export function buildWikiPlan(state: ProgressState, opts: WikiBuildOptions = {}): WikiPlan {
+  const answers = obj(state.answers);
+  const brand = (state.brand && typeof state.brand === "object" ? state.brand : null) as Brand | null;
+  const guide = brand?.guide || null;
+  const grill = (state.grill && typeof state.grill === "object" ? state.grill : null) as Grill | null;
+  const swot = (state.swot && typeof state.swot === "object" ? state.swot : null) as Swot | null;
+  const prd = obj(state.prd);
+  const bizModel = obj(state.bizModel);
+  const research = obj(state.research);
+  const assumptions = (bizModel["assumptions"] || null) as Assumptions | null;
+  const brandName = str(guide?.brandName) || "Your Product";
+  const oneLiner = str(answers["what-statement"]) || str(answers["pitch"]) || str(guide?.positioning);
+
+  const overview: Block[] = [];
+  if (oneLiner) overview.push(callout(oneLiner, "💡"));
+  overview.push(para("This private workspace was generated by The Thought Layer. Each section below is a page; the Artifacts database links the files delivered to your repo."));
+
+  const areaBlocks: Record<string, Block[]> = {};
+
+  // Big idea: the one-liner, positioning, and the press release if present.
+  {
+    const b: Block[] = [];
+    if (oneLiner) b.push(heading(2, "What it is"), callout(oneLiner, "🎯"));
+    if (guide?.positioning) b.push(heading(2, "Who it is for"), para(guide.positioning));
+    const press = str(answers["press-release"]);
+    if (press) b.push(heading(2, "The press release"), ...markdownToBlocks(press));
+    areaBlocks["big-idea"] = b;
+  }
+
+  // Business model: a parties table + the projection summary.
+  {
+    const b: Block[] = [];
+    const proj = computeProjection(assumptions);
+    if (proj && assumptions) {
+      const s = proj.summary;
+      const cur = assumptions.currency || "USD";
+      b.push(heading(2, "The numbers"));
+      b.push(callout(
+        `Year 1 revenue ${fmtMoney(s.year1Revenue, cur)}. Monthly break-even ${s.breakEvenMonth ? `month ${s.breakEvenMonth}` : "beyond horizon"}. Max cash drawdown ${fmtMoney(s.maxDrawdown, cur)}. MRR at month ${s.horizon} is ${fmtMoney(s.endingMRR, cur)}.`,
+        "💰",
+      ));
+      const rows = (assumptions.parties || []).slice(0, 12).map((p) => [
+        str(p.name) || p.id, str(p.role), String(p.startingCount ?? ""), String(p.monthlyNewBase ?? ""),
+        `${p.monthlyChurnPct ?? 0}%`, fmtMoney(Number(p.revenuePerUnitPerMonth) || 0, cur), fmtMoney(Number(p.cacPerUnit) || 0, cur),
+      ]);
+      b.push(heading(2, "Parties"), table(["Party", "Role", "Start", "New/mo", "Churn", "Rev/unit/mo", "CAC"], rows));
+      if (assumptions.narrative) b.push(heading(2, "Notes"), para(assumptions.narrative));
+    }
+    areaBlocks["business-model"] = b;
+  }
+
+  // Brand: the style guide rendered natively, plus a palette table.
+  {
+    const b: Block[] = [];
+    if (guide) {
+      b.push(...markdownToBlocks(brandGuideMarkdown(guide)));
+      const pal = (guide.palette || []).filter((p) => p?.hex);
+      if (pal.length) b.push(heading(2, "Palette"), table(["Color", "Hex", "Role"], pal.map((p) => [str(p.name), str(p.hex), str(p.role)])));
+    }
+    areaBlocks["brand"] = b;
+  }
+
+  // Market research.
+  {
+    const b: Block[] = [];
+    const brief = str(research["brief"]);
+    if (brief) {
+      const desc = str(research["description"]);
+      if (desc) b.push(callout(desc, "📊"));
+      b.push(...markdownToBlocks(brief));
+    }
+    areaBlocks["market-research"] = b;
+  }
+
+  // Strategy: the SWOT.
+  {
+    const b: Block[] = [];
+    const hasSwot = !!swot && Object.values(swot).some((v) => Array.isArray(v) && v.some((x) => x && String(x).trim()));
+    if (hasSwot) b.push(...markdownToBlocks(swotMarkdown(swot)));
+    areaBlocks["strategy"] = b;
+  }
+
+  // Product: the PRD, requirements, and glossary.
+  {
+    const b: Block[] = [];
+    const prdMd = str(prd["markdown"]);
+    if (prdMd) b.push(...markdownToBlocks(prdMd));
+    if (grill?.requirements?.length) { b.push(divider()); b.push(...markdownToBlocks(requirementsMarkdown(grill))); }
+    if (grill?.glossary?.length) { b.push(divider()); b.push(...markdownToBlocks(glossaryMarkdown(grill))); }
+    areaBlocks["product"] = b;
+  }
+
+  // Compliance: the researched GRC, licensing, and tax report (from the
+  // thought-layer-compliance skill). The report carries its own disclaimer.
+  {
+    const b: Block[] = [];
+    const report = str(obj(state.governance)["report"]);
+    if (report.trim()) b.push(...markdownToBlocks(report));
+    areaBlocks["compliance"] = b;
+  }
+
+  // Decision science: any dq-* / decision-* answers.
+  {
+    const b: Block[] = [];
+    const dq = Object.keys(answers).filter((k) => /^(dq|decision)/i.test(k) && str(answers[k]).trim());
+    if (dq.length) { b.push(heading(2, "Decision records")); for (const k of dq) b.push(bullet(`**${k}**: ${str(answers[k])}`)); }
+    areaBlocks["decision-science"] = b;
+  }
+
+  // Library: no structured data in state; left empty (the io layer skips empties).
+  areaBlocks["library"] = [];
+
+  const areas: WikiArea[] = WIKI_AREAS
+    .map((a) => ({ ...a, blocks: areaBlocks[a.key] || [] }))
+    .filter((a) => a.blocks.length > 0);
+
+  // Artifacts for the database: skip the landing-page SEO sidecars (keep only
+  // index.html), keep everything else.
+  const urls = opts.urls || {};
+  const files = opts.manifest?.files || [];
+  const artifacts: WikiArtifact[] = files
+    .filter((f) => !(f.path.startsWith("LandingPage/") && f.path !== "LandingPage/index.html"))
+    .map((f) => ({ name: f.path, path: f.path, category: artifactCategory(f.path), bytes: f.bytes, ...(urls[f.path] ? { url: urls[f.path] } : {}) }));
+
+  return { title: `${brandName} workspace`, icon: "🚀", overview, areas, artifacts };
+}
+
+// ---- the agent-replayable plan (markdown per area; no token, no network) ------
+
+export interface WikiPlanArea { key: string; title: string; emoji: string; markdown: string; }
+export interface WikiPlanMarkdown {
+  title: string;
+  icon: string;
+  overview: string;
+  areas: WikiPlanArea[];
+  artifacts: WikiArtifact[];
+}
+
+// Render a WikiPlan to per-area markdown so an agent that already holds a Notion
+// MCP can replay it (create a root page, one child page per area, an Artifacts
+// database) without the kit ever touching Notion or needing a token. The token
+// path (notion-io) renders the same plan as native blocks; this is the same
+// content, one canonical plan with two executors.
+export function wikiPlanToMarkdown(plan: WikiPlan): WikiPlanMarkdown {
+  return {
+    title: plan.title,
+    icon: plan.icon,
+    overview: blocksToMarkdown(plan.overview),
+    areas: plan.areas.map((a) => ({ key: a.key, title: a.title, emoji: a.emoji, markdown: blocksToMarkdown(a.blocks) })),
+    artifacts: plan.artifacts,
+  };
+}

package/core/progress.ts

@@ -21,10 +21,10 @@ export const PROGRESS_FORMAT = 2;
 
 export const KNOWN_STATE_KEYS = [
   "version", "answers", "feedback", "bizModel", "grill",
-  "assets", "research", "swot", "prd", "naming", "brand", "kit",
+  "assets", "research", "swot", "prd", "naming", "brand", "governance", "kit",
 ] as const;
 
-export type ArtifactKey = "bizModel" | "grill" | "assets" | "research" | "swot" | "prd" | "naming" | "brand";
+export type ArtifactKey = "bizModel" | "grill" | "assets" | "research" | "swot" | "prd" | "naming" | "brand" | "governance";
 
 export interface Writer { kind: "web" | "kit"; version?: string; ts: number; }
 
@@ -81,6 +81,7 @@ export interface ProgressState {
   prd: unknown;
   naming: unknown;
   brand: unknown;
+  governance: unknown;
   kit: KitNamespace | null;
   [extra: string]: unknown;
 }
@@ -99,7 +100,7 @@ export interface ProgressPayload {
 export function emptyState(): ProgressState {
   return {
     version: 2, answers: {}, feedback: {}, bizModel: null, grill: null,
-    assets: null, research: null, swot: null, prd: null, naming: null, brand: null, kit: null,
+    assets: null, research: null, swot: null, prd: null, naming: null, brand: null, governance: null, kit: null,
   };
 }
 
@@ -132,6 +133,7 @@ export function parseProgress(text: string): ProgressPayload {
     prd: s["prd"] ?? null,
     naming: s["naming"] ?? null,
     brand: s["brand"] ?? null,
+    governance: s["governance"] ?? null,
     kit: (s["kit"] as KitNamespace | undefined) ?? null,
   };
   return {
@@ -149,7 +151,7 @@ export function parseProgress(text: string): ProgressPayload {
 export function buildProgress(state: Partial<ProgressState>, writer: Writer, exportedAt: string): ProgressPayload {
   const s = (state || {}) as Record<string, unknown>;
   const {
-    answers, feedback, bizModel, grill, assets, research, swot, prd, naming, brand, kit,
+    answers, feedback, bizModel, grill, assets, research, swot, prd, naming, brand, governance, kit,
     version: _v, exportedAt: _ea, formatNewer: _fn, ...rest
   } = s;
   return {
@@ -170,6 +172,7 @@ export function buildProgress(state: Partial<ProgressState>, writer: Writer, exp
       prd: prd ?? null,
       naming: naming ?? null,
       brand: brand ?? null,
+      governance: governance ?? null,
       kit: (kit as KitNamespace | undefined) ?? null,
       ...rest,
     },
@@ -299,7 +302,7 @@ export function summarizeState(state: ProgressState): StateSummary {
     if (s === "green" || s === "yellow" || s === "red") byStatus[s]++;
     else byStatus.ungraded++;
   }
-  const artifacts = (["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand"] as const)
+  const artifacts = (["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand", "governance"] as const)
     .filter((k) => state[k] != null);
   const kit = (state.kit && typeof state.kit === "object") ? state.kit : null;
   return {

package/core/state-ops.ts

@@ -12,7 +12,7 @@ import {
   type ArtifactKey, type PersonaInput, type EndState, type KitCursor,
 } from "./progress.ts";
 
-export const ARTIFACT_KEYS: ArtifactKey[] = ["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand"];
+export const ARTIFACT_KEYS: ArtifactKey[] = ["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand", "governance"];
 const END_STATES: EndState[] = ["open", "pass", "setAside"];
 
 export interface StateOp {

package/core/sync-io.ts

@@ -60,7 +60,7 @@ export function ghAuthed(): boolean {
 function syncConfigPath(): string {
   return process.env["THOUGHT_LAYER_SYNC_CONFIG"] || join(homedir(), ".thought-layer", "sync.json");
 }
-function loadConfig(): SyncConfig {
+export function loadConfig(): SyncConfig {
   const p = syncConfigPath();
   if (!existsSync(p)) return emptySyncConfig();
   try { return parseSyncConfig(readFileSync(p, "utf8")); }
@@ -74,12 +74,14 @@ function saveConfig(cfg: SyncConfig): void {
 
 // ---- git helpers -------------------------------------------------------------
 
-interface Run { status: number; out: string; err: string; }
-function git(dir: string | null, args: string[], timeout = 120000): Run {
+export interface Run { status: number; out: string; err: string; }
+// Exported so the artifacts delivery layer (artifacts-io.ts) reuses the exact
+// same git shell-out plumbing rather than re-implementing spawnSync.
+export function git(dir: string | null, args: string[], timeout = 120000): Run {
   const r = spawnSync("git", dir ? ["-C", dir, ...args] : args, { encoding: "utf8", timeout });
   return { status: r.status ?? 1, out: r.stdout || "", err: r.stderr || "" };
 }
-function isGitRepo(dir: string): boolean {
+export function isGitRepo(dir: string): boolean {
   return existsSync(join(dir, ".git")) && git(dir, ["rev-parse", "--is-inside-work-tree"]).status === 0;
 }
 function dirNonEmpty(dir: string): boolean {
@@ -91,7 +93,7 @@ const absDir = (d: string, cwd = process.cwd()): string => (isAbsolute(d) ? d :
 // ---- the clone scaffolding files written on init -----------------------------
 
 const GITATTRIBUTES = `# The kit reconciles session JSON itself; never let git textually merge it\n# (which would corrupt the envelope). -merge keeps our copy in the working tree\n# on a conflict; the kit then rebuilds the merged result from the clean blobs.\n.thought-layer/*.json -merge\n`;
-const GITIGNORE = `# A Thought Layer sessions repo holds session state only. Built product\n# artifacts and secrets never sync here.\nbuild.json\ndeploy.json\n*.local\n.env\n.env.*\n!.env.example\ndist/\n.netlify/\nnode_modules/\n`;
+const GITIGNORE = `# A Thought Layer sessions repo holds session state only. Built product\n# artifacts and secrets never sync here.\nbuild.json\ndeploy.json\n*.local\n.env\n.env.*\n!.env.example\ndist/\n.netlify/\nnode_modules/\n# Delivered artifacts (tl artifacts) ARE intentionally tracked, even though the\n# same filenames are ignored elsewhere in the tree.\n!artifacts/\n!artifacts/**\n`;
 const README = `# Thought Layer sessions\n\nThis private repo is the home for Thought Layer session files. Each session is one\nfile under \`.thought-layer/<name>.json\` (the portable validation and design state).\nUse the kit to work with them:\n\n    tl sync open --name <session>     pull and resume a session\n    tl sync save --name <session>     snapshot the current state, commit, and push\n    tl sync list                      list the sessions in this repo\n\nCollaboration is handled by GitHub: add a collaborator to this repo in its GitHub\nsettings, and they can clone it and run the kit against the same sessions.\nThe kit reconciles concurrent edits itself (newest wins per field, conflicts are\nreported), so git never has to merge the JSON by hand.\n`;
 
 function writeCloneScaffold(cloneDir: string): void {
@@ -136,7 +138,8 @@ export async function runSync(opts: SyncRunOptions, ctx: { ts: number; exportedA
 }
 
 // Resolve the workspace + clone dir an op targets (everything except init).
-function resolveWorkspace(opts: SyncRunOptions, cfg: SyncConfig): { cloneDir: string; ws: SyncWorkspace | null } {
+// Exported so artifacts-io.ts resolves the same sessions workspace.
+export function resolveWorkspace(opts: SyncRunOptions, cfg: SyncConfig): { cloneDir: string; ws: SyncWorkspace | null } {
   if (opts.dir && opts.dir.trim()) return { cloneDir: absDir(opts.dir), ws: null };
   const env = process.env["THOUGHT_LAYER_SESSIONS_DIR"];
   if (env && env.trim()) return { cloneDir: absDir(env), ws: null };