@hobocode/thought-layer 0.1.0 → 0.2.1

package/core/index.ts

@@ -10,3 +10,8 @@
 export * from "./scoring.ts";
 export * from "./domains.ts";
 export * from "./model.ts";
+export * from "./progress.ts";
+export * from "./stages.ts";
+export * from "./stage-map.ts";
+export * from "./state-file.ts";
+export * from "./state-ops.ts";

package/core/progress.ts

@@ -0,0 +1,348 @@
+// The portable Thought Layer progress file: the interop format shared with the
+// web app (src/lib/progressFile.js). An agent reads it to resume a long
+// validation run and writes it to hand back to a co-founder using the web app.
+//
+// This module is the single deterministic source of envelope + feedback-entry
+// assembly, so the model never hand-writes the JSON. Hand-written feedback is
+// the main way a file gets corrupted (wrong thresholds, missing personas,
+// statement-vs-text drift), so the tl_state tool and the CLI both build the
+// objects here from prose + numbers the model supplies.
+//
+// Mirrors the web app's buildProgressPayload / parseProgressFile EXACTLY. Keep
+// PROGRESS_FORMAT and KNOWN_STATE_KEYS in sync with src/lib/progressFile.js.
+
+import { aggregateConfidence, statusFromConfidence } from "./scoring.ts";
+import type { Status } from "./scoring.ts";
+import { isAnswerableQid } from "./stages.ts";
+import { ANSWERABLE_QIDS } from "./stage-map.ts";
+
+export const APP = "thought-layer";
+export const PROGRESS_FORMAT = 2;
+
+export const KNOWN_STATE_KEYS = [
+  "version", "answers", "feedback", "bizModel", "grill",
+  "assets", "research", "swot", "prd", "naming", "brand", "kit",
+] as const;
+
+export type ArtifactKey = "bizModel" | "grill" | "assets" | "research" | "swot" | "prd" | "naming" | "brand";
+
+export interface Writer { kind: "web" | "kit"; version?: string; ts: number; }
+
+export interface Suggestion { id: string; persona: string; summary: string; patch: string; }
+
+export interface PersonaResult {
+  assessment: string;
+  confidence: number;
+  confidenceRationale: string;
+  suggestions: Suggestion[];
+}
+
+export interface FeedbackEntry {
+  mode: string;
+  personas: Record<string, PersonaResult>;
+  confidence: number | null;
+  status: Status | null;
+  assessment: string;
+  suggestions: Suggestion[];
+  appliedIds: string[];
+  todos: Suggestion[];
+  round: number;
+  overridden: boolean;
+  exited: boolean;
+  stale: boolean;
+  ts: number;
+}
+
+export interface KitCursor {
+  stage?: "validation" | "model" | "design";
+  backboneStage?: number;
+  lastQuestionId?: string;
+  phase?: string;
+}
+
+export interface KitNamespace {
+  schema: number;
+  cursor?: KitCursor;
+  modulesRun?: string[];
+  parked?: Record<string, string[]>;
+  panelMeta?: Record<string, unknown>;
+  updatedAt: number;
+}
+
+export interface ProgressState {
+  version: number;
+  answers: Record<string, unknown>;
+  feedback: Record<string, unknown>;
+  bizModel: unknown;
+  grill: unknown;
+  assets: unknown;
+  research: unknown;
+  swot: unknown;
+  prd: unknown;
+  naming: unknown;
+  brand: unknown;
+  kit: KitNamespace | null;
+  [extra: string]: unknown;
+}
+
+export interface ProgressPayload {
+  app: string;
+  format: number;
+  exportedAt: string;
+  writer?: Writer;
+  state: ProgressState;
+  formatNewer: boolean;
+}
+
+// ---- envelope ----------------------------------------------------------------
+
+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,
+  };
+}
+
+// Lenient parse: validate the gate string, accept ANY format (a newer file is
+// not rejected), default missing artifacts to null, and preserve unknown keys
+// so a file from a newer build round-trips losslessly.
+export function parseProgress(text: string): ProgressPayload {
+  let payload: Record<string, unknown>;
+  try { payload = JSON.parse(text) as Record<string, unknown>; }
+  catch { throw new Error("That file isn't valid JSON."); }
+  if (payload?.["app"] !== APP || !payload?.["state"]) {
+    throw new Error("That file isn't a Thought Layer progress file.");
+  }
+  const rawFormat = payload["format"];
+  const formatNewer = typeof rawFormat === "number" && rawFormat > PROGRESS_FORMAT;
+  const s = (payload["state"] && typeof payload["state"] === "object")
+    ? payload["state"] as Record<string, unknown> : {};
+  const obj = (v: unknown): Record<string, unknown> =>
+    (v && typeof v === "object" && !Array.isArray(v)) ? v as Record<string, unknown> : {};
+  const state: ProgressState = {
+    ...s,
+    version: 2,
+    answers: obj(s["answers"]),
+    feedback: obj(s["feedback"]),
+    bizModel: s["bizModel"] ?? null,
+    grill: s["grill"] ?? null,
+    assets: s["assets"] ?? null,
+    research: s["research"] ?? null,
+    swot: s["swot"] ?? null,
+    prd: s["prd"] ?? null,
+    naming: s["naming"] ?? null,
+    brand: s["brand"] ?? null,
+    kit: (s["kit"] as KitNamespace | undefined) ?? null,
+  };
+  return {
+    app: APP,
+    format: typeof rawFormat === "number" ? rawFormat : PROGRESS_FORMAT,
+    exportedAt: typeof payload["exportedAt"] === "string" ? payload["exportedAt"] as string : "",
+    writer: payload["writer"] as Writer | undefined,
+    state,
+    formatNewer,
+  };
+}
+
+// Assemble the on-disk payload. Pulls known keys explicitly and preserves any
+// unknown future key (rest), exactly like the web app's buildProgressPayload.
+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,
+    version: _v, exportedAt: _ea, formatNewer: _fn, ...rest
+  } = s;
+  return {
+    app: APP,
+    format: PROGRESS_FORMAT,
+    exportedAt,
+    writer,
+    formatNewer: false,
+    state: {
+      version: 2,
+      answers: (answers as Record<string, unknown>) || {},
+      feedback: (feedback as Record<string, unknown>) || {},
+      bizModel: bizModel ?? null,
+      grill: grill ?? null,
+      assets: assets ?? null,
+      research: research ?? null,
+      swot: swot ?? null,
+      prd: prd ?? null,
+      naming: naming ?? null,
+      brand: brand ?? null,
+      kit: (kit as KitNamespace | undefined) ?? null,
+      ...rest,
+    },
+  };
+}
+
+export function serializeProgress(payload: ProgressPayload): string {
+  const { formatNewer: _fn, ...wire } = payload;
+  return JSON.stringify(wire, null, 2) + "\n";
+}
+
+// ---- feedback assembly (the corruption guard) --------------------------------
+
+const clampConfidence = (n: unknown): number =>
+  (typeof n === "number" && !Number.isNaN(n)) ? Math.min(1, Math.max(0, n)) : 0.6;
+
+export interface PersonaInput {
+  persona: string;
+  assessment?: string;
+  confidence: number;
+  confidenceRationale?: string;
+  suggestions?: Array<{ id?: string; summary?: string; patch?: string }>;
+}
+
+// "pass" and "open" are byte-identical on disk: the web app derives done from
+// confidence >= 0.85 && !stale, so a GENUINE pass must not set overridden (that
+// is reserved for an explicit set-aside, which renders "set aside by you").
+export type EndState = "open" | "pass" | "setAside";
+
+export function buildFeedbackEntry(opts: {
+  mode: string;
+  personas: PersonaInput[];
+  endState?: EndState;
+  round?: number;
+  ts: number;
+}): FeedbackEntry {
+  const { mode, personas: inputs, endState = "open", round = 1, ts } = opts;
+  const personas: Record<string, PersonaResult> = {};
+  for (const p of inputs) {
+    const k = p.persona;
+    personas[k] = {
+      assessment: p.assessment || "",
+      confidence: clampConfidence(p.confidence),
+      confidenceRationale: p.confidenceRationale || "",
+      suggestions: (p.suggestions || []).slice(0, 3).map((sg, i) => ({
+        id: `${k}-${sg.id || `s${i + 1}`}`,
+        persona: k,
+        summary: sg.summary || "Suggestion",
+        patch: sg.patch || "",
+      })),
+    };
+  }
+  const keys = Object.keys(personas);
+  const confidence = aggregateConfidence(keys.map((k) => personas[k]!.confidence));
+  const status = statusFromConfidence(confidence);
+  const suggestions = keys.flatMap((k) => personas[k]!.suggestions);
+  const assessment = mode !== "panel" && personas[mode] ? personas[mode]!.assessment : "";
+
+  const entry: FeedbackEntry = {
+    mode, personas, confidence, status, assessment,
+    suggestions, appliedIds: [], todos: [],
+    round, overridden: false, exited: false, stale: false, ts,
+  };
+
+  if (endState === "setAside") {
+    // Mirror QuestionPage.exit(): freeze unresolved suggestions as to-dos and
+    // force the dot green (the founder explicitly set this stage aside).
+    const seen = new Set<string>();
+    const todos = suggestions.filter((sg) => (seen.has(sg.id) ? false : (seen.add(sg.id), true)));
+    return { ...entry, overridden: true, exited: true, status: "green", todos };
+  }
+  return entry;
+}
+
+// ---- requirement normalization ----------------------------------------------
+
+// The kit's grill describes a requirement as { id, category, statement }; the
+// web app's prd/grill store it as { id, category, text }. Remap on write.
+export function normalizeRequirements(
+  reqs: Array<{ id?: string; category?: string; statement?: string; text?: string }> | undefined,
+): Array<{ id: string; category: string; text: string }> {
+  return (reqs || []).map((r, i) => ({
+    id: r.id || `r${i + 1}`,
+    category: r.category || "functional",
+    text: r.text ?? r.statement ?? "",
+  }));
+}
+
+// Normalize an artifact value on write. For prd/grill, remap the kit's
+// requirement `statement` field to the web app's `text` field so the structured
+// views render. Everything else passes through untouched.
+export function normalizeArtifactValue(key: ArtifactKey, value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  if (key === "prd" || key === "grill") {
+    const v = value as Record<string, unknown>;
+    if (Array.isArray(v["requirements"])) {
+      return { ...v, requirements: normalizeRequirements(v["requirements"] as Array<{ id?: string; category?: string; statement?: string; text?: string }>) };
+    }
+  }
+  return value;
+}
+
+// ---- resume summary ----------------------------------------------------------
+
+export interface StateSummary {
+  answered: number;
+  totalAnswerable: number;
+  byStatus: { green: number; yellow: number; red: number; ungraded: number };
+  artifacts: string[];
+  cursor: KitCursor | null;
+  modulesRun: string[];
+}
+
+const isFilled = (v: unknown): boolean =>
+  typeof v === "string" ? v.trim().length > 0
+    : Array.isArray(v) ? v.length > 0
+      : v != null && typeof v === "object" ? Object.keys(v).length > 0
+        : v != null;
+
+export function summarizeState(state: ProgressState): StateSummary {
+  const answers = state.answers || {};
+  const answered = Object.keys(answers).filter((k) => isFilled(answers[k])).length;
+  const byStatus = { green: 0, yellow: 0, red: 0, ungraded: 0 };
+  for (const v of Object.values(state.feedback || {})) {
+    const fb = v as { status?: string; overridden?: boolean } | null;
+    const s = fb?.overridden ? "green" : fb?.status;
+    if (s === "green" || s === "yellow" || s === "red") byStatus[s]++;
+    else byStatus.ungraded++;
+  }
+  const artifacts = (["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand"] as const)
+    .filter((k) => state[k] != null);
+  const kit = (state.kit && typeof state.kit === "object") ? state.kit : null;
+  return {
+    answered,
+    totalAnswerable: ANSWERABLE_QIDS.length,
+    byStatus,
+    artifacts,
+    cursor: kit?.cursor ?? null,
+    modulesRun: kit?.modulesRun ?? [],
+  };
+}
+
+// ---- state mutators (keep the tool + CLI thin and consistent) ----------------
+
+function withKit(state: ProgressState, patch: Partial<KitNamespace>, ts: number): KitNamespace {
+  const prev = (state.kit && typeof state.kit === "object") ? state.kit : { schema: 1, updatedAt: ts };
+  return { ...prev, ...patch, schema: 1, updatedAt: ts };
+}
+
+export function setAnswer(state: ProgressState, qId: string, value: unknown, ts: number): ProgressState {
+  if (!isAnswerableQid(qId)) {
+    throw new Error(`"${qId}" is not an answerable Thought Layer question id. The agent leaves web-app-only fields to the founder; module sub-stage notes belong in kit.panelMeta.`);
+  }
+  return { ...state, answers: { ...state.answers, [qId]: value }, kit: withKit(state, {}, ts) };
+}
+
+export function setFeedbackEntry(state: ProgressState, qId: string, entry: FeedbackEntry, ts: number): ProgressState {
+  return { ...state, feedback: { ...state.feedback, [qId]: entry }, kit: withKit(state, {}, ts) };
+}
+
+export function setArtifact(state: ProgressState, key: ArtifactKey, value: unknown, ts: number): ProgressState {
+  return { ...state, [key]: value, kit: withKit(state, {}, ts) };
+}
+
+export function setCursor(state: ProgressState, cursor: KitCursor, ts: number): ProgressState {
+  return { ...state, kit: withKit(state, { cursor }, ts) };
+}
+
+// Park a panel note that has no web-app question id (module sub-stage verdicts,
+// later-stage concerns surfaced early) under the agent-owned kit namespace.
+export function parkNote(state: ProgressState, key: string, note: string, ts: number): ProgressState {
+  const prev = (state.kit && typeof state.kit === "object") ? state.kit : { schema: 1, updatedAt: ts };
+  const parked = { ...(prev.parked || {}) };
+  parked[key] = [...(parked[key] || []), note];
+  return { ...state, kit: withKit(state, { parked }, ts) };
+}

package/core/stage-map.ts

@@ -0,0 +1,16 @@
+// GENERATED from the web app's stage-map.json by scripts/sync-stage-map.mjs.
+// Do not edit by hand. This is the vendored copy of the web app's question
+// registry; it is the single source of truth for which question ids exist, so
+// an agent never writes an answer the web app cannot represent. Regenerate with
+// `node scripts/sync-stage-map.mjs` after the web app's sections.js changes.
+
+export const STATE_FORMAT = 2;
+
+export const AREAS: readonly string[] = ["big-idea","business-model","brand","market-research","strategy","product","decision-science","library"];
+
+// Every question id, in canonical order.
+export const ALL_QIDS: readonly string[] = ["what-statement","domain-experience","domain-gaps","paid-today","evidence","target-market","incumbent-gap","pitch","headline","customer-quote","press-why-now","deck-audience","landing-goal","asset-builder","commitment","cost-architecture","cost-risk","realistic-goal","pricing-model","first-ten","retention","crm-approach","crm-community","support-model","support-scaling","bm-who-buys","bm-who-supplies","bm-parties","bm-builder","naming-studio","brand-feel","brand-unlike","brand-studio","market-research","swot","prd-problem","prd-not-building","prd-draft","prd-grill","review","dq-frame","dq-alternatives","dq-information","dq-values","dq-reasoning","dq-commitment","library"];
+
+// Question ids that hold a value under answers[] (text / repeatable / parties /
+// research-flagged text). Artifact and page steps are excluded.
+export const ANSWERABLE_QIDS: readonly string[] = ["what-statement","domain-experience","domain-gaps","paid-today","evidence","target-market","incumbent-gap","pitch","headline","customer-quote","press-why-now","deck-audience","landing-goal","commitment","cost-architecture","cost-risk","realistic-goal","pricing-model","first-ten","retention","crm-approach","crm-community","support-model","support-scaling","bm-who-buys","bm-who-supplies","bm-parties","brand-feel","brand-unlike","market-research","prd-problem","prd-not-building","dq-frame","dq-alternatives","dq-information","dq-values","dq-reasoning","dq-commitment"];

package/core/stages.ts

@@ -0,0 +1,68 @@
+// The kit's mapping from framework backbone stages (and the optional modules)
+// to the web app question ids they write into answers[]. Hand-maintained, but
+// guarded: core/stages.test.ts fails if any mapped qId is missing from the
+// vendored stage-map (regenerated from the web app). That is the drift
+// protection for the two-repo interop contract - rename a qId in the web app,
+// re-run sync-stage-map, and the test goes red until this map is updated.
+
+import { ANSWERABLE_QIDS, ALL_QIDS } from "./stage-map.ts";
+
+const ANSWERABLE_SET = new Set(ANSWERABLE_QIDS);
+const ALL_SET = new Set(ALL_QIDS);
+
+// A question id the agent may write a value into answers[] for.
+export function isAnswerableQid(qId: string): boolean {
+  return ANSWERABLE_SET.has(qId);
+}
+// A question id (answerable or artifact/page step) the web app knows about.
+export function isKnownQid(qId: string): boolean {
+  return ALL_SET.has(qId);
+}
+
+// Backbone stage (in framework order) -> the answer qIds it writes. Stages that
+// only produce an artifact (PRD, grill, business-model numbers) are noted but
+// have no answer ids beyond the prose questions listed here.
+export const BACKBONE_QID_MAP: Record<string, readonly string[]> = {
+  "concise-what": ["what-statement"],
+  "domain-knowledge": ["domain-experience", "domain-gaps"],
+  "validation": ["paid-today", "evidence"],
+  "market-selection": ["target-market", "incumbent-gap"],
+  "thirty-second-test": ["pitch"],
+  "time": ["commitment"],
+  "costs": ["cost-architecture", "cost-risk"],
+  "scale": ["realistic-goal"],
+  "pricing": ["pricing-model"],
+  "business-model": ["bm-who-buys", "bm-who-supplies", "bm-parties"],
+  "customer-acquisition": ["first-ten", "retention"],
+  "customer-relationships": ["crm-approach", "crm-community"],
+  "support": ["support-model", "support-scaling"],
+  "prd": ["prd-problem", "prd-not-building"],
+};
+
+// Optional deep-dive modules -> the answer qIds they may write. The modules
+// mostly converge into backbone qIds; these are the ids unique to a module.
+export const MODULE_QID_MAP: Record<string, readonly string[]> = {
+  "market-research": ["market-research"],
+  "brand": ["brand-feel", "brand-unlike"],
+  // strategy folds into market-selection (target-market / incumbent-gap) and
+  // produces the swot artifact; business-model folds into costs/pricing and
+  // produces the bizModel artifact - neither has a unique answer qId.
+};
+
+// Every answer qId the kit may write, across backbone + modules. The drift test
+// asserts this is a subset of the web app's answerable registry.
+export const KIT_WRITTEN_QIDS: readonly string[] = [
+  ...new Set([
+    ...Object.values(BACKBONE_QID_MAP).flat(),
+    ...Object.values(MODULE_QID_MAP).flat(),
+  ]),
+];
+
+// qIds the agent deliberately leaves for the founder in the web app (no kit
+// stage). Surfaced so the framework skill can skip them explicitly rather than
+// writing empty strings (which read as "attempted and blank").
+export const WEB_APP_ONLY_QIDS: readonly string[] = [
+  "headline", "customer-quote", "press-why-now", // press release
+  "deck-audience", "landing-goal", // launch assets
+  "dq-frame", "dq-alternatives", "dq-information", "dq-values", "dq-reasoning", "dq-commitment", // decision science
+];

package/core/state-file.ts

@@ -0,0 +1,56 @@
+// Node filesystem layer for the portable progress file. The pure transforms
+// live in progress.ts; this is the thin IO both frontends share - the Pi
+// tl_state tool and the CLI bin. Kept out of progress.ts so the transforms stay
+// testable without touching disk.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import {
+  parseProgress, buildProgress, serializeProgress, emptyState,
+  type ProgressState, type ProgressPayload, type Writer,
+} from "./progress.ts";
+
+export const STATE_DIR = ".thought-layer";
+export const STATE_FILE = "state.json";
+
+// Resolve the canonical state file path. `target` may be a project directory or
+// a direct path to a .json file; defaults to <cwd>/.thought-layer/state.json.
+export function resolveStatePath(target?: string, cwd: string = process.cwd()): string {
+  if (!target) return join(cwd, STATE_DIR, STATE_FILE);
+  const abs = isAbsolute(target) ? target : resolve(cwd, target);
+  return abs.endsWith(".json") ? abs : join(abs, STATE_DIR, STATE_FILE);
+}
+
+export interface LoadResult {
+  path: string;
+  exists: boolean;
+  payload: ProgressPayload;
+  state: ProgressState;
+}
+
+// Read the state file. A missing file is not an error: it returns an empty
+// state so the caller can start a fresh run and write it on first save.
+export function loadStateFile(target?: string, cwd?: string): LoadResult {
+  const path = resolveStatePath(target, cwd);
+  if (!existsSync(path)) {
+    const state = emptyState();
+    return { path, exists: false, payload: buildProgress(state, { kind: "kit", ts: 0 }, ""), state };
+  }
+  const payload = parseProgress(readFileSync(path, "utf8"));
+  return { path, exists: true, payload, state: payload.state };
+}
+
+// Write the state file, stamping the kit writer + an ISO exportedAt. Creates the
+// .thought-layer directory on first write.
+export function saveStateFile(
+  state: ProgressState,
+  opts: { target?: string; cwd?: string; version?: string; ts: number; exportedAt: string },
+): { path: string; bytes: number } {
+  const path = resolveStatePath(opts.target, opts.cwd);
+  mkdirSync(dirname(path), { recursive: true });
+  const writer: Writer = { kind: "kit", ts: opts.ts };
+  if (opts.version) writer.version = opts.version;
+  const text = serializeProgress(buildProgress(state, writer, opts.exportedAt));
+  writeFileSync(path, text);
+  return { path, bytes: Buffer.byteLength(text) };
+}

package/core/state-ops.ts

@@ -0,0 +1,104 @@
+// The single dispatch for every progress-file operation, shared by both
+// frontends - the Pi tl_state tool and the CLI bin - so they can never drift.
+// The model (or the shell) supplies a payload of prose + numbers; this builds
+// the exact on-disk objects via core/progress.ts and writes through
+// core/state-file.ts. Pure of any host concern (no Pi types, no argv).
+
+import { gradeFromConfidence } from "./scoring.ts";
+import { loadStateFile, saveStateFile } from "./state-file.ts";
+import {
+  setAnswer, setArtifact, setCursor, parkNote, buildFeedbackEntry,
+  normalizeArtifactValue, summarizeState,
+  type ArtifactKey, type PersonaInput, type EndState, type KitCursor,
+} from "./progress.ts";
+
+export const ARTIFACT_KEYS: ArtifactKey[] = ["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand"];
+const END_STATES: EndState[] = ["open", "pass", "setAside"];
+
+export interface StateOp {
+  op: string;
+  path?: string;
+  qId?: string;
+  value?: unknown;
+  artifact?: string;
+  mode?: string;
+  personas?: PersonaInput[];
+  endState?: string;
+  round?: number;
+  cursor?: KitCursor;
+  key?: string;
+  note?: string;
+}
+
+export interface StateOpResult {
+  ok: boolean;
+  message: string;
+  details: Record<string, unknown>;
+}
+
+export function applyStateOp(p: StateOp, ctx: { ts: number; exportedAt: string }): StateOpResult {
+  const { ts, exportedAt } = ctx;
+  const fail = (message: string): StateOpResult => ({ ok: false, message, details: {} });
+  try {
+    const loaded = loadStateFile(p.path);
+    const save = (next: typeof loaded.state) => saveStateFile(next, { target: p.path, ts, exportedAt }).path;
+
+    if (p.op === "read" || p.op === "export") {
+      const sum = summarizeState(loaded.state);
+      const message = loaded.exists
+        ? `Loaded ${loaded.path}: ${sum.answered}/${sum.totalAnswerable} answered ` +
+          `(${sum.byStatus.green} green, ${sum.byStatus.yellow} yellow, ${sum.byStatus.red} red), ` +
+          `artifacts: ${sum.artifacts.join(", ") || "none"}. ` +
+          `Resume at ${sum.cursor ? `stage ${sum.cursor.backboneStage ?? "?"} (${sum.cursor.phase ?? "?"})` : "the beginning"}.`
+        : `No state file yet at ${loaded.path}. Start a fresh run; it will be created on first write.`;
+      return { ok: true, message, details: { path: loaded.path, exists: loaded.exists, summary: sum, state: loaded.state } };
+    }
+
+    if (p.op === "answer") {
+      if (!p.qId || typeof p.value !== "string") return fail("answer needs a qId and a string value.");
+      const path = save(setAnswer(loaded.state, p.qId, p.value, ts));
+      return { ok: true, message: `Recorded answer for "${p.qId}" and saved ${path}.`, details: { path, qId: p.qId } };
+    }
+
+    if (p.op === "feedback") {
+      if (!p.qId || !p.personas?.length) return fail("feedback needs a qId and at least one persona.");
+      const endState = (END_STATES as string[]).includes(p.endState || "") ? (p.endState as EndState) : "open";
+      const mode = p.mode || (p.personas.length > 1 ? "panel" : p.personas[0]!.persona);
+      const entry = buildFeedbackEntry({ mode, personas: p.personas, endState, round: p.round, ts });
+      const next = { ...loaded.state, feedback: { ...loaded.state.feedback, [p.qId]: entry } };
+      const path = save(next);
+      const grade = gradeFromConfidence(entry.confidence);
+      const pct = entry.confidence != null ? `${(entry.confidence * 100).toFixed(0)}%` : "n/a";
+      const tail = endState === "setAside" ? `, set aside with ${entry.todos.length} to-do(s)` : endState === "pass" ? ", cleared the bar" : "";
+      return {
+        ok: true,
+        message: `Recorded panel verdict for "${p.qId}": confidence ${pct} -> ${entry.status}, grade ${grade}${tail}. Saved ${path}.`,
+        details: { path, qId: p.qId, confidence: entry.confidence, status: entry.status, grade },
+      };
+    }
+
+    if (p.op === "artifact") {
+      const key = p.artifact as ArtifactKey;
+      if (!ARTIFACT_KEYS.includes(key)) return fail(`artifact needs a key in: ${ARTIFACT_KEYS.join(", ")}.`);
+      if (p.value == null) return fail("artifact needs a value object.");
+      const path = save(setArtifact(loaded.state, key, normalizeArtifactValue(key, p.value), ts));
+      return { ok: true, message: `Stored ${key} artifact and saved ${path}.`, details: { path, artifact: key } };
+    }
+
+    if (p.op === "cursor") {
+      if (!p.cursor) return fail("cursor needs a cursor object.");
+      const path = save(setCursor(loaded.state, p.cursor, ts));
+      return { ok: true, message: `Saved resume cursor (stage ${p.cursor.backboneStage ?? "?"}, ${p.cursor.phase ?? "?"}) to ${path}.`, details: { path } };
+    }
+
+    if (p.op === "park") {
+      if (!p.key || !p.note) return fail("park needs a key and a note.");
+      const path = save(parkNote(loaded.state, p.key, p.note, ts));
+      return { ok: true, message: `Parked a note under "${p.key}" and saved ${path}.`, details: { path, key: p.key } };
+    }
+
+    return fail(`Unknown op "${p.op}". Use read, answer, feedback, artifact, cursor, park, or export.`);
+  } catch (e) {
+    return fail(`tl_state error: ${(e as Error).message}`);
+  }
+}

package/dist/tl.js

@@ -0,0 +1,453 @@
+#!/usr/bin/env node
+
+// bin/tl.ts
+import { readFileSync as readFileSync2 } from "fs";
+
+// core/scoring.ts
+var CONFIDENCE_GOAL = 0.85;
+function statusFromConfidence(c) {
+  if (typeof c !== "number" || Number.isNaN(c)) return null;
+  if (c >= CONFIDENCE_GOAL) return "green";
+  if (c >= 0.6) return "yellow";
+  return "red";
+}
+function gradeFromConfidence(c) {
+  if (typeof c !== "number" || Number.isNaN(c)) return null;
+  if (c >= 0.9) return "A";
+  if (c >= 0.8) return "B";
+  if (c >= 0.7) return "C";
+  if (c >= 0.6) return "D";
+  return "F";
+}
+function aggregateConfidence(values) {
+  const nums = (values || []).filter((v) => typeof v === "number" && !Number.isNaN(v));
+  if (nums.length === 0) return null;
+  return nums.reduce((a, b) => a + b, 0) / nums.length;
+}
+
+// core/state-file.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, isAbsolute, join, resolve } from "path";
+
+// core/stage-map.ts
+var ALL_QIDS = ["what-statement", "domain-experience", "domain-gaps", "paid-today", "evidence", "target-market", "incumbent-gap", "pitch", "headline", "customer-quote", "press-why-now", "deck-audience", "landing-goal", "asset-builder", "commitment", "cost-architecture", "cost-risk", "realistic-goal", "pricing-model", "first-ten", "retention", "crm-approach", "crm-community", "support-model", "support-scaling", "bm-who-buys", "bm-who-supplies", "bm-parties", "bm-builder", "naming-studio", "brand-feel", "brand-unlike", "brand-studio", "market-research", "swot", "prd-problem", "prd-not-building", "prd-draft", "prd-grill", "review", "dq-frame", "dq-alternatives", "dq-information", "dq-values", "dq-reasoning", "dq-commitment", "library"];
+var ANSWERABLE_QIDS = ["what-statement", "domain-experience", "domain-gaps", "paid-today", "evidence", "target-market", "incumbent-gap", "pitch", "headline", "customer-quote", "press-why-now", "deck-audience", "landing-goal", "commitment", "cost-architecture", "cost-risk", "realistic-goal", "pricing-model", "first-ten", "retention", "crm-approach", "crm-community", "support-model", "support-scaling", "bm-who-buys", "bm-who-supplies", "bm-parties", "brand-feel", "brand-unlike", "market-research", "prd-problem", "prd-not-building", "dq-frame", "dq-alternatives", "dq-information", "dq-values", "dq-reasoning", "dq-commitment"];
+
+// core/stages.ts
+var ANSWERABLE_SET = new Set(ANSWERABLE_QIDS);
+var ALL_SET = new Set(ALL_QIDS);
+function isAnswerableQid(qId) {
+  return ANSWERABLE_SET.has(qId);
+}
+var BACKBONE_QID_MAP = {
+  "concise-what": ["what-statement"],
+  "domain-knowledge": ["domain-experience", "domain-gaps"],
+  "validation": ["paid-today", "evidence"],
+  "market-selection": ["target-market", "incumbent-gap"],
+  "thirty-second-test": ["pitch"],
+  "time": ["commitment"],
+  "costs": ["cost-architecture", "cost-risk"],
+  "scale": ["realistic-goal"],
+  "pricing": ["pricing-model"],
+  "business-model": ["bm-who-buys", "bm-who-supplies", "bm-parties"],
+  "customer-acquisition": ["first-ten", "retention"],
+  "customer-relationships": ["crm-approach", "crm-community"],
+  "support": ["support-model", "support-scaling"],
+  "prd": ["prd-problem", "prd-not-building"]
+};
+var MODULE_QID_MAP = {
+  "market-research": ["market-research"],
+  "brand": ["brand-feel", "brand-unlike"]
+  // strategy folds into market-selection (target-market / incumbent-gap) and
+  // produces the swot artifact; business-model folds into costs/pricing and
+  // produces the bizModel artifact - neither has a unique answer qId.
+};
+var KIT_WRITTEN_QIDS = [
+  .../* @__PURE__ */ new Set([
+    ...Object.values(BACKBONE_QID_MAP).flat(),
+    ...Object.values(MODULE_QID_MAP).flat()
+  ])
+];
+
+// core/progress.ts
+var APP = "thought-layer";
+var PROGRESS_FORMAT = 2;
+function emptyState() {
+  return {
+    version: 2,
+    answers: {},
+    feedback: {},
+    bizModel: null,
+    grill: null,
+    assets: null,
+    research: null,
+    swot: null,
+    prd: null,
+    naming: null,
+    brand: null,
+    kit: null
+  };
+}
+function parseProgress(text) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new Error("That file isn't valid JSON.");
+  }
+  if (payload?.["app"] !== APP || !payload?.["state"]) {
+    throw new Error("That file isn't a Thought Layer progress file.");
+  }
+  const rawFormat = payload["format"];
+  const formatNewer = typeof rawFormat === "number" && rawFormat > PROGRESS_FORMAT;
+  const s = payload["state"] && typeof payload["state"] === "object" ? payload["state"] : {};
+  const obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
+  const state = {
+    ...s,
+    version: 2,
+    answers: obj(s["answers"]),
+    feedback: obj(s["feedback"]),
+    bizModel: s["bizModel"] ?? null,
+    grill: s["grill"] ?? null,
+    assets: s["assets"] ?? null,
+    research: s["research"] ?? null,
+    swot: s["swot"] ?? null,
+    prd: s["prd"] ?? null,
+    naming: s["naming"] ?? null,
+    brand: s["brand"] ?? null,
+    kit: s["kit"] ?? null
+  };
+  return {
+    app: APP,
+    format: typeof rawFormat === "number" ? rawFormat : PROGRESS_FORMAT,
+    exportedAt: typeof payload["exportedAt"] === "string" ? payload["exportedAt"] : "",
+    writer: payload["writer"],
+    state,
+    formatNewer
+  };
+}
+function buildProgress(state, writer, exportedAt) {
+  const s = state || {};
+  const {
+    answers,
+    feedback,
+    bizModel,
+    grill,
+    assets,
+    research,
+    swot,
+    prd,
+    naming,
+    brand,
+    kit,
+    version: _v,
+    exportedAt: _ea,
+    formatNewer: _fn,
+    ...rest
+  } = s;
+  return {
+    app: APP,
+    format: PROGRESS_FORMAT,
+    exportedAt,
+    writer,
+    formatNewer: false,
+    state: {
+      version: 2,
+      answers: answers || {},
+      feedback: feedback || {},
+      bizModel: bizModel ?? null,
+      grill: grill ?? null,
+      assets: assets ?? null,
+      research: research ?? null,
+      swot: swot ?? null,
+      prd: prd ?? null,
+      naming: naming ?? null,
+      brand: brand ?? null,
+      kit: kit ?? null,
+      ...rest
+    }
+  };
+}
+function serializeProgress(payload) {
+  const { formatNewer: _fn, ...wire } = payload;
+  return JSON.stringify(wire, null, 2) + "\n";
+}
+var clampConfidence = (n) => typeof n === "number" && !Number.isNaN(n) ? Math.min(1, Math.max(0, n)) : 0.6;
+function buildFeedbackEntry(opts) {
+  const { mode, personas: inputs, endState = "open", round = 1, ts } = opts;
+  const personas = {};
+  for (const p of inputs) {
+    const k = p.persona;
+    personas[k] = {
+      assessment: p.assessment || "",
+      confidence: clampConfidence(p.confidence),
+      confidenceRationale: p.confidenceRationale || "",
+      suggestions: (p.suggestions || []).slice(0, 3).map((sg, i) => ({
+        id: `${k}-${sg.id || `s${i + 1}`}`,
+        persona: k,
+        summary: sg.summary || "Suggestion",
+        patch: sg.patch || ""
+      }))
+    };
+  }
+  const keys = Object.keys(personas);
+  const confidence = aggregateConfidence(keys.map((k) => personas[k].confidence));
+  const status = statusFromConfidence(confidence);
+  const suggestions = keys.flatMap((k) => personas[k].suggestions);
+  const assessment = mode !== "panel" && personas[mode] ? personas[mode].assessment : "";
+  const entry = {
+    mode,
+    personas,
+    confidence,
+    status,
+    assessment,
+    suggestions,
+    appliedIds: [],
+    todos: [],
+    round,
+    overridden: false,
+    exited: false,
+    stale: false,
+    ts
+  };
+  if (endState === "setAside") {
+    const seen = /* @__PURE__ */ new Set();
+    const todos = suggestions.filter((sg) => seen.has(sg.id) ? false : (seen.add(sg.id), true));
+    return { ...entry, overridden: true, exited: true, status: "green", todos };
+  }
+  return entry;
+}
+function normalizeRequirements(reqs) {
+  return (reqs || []).map((r, i) => ({
+    id: r.id || `r${i + 1}`,
+    category: r.category || "functional",
+    text: r.text ?? r.statement ?? ""
+  }));
+}
+function normalizeArtifactValue(key, value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  if (key === "prd" || key === "grill") {
+    const v = value;
+    if (Array.isArray(v["requirements"])) {
+      return { ...v, requirements: normalizeRequirements(v["requirements"]) };
+    }
+  }
+  return value;
+}
+var isFilled = (v) => typeof v === "string" ? v.trim().length > 0 : Array.isArray(v) ? v.length > 0 : v != null && typeof v === "object" ? Object.keys(v).length > 0 : v != null;
+function summarizeState(state) {
+  const answers = state.answers || {};
+  const answered = Object.keys(answers).filter((k) => isFilled(answers[k])).length;
+  const byStatus = { green: 0, yellow: 0, red: 0, ungraded: 0 };
+  for (const v of Object.values(state.feedback || {})) {
+    const fb = v;
+    const s = fb?.overridden ? "green" : fb?.status;
+    if (s === "green" || s === "yellow" || s === "red") byStatus[s]++;
+    else byStatus.ungraded++;
+  }
+  const artifacts = ["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand"].filter((k) => state[k] != null);
+  const kit = state.kit && typeof state.kit === "object" ? state.kit : null;
+  return {
+    answered,
+    totalAnswerable: ANSWERABLE_QIDS.length,
+    byStatus,
+    artifacts,
+    cursor: kit?.cursor ?? null,
+    modulesRun: kit?.modulesRun ?? []
+  };
+}
+function withKit(state, patch, ts) {
+  const prev = state.kit && typeof state.kit === "object" ? state.kit : { schema: 1, updatedAt: ts };
+  return { ...prev, ...patch, schema: 1, updatedAt: ts };
+}
+function setAnswer(state, qId, value, ts) {
+  if (!isAnswerableQid(qId)) {
+    throw new Error(`"${qId}" is not an answerable Thought Layer question id. The agent leaves web-app-only fields to the founder; module sub-stage notes belong in kit.panelMeta.`);
+  }
+  return { ...state, answers: { ...state.answers, [qId]: value }, kit: withKit(state, {}, ts) };
+}
+function setArtifact(state, key, value, ts) {
+  return { ...state, [key]: value, kit: withKit(state, {}, ts) };
+}
+function setCursor(state, cursor, ts) {
+  return { ...state, kit: withKit(state, { cursor }, ts) };
+}
+function parkNote(state, key, note, ts) {
+  const prev = state.kit && typeof state.kit === "object" ? state.kit : { schema: 1, updatedAt: ts };
+  const parked = { ...prev.parked || {} };
+  parked[key] = [...parked[key] || [], note];
+  return { ...state, kit: withKit(state, { parked }, ts) };
+}
+
+// core/state-file.ts
+var STATE_DIR = ".thought-layer";
+var STATE_FILE = "state.json";
+function resolveStatePath(target, cwd = process.cwd()) {
+  if (!target) return join(cwd, STATE_DIR, STATE_FILE);
+  const abs = isAbsolute(target) ? target : resolve(cwd, target);
+  return abs.endsWith(".json") ? abs : join(abs, STATE_DIR, STATE_FILE);
+}
+function loadStateFile(target, cwd) {
+  const path = resolveStatePath(target, cwd);
+  if (!existsSync(path)) {
+    const state = emptyState();
+    return { path, exists: false, payload: buildProgress(state, { kind: "kit", ts: 0 }, ""), state };
+  }
+  const payload = parseProgress(readFileSync(path, "utf8"));
+  return { path, exists: true, payload, state: payload.state };
+}
+function saveStateFile(state, opts) {
+  const path = resolveStatePath(opts.target, opts.cwd);
+  mkdirSync(dirname(path), { recursive: true });
+  const writer = { kind: "kit", ts: opts.ts };
+  if (opts.version) writer.version = opts.version;
+  const text = serializeProgress(buildProgress(state, writer, opts.exportedAt));
+  writeFileSync(path, text);
+  return { path, bytes: Buffer.byteLength(text) };
+}
+
+// core/state-ops.ts
+var ARTIFACT_KEYS = ["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand"];
+var END_STATES = ["open", "pass", "setAside"];
+function applyStateOp(p, ctx) {
+  const { ts, exportedAt } = ctx;
+  const fail = (message) => ({ ok: false, message, details: {} });
+  try {
+    const loaded = loadStateFile(p.path);
+    const save = (next) => saveStateFile(next, { target: p.path, ts, exportedAt }).path;
+    if (p.op === "read" || p.op === "export") {
+      const sum = summarizeState(loaded.state);
+      const message = loaded.exists ? `Loaded ${loaded.path}: ${sum.answered}/${sum.totalAnswerable} answered (${sum.byStatus.green} green, ${sum.byStatus.yellow} yellow, ${sum.byStatus.red} red), artifacts: ${sum.artifacts.join(", ") || "none"}. Resume at ${sum.cursor ? `stage ${sum.cursor.backboneStage ?? "?"} (${sum.cursor.phase ?? "?"})` : "the beginning"}.` : `No state file yet at ${loaded.path}. Start a fresh run; it will be created on first write.`;
+      return { ok: true, message, details: { path: loaded.path, exists: loaded.exists, summary: sum, state: loaded.state } };
+    }
+    if (p.op === "answer") {
+      if (!p.qId || typeof p.value !== "string") return fail("answer needs a qId and a string value.");
+      const path = save(setAnswer(loaded.state, p.qId, p.value, ts));
+      return { ok: true, message: `Recorded answer for "${p.qId}" and saved ${path}.`, details: { path, qId: p.qId } };
+    }
+    if (p.op === "feedback") {
+      if (!p.qId || !p.personas?.length) return fail("feedback needs a qId and at least one persona.");
+      const endState = END_STATES.includes(p.endState || "") ? p.endState : "open";
+      const mode = p.mode || (p.personas.length > 1 ? "panel" : p.personas[0].persona);
+      const entry = buildFeedbackEntry({ mode, personas: p.personas, endState, round: p.round, ts });
+      const next = { ...loaded.state, feedback: { ...loaded.state.feedback, [p.qId]: entry } };
+      const path = save(next);
+      const grade = gradeFromConfidence(entry.confidence);
+      const pct = entry.confidence != null ? `${(entry.confidence * 100).toFixed(0)}%` : "n/a";
+      const tail = endState === "setAside" ? `, set aside with ${entry.todos.length} to-do(s)` : endState === "pass" ? ", cleared the bar" : "";
+      return {
+        ok: true,
+        message: `Recorded panel verdict for "${p.qId}": confidence ${pct} -> ${entry.status}, grade ${grade}${tail}. Saved ${path}.`,
+        details: { path, qId: p.qId, confidence: entry.confidence, status: entry.status, grade }
+      };
+    }
+    if (p.op === "artifact") {
+      const key = p.artifact;
+      if (!ARTIFACT_KEYS.includes(key)) return fail(`artifact needs a key in: ${ARTIFACT_KEYS.join(", ")}.`);
+      if (p.value == null) return fail("artifact needs a value object.");
+      const path = save(setArtifact(loaded.state, key, normalizeArtifactValue(key, p.value), ts));
+      return { ok: true, message: `Stored ${key} artifact and saved ${path}.`, details: { path, artifact: key } };
+    }
+    if (p.op === "cursor") {
+      if (!p.cursor) return fail("cursor needs a cursor object.");
+      const path = save(setCursor(loaded.state, p.cursor, ts));
+      return { ok: true, message: `Saved resume cursor (stage ${p.cursor.backboneStage ?? "?"}, ${p.cursor.phase ?? "?"}) to ${path}.`, details: { path } };
+    }
+    if (p.op === "park") {
+      if (!p.key || !p.note) return fail("park needs a key and a note.");
+      const path = save(parkNote(loaded.state, p.key, p.note, ts));
+      return { ok: true, message: `Parked a note under "${p.key}" and saved ${path}.`, details: { path, key: p.key } };
+    }
+    return fail(`Unknown op "${p.op}". Use read, answer, feedback, artifact, cursor, park, or export.`);
+  } catch (e) {
+    return fail(`tl_state error: ${e.message}`);
+  }
+}
+
+// bin/tl.ts
+var HELP = `tl - read/write the portable Thought Layer state file (.thought-layer/state.json)
+
+  tl read [path] [--json]            where the run stands
+  tl export [path]                   handoff check
+  tl answer <qId> <value> [path]     record an answer
+  tl feedback --data '<json>'        record a panel verdict ({qId,mode,personas,endState,round})
+  tl artifact <key> --data '<json>'  store an artifact value object
+  tl cursor --data '<json>'          save the resume cursor object
+  tl park <key> <note> [path]        stash a panel note
+  tl exec --data '<json>'            run a full {op,...} payload
+
+  --path <p>  project dir or .json path   --data <j>  JSON payload ("-" = stdin)
+  --json      print details JSON          -h, --help`;
+function parseArgs(argv) {
+  const args = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") flags["help"] = true;
+    else if (a === "--json") flags["json"] = true;
+    else if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else flags[key] = true;
+    } else args.push(a);
+  }
+  return { args, flags };
+}
+function readData(flags) {
+  const d = flags["data"];
+  if (d === void 0) return void 0;
+  const raw = d === "-" || d === true ? readFileSync2(0, "utf8") : String(d);
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error("--data is not valid JSON.");
+  }
+}
+function buildOp(args, flags) {
+  const op = args[0];
+  const path = typeof flags["path"] === "string" ? flags["path"] : void 0;
+  const data = readData(flags);
+  switch (op) {
+    case "read":
+    case "export":
+      return { op, path: path ?? args[1] };
+    case "answer":
+      return { op, qId: args[1], value: args[2], path: path ?? args[3] };
+    case "park":
+      return { op, key: args[1], note: args[2], path: path ?? args[3] };
+    case "feedback":
+      return { op, path, ...data || {} };
+    case "artifact":
+      return { op, artifact: args[1], value: data, path };
+    case "cursor":
+      return { op, cursor: data || {}, path };
+    case "exec":
+      return { path, ...data || {} };
+    default:
+      throw new Error(`Unknown command "${op ?? ""}". Run \`tl --help\`.`);
+  }
+}
+function main() {
+  const { args, flags } = parseArgs(process.argv.slice(2));
+  if (args[0] === "tl" || args[0] === "thought-layer") args.shift();
+  if (flags["help"] || args.length === 0) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  let payload;
+  try {
+    payload = buildOp(args, flags);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+    return;
+  }
+  const r = applyStateOp(payload, { ts: Date.now(), exportedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  if (flags["json"]) console.log(JSON.stringify(r.details, null, 2));
+  else console.log(r.message);
+  process.exit(r.ok ? 0 : 1);
+}
+main();

package/extensions/thought-layer.ts

@@ -9,7 +9,8 @@ import {
   aggregateConfidence, statusFromConfidence, gradeFromConfidence,
   checkDomains, registrarSearchUrl,
   computeProjection, fmtMoney,
-  type Assumptions,
+  applyStateOp,
+  type Assumptions, type StateOp,
 } from "../core/index.ts";
 
 const text = (t: string, details?: Record<string, unknown>): ToolResult => ({
@@ -125,4 +126,57 @@ export default function (pi: ExtensionAPI) {
       return text(`Projection summary:\n${body}`, { summary: s });
     },
   });
+
+  // tl_state: read, update, and write the portable Thought Layer state file
+  // (.thought-layer/state.json) so a co-founder using the web app and an agent
+  // share ONE lossless file. This owns the feedback-envelope assembly and
+  // artifact normalization, so the model supplies prose + numbers and never
+  // hand-writes the JSON (the main way the file gets corrupted).
+  const SuggestionSchema = Type.Object({
+    id: Type.Optional(Type.String()),
+    summary: Type.Optional(Type.String()),
+    patch: Type.Optional(Type.String()),
+  });
+  const PersonaSchema = Type.Object({
+    persona: Type.String({ description: "redteam | expert | investor, or the single chosen persona key." }),
+    assessment: Type.Optional(Type.String()),
+    confidence: Type.Number({ description: "0 to 1, this persona's confidence." }),
+    confidenceRationale: Type.Optional(Type.String()),
+    suggestions: Type.Optional(Type.Array(SuggestionSchema)),
+  });
+  pi.registerTool({
+    name: "tl_state",
+    label: "Thought Layer: state",
+    description:
+      "Read, update, and write the portable Thought Layer progress file (.thought-layer/state.json) shared with the web app so work passes losslessly between a founder in the browser and an agent. " +
+      "ops: 'read' (resume: where the run stands), 'answer' (record a question answer), 'feedback' (record a panel verdict - pass it the per-persona prose + confidences and it builds the exact entry), " +
+      "'artifact' (store prd/grill/bizModel/naming/brand/etc., requirements auto-normalized), 'cursor' (save resume position), 'park' (stash a panel note with no web-app question), 'export' (report the current file for handoff). " +
+      "Always use this instead of writing the JSON by hand.",
+    parameters: Type.Object({
+      op: Type.Union([
+        Type.Literal("read"), Type.Literal("answer"), Type.Literal("feedback"),
+        Type.Literal("artifact"), Type.Literal("cursor"), Type.Literal("park"), Type.Literal("export"),
+      ], { description: "The operation to perform." }),
+      path: Type.Optional(Type.String({ description: "Project dir or .json path. Defaults to ./.thought-layer/state.json in the cwd." })),
+      qId: Type.Optional(Type.String({ description: "Question id (for 'answer'/'feedback'). Must be a real Thought Layer question id." })),
+      value: Type.Optional(Type.Unknown({ description: "For 'answer': the answer string. For 'artifact': the artifact object." })),
+      artifact: Type.Optional(Type.String({ description: "For 'artifact': one of bizModel, grill, assets, research, swot, prd, naming, brand." })),
+      mode: Type.Optional(Type.String({ description: "For 'feedback': 'panel' (3 personas) or a single persona key." })),
+      personas: Type.Optional(Type.Array(PersonaSchema, { description: "For 'feedback': one entry per persona with its assessment + confidence." })),
+      endState: Type.Optional(Type.String({ description: "For 'feedback': 'open' (still iterating), 'pass' (cleared 0.85), or 'setAside' (frozen with to-dos)." })),
+      round: Type.Optional(Type.Number({ description: "For 'feedback': which feedback round this is (default 1)." })),
+      cursor: Type.Optional(Type.Object({
+        stage: Type.Optional(Type.String()),
+        backboneStage: Type.Optional(Type.Number()),
+        lastQuestionId: Type.Optional(Type.String()),
+        phase: Type.Optional(Type.String()),
+      }, { description: "For 'cursor': the resume position." })),
+      key: Type.Optional(Type.String({ description: "For 'park': a synthetic note key, e.g. 'brand.voice' or 'mr.willingness-to-pay'." })),
+      note: Type.Optional(Type.String({ description: "For 'park': the note to stash under the kit namespace." })),
+    }),
+    async execute(_id, params): Promise<ToolResult> {
+      const r = applyStateOp(params as StateOp, { ts: Date.now(), exportedAt: new Date().toISOString() });
+      return text(r.message, r.details);
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobocode/thought-layer",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "The Thought Layer: rigor for building. Validate an idea, grill it into a buildable spec, then build and deploy it, inside the agent you already use. BYOK, no telemetry.",
   "license": "MIT",
   "author": "Hobocode LLC <jerm@hobocode.net>",
@@ -25,10 +25,16 @@
   "exports": {
     "./core": "./core/index.ts"
   },
+  "bin": {
+    "thought-layer": "./dist/tl.js",
+    "tl": "./dist/tl.js"
+  },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "build": "tsup",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.0"
@@ -41,6 +47,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"
   },
@@ -52,6 +59,12 @@
     "core/scoring.ts",
     "core/domains.ts",
     "core/model.ts",
+    "core/progress.ts",
+    "core/stages.ts",
+    "core/stage-map.ts",
+    "core/state-file.ts",
+    "core/state-ops.ts",
+    "dist",
     "README.md",
     "LICENSE"
   ]

package/skills/thought-layer-brand/SKILL.md

@@ -99,4 +99,8 @@ Its finished output feeds back, mapped block by block — one canonical mapping,
 - **The whole kit** receives the **Name**, produced here via `thought-layer-naming` and checked with `tl_domains`.
 - **The design phase (framework Part 3)** receives the **Personality**, the **Voice**, and the **Visual & Identity Direction** as notes for the PRD's UX and identity sections — direction only. This module never drafts the PRD and never grills; the design phase remains the framework's Part 3, **PRD first and the grill second**, and the final logos, palettes, and screens are produced there, not here.
 
+## Persisting (multi-session)
+
+Keep the shared state file current as the brand takes shape (see the framework skill's "Saving and resuming"). Record the brand-feel and what-it-is-not answers against `brand-feel` and `brand-unlike` via the state tool, store the chosen name as the `naming` artifact and the guide as the `brand` artifact (op `artifact`), and leave the final logos, palettes, and screens to the design phase / web app. Sub-stage verdicts with no web-app question (promise, emotional job, personality, voice, visual direction) go to op `park` (a key like `brand.voice`), never into answers. If neither `tl_state` nor `tl` is available, carry the brief in chat.
+
 It takes positioning as input and expresses it; it never sets or relitigates competitive strategy (that is `thought-layer-strategy` and backbone Market Selection), and it never starts the design phase.

package/skills/thought-layer-business-model/SKILL.md

@@ -104,4 +104,8 @@ Its finished output feeds back into the backbone, mapped block by block — one
 - **Business Model (stage 10)** receives the **Revenue Model & Money Flow**, the **Unit Economics**, and the **Scenario Modeling**.
 - **Scale Expectations (stage 8)** receives the **scenario projections** as an evidence anchor, alongside market-research's SOM; the two reconcile (scenario year-one revenue should sit inside the winnable SOM) and the 12-month and 3-year calls stay the founder's.
 
-It never drafts the PRD and never grills; the design phase remains the framework's Part 3, PRD first and the grill second.
+It never drafts the PRD and never grills; the design phase remains the framework's Part 3, PRD first and the grill second.
+
+## Persisting (multi-session)
+
+Keep the shared state file current as the model firms up (see the framework skill's "Saving and resuming"). Record the deepened answers against their web-app question ids via the state tool — Costs to `cost-architecture`/`cost-risk`, Pricing to `pricing-model`, the parties to `bm-who-buys`/`bm-who-supplies`/`bm-parties` — and store the numeric model (the `tl_project` output and its assumptions) as the `bizModel` artifact (op `artifact`). Sub-stage verdicts with no web-app question (money flow, unit economics, cost stress, scenarios) go to op `park` (a key like `bm.unit-economics`), never into answers. If neither `tl_state` nor `tl` is available, carry the model in chat.

package/skills/thought-layer-framework/SKILL.md

@@ -20,6 +20,43 @@ Then walk the stages below **in order, one stage per turn**. For each stage:
 
 Reaching the Grill or the PRD before all of Part 1 (validate the idea) and Part 2 (the business model) are worked through is the signature failure of this framework. Do not do it. The Grill and the PRD are the design phase and they come last.
 
+## Saving and resuming (this runs across many sessions)
+
+No one finishes this in one sitting. The work lives in a portable file, `.thought-layer/state.json`, in the project directory. It is your memory across turns and sessions, and it is the SAME interop file the web app reads, so a founder can answer some stages here and hand the file to a co-founder who continues in the web app (weareallproductmanagersnow.com, "Load progress from file"), back and forth, losslessly. Never hand-write this JSON: use the tool below, which builds the exact shapes the web app expects.
+
+**The tool.** If the `tl_state` tool is available (Pi), use it. Otherwise run the CLI from any shell: `npx -y @hobocode/thought-layer tl <op> ...` (or just `tl ...` if the package is installed). Ops: `read`, `answer`, `feedback`, `artifact`, `cursor`, `park`, `export`.
+
+**On start, ALWAYS read first.** `tl_state read` (or `tl read`). If a file exists, summarize where the run stands and **resume from the saved cursor** - do not restart at stage 1. If not, start fresh; the file is created on first write.
+
+**After each stage:**
+1. Record the answer against its question id: `tl_state` op `answer` (or `tl answer <qId> "<value>"`).
+2. Record the panel verdict: `tl_state` op `feedback` - pass it the per-persona assessments + confidences and the end state (`pass` when confidence clears 0.85, `setAside` when the user sets it aside with to-dos, else `open`). The tool computes the status, grade, and to-dos; you supply only prose + numbers.
+3. Save the cursor: `tl_state` op `cursor` with the backbone stage number and phase, so the next session resumes exactly here.
+
+**Stage to question id** (use these exact ids; the tool rejects unknown ones):
+
+| Stage | id(s) |
+|---|---|
+| 1 Concise What | `what-statement` |
+| 2 Domain Knowledge | `domain-experience`, `domain-gaps` |
+| 3 Validation | `paid-today`, `evidence` |
+| 4 Market Selection | `target-market`, `incumbent-gap` |
+| 5 30-Second Test | `pitch` |
+| 6 Time | `commitment` |
+| 7 Costs | `cost-architecture`, `cost-risk` |
+| 8 Scale | `realistic-goal` |
+| 9 Pricing | `pricing-model` |
+| 10 Business Model | `bm-who-buys`, `bm-who-supplies`, `bm-parties` (+ `bizModel` artifact) |
+| 11 Customer Acquisition | `first-ten`, `retention` |
+| 12 Customer Relationships | `crm-approach`, `crm-community` |
+| 13 Support | `support-model`, `support-scaling` |
+| 14 PRD | `prd-problem`, `prd-not-building` (+ `prd` artifact) |
+| 15 Grill | `grill` artifact (re-compose `prd` markdown on done) |
+
+**Artifacts** (PRD, grill, bizModel, naming, brand, swot, research) go through op `artifact`, which normalizes them to the web app's shapes. **Web-app-only fields** - the Decision Support questions (`dq-*`), the press-release fields, and the launch-asset fields - have no stage here; leave them for the founder in the web app, do not write them. **Module sub-stage verdicts** that have no web-app question (the deep-dive modules' internal stages) go to op `park`, never into answers.
+
+**At session end or handoff,** run `export` to confirm the file is current, and tell the founder where it is and that they (or a collaborator) can load it into the web app or keep going with the agent.
+
 ## Part 1: Validate the idea
 
 Altitude: is the idea clear, honest, real, and worth pursuing? Not how it will be built.

package/skills/thought-layer-grill/SKILL.md

@@ -56,6 +56,10 @@ Update the draft PRD in place, keeping two living artifacts inside it current:
 
 When the grilling is complete, the hardened PRD — with its sharpened glossary and completed requirements — is the build brief the build step consumes.
 
+## Persisting (multi-session)
+
+Keep the shared state file current as you harden the PRD, so the work survives the session and round-trips to the web app and a co-founder. Store the grill artifact via the state tool: `tl_state` op `artifact` with `artifact: "grill"` and `{ transcript, requirements, glossary, done, doneSummary }` (or `tl artifact grill --data '<json>'`); each requirement carries `statement`, which the tool remaps to the web app's `text`. When the grill is done, re-compose the hardened glossary + requirements into the PRD prose and store that too (`artifact: "prd"`), so an imported file shows the hardened spec, not the stale draft. If neither `tl_state` nor `tl` is available, just keep the PRD updated in chat. See the framework skill's "Saving and resuming."
+
 ## Credit
 
 The "grill" — a relentless, one-question-at-a-time interview that grills an existing plan, sharpens the domain glossary, and surfaces contradictions, updating the doc inline as decisions crystallize — is inspired by Matt Pocock's [`grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md) skill (MIT, © Matt Pocock). His grills an architecture plan against the existing domain model and docs; this skill adapts the same technique to grill a draft PRD against the domain and harden it inline. Thank you, Matt.

package/skills/thought-layer-market-research/SKILL.md

@@ -102,4 +102,8 @@ Its finished output feeds back into the backbone, mapped block by block — one
 - **Market Selection (stage 4)** receives the **ICP**, the **Market Sizing / SOM**, the **Competitive Landscape**, the **Wedge**, and **Why Now**.
 - **Pricing (stage 9)** receives the **Willingness to Pay** evidence — the anchors, not the final number.
 
-The **SOM** additionally anchors backbone stage 8 (Scale Expectations), and **Channels** additionally feeds backbone stage 11 (Customer Acquisition) as reachability evidence. It never drafts the PRD and never grills; the design phase remains the framework's Part 3, PRD first and the grill second.
+The **SOM** additionally anchors backbone stage 8 (Scale Expectations), and **Channels** additionally feeds backbone stage 11 (Customer Acquisition) as reachability evidence. It never drafts the PRD and never grills; the design phase remains the framework's Part 3, PRD first and the grill second.
+
+## Persisting (multi-session)
+
+This deep-dive runs across sessions, so keep the shared state file current (see the framework skill's "Saving and resuming"). When the evidence feeds back to a backbone stage, record that answer against its web-app question id via the state tool — Validation to `evidence`/`paid-today`, Market Selection to `target-market`/`incumbent-gap`, Pricing to `pricing-model` — and store the write-up as the `research` artifact (op `artifact`). The module's own sub-stage verdicts (ICP, sizing, WTP, and the rest) have no web-app question: stash them with op `park` (a key like `mr.willingness-to-pay`), never in answers. If neither `tl_state` nor `tl` is available, just carry the evidence ledger in chat.

package/skills/thought-layer-prd/SKILL.md

@@ -36,3 +36,7 @@ Write in clear prose with markdown headings:
 - Make the success metrics honest outcomes, not vanity: draft a north-star metric tied to delivered customer value (one that moves only when customers get the promised outcome), at least one counter-metric it could break, and a leading plus lagging pair. The grill holds these to its metric-honesty rule.
 
 Output only the markdown document, no preamble.
+
+## Persisting (multi-session)
+
+After composing the draft, save it to the shared state file so it survives the session and round-trips to the web app and any co-founder, rather than living only in chat. Store it via the state tool: `tl_state` op `artifact` with `artifact: "prd"` and `{ markdown, glossary, requirements, weakestAssumptions }` (or the CLI `tl artifact prd --data '<json>'`). Each requirement may carry `statement` for its wording; the tool remaps that to the web app's `text` field for you. If neither `tl_state` nor `tl` is available, just output the markdown. See the framework skill's "Saving and resuming."

package/skills/thought-layer-strategy/SKILL.md

@@ -103,4 +103,8 @@ Its finished output feeds back into the backbone, mapped block by block — one
 - **Market Selection (stage 4)** receives the **Strategic Positioning** (where to play and what you refuse), the **Moat mechanism and its clock**, the **Beachhead → Expansion sequence**, the **Incumbent-response counter**, and the **Strategic Bets** — the full case that the chosen market is not just real but winnable and defensible over multiple years.
 - **The 30-Second Test (stage 5)** is *informed* by the positioning statement (it sharpens what the pitch must convey) but receives no pitch from this module; writing the one-sentence pitch stays the founder's call in the backbone.
 
-Boundaries it holds to the end: it takes the buyer, the market size, the demand evidence, the competitive map, the wedge's existence, why-now, and market-research's first-pass defensibility window and structural-incumbent sketch as input and does not re-derive them (it deepens the window and structural sketch in stages 2 and 4 rather than rebuilding them); it sets positioning but hands brand promise, personality, voice, name, and visual direction to **thought-layer-brand**, which expresses that positioning; and it sets the strategic spine but hands deep unit economics, pricing-and-packaging, and scenario modeling to **thought-layer-business-model**. It never drafts the PRD and never grills; the design phase remains the framework's Part 3, PRD first and the grill second.
+Boundaries it holds to the end: it takes the buyer, the market size, the demand evidence, the competitive map, the wedge's existence, why-now, and market-research's first-pass defensibility window and structural-incumbent sketch as input and does not re-derive them (it deepens the window and structural sketch in stages 2 and 4 rather than rebuilding them); it sets positioning but hands brand promise, personality, voice, name, and visual direction to **thought-layer-brand**, which expresses that positioning; and it sets the strategic spine but hands deep unit economics, pricing-and-packaging, and scenario modeling to **thought-layer-business-model**. It never drafts the PRD and never grills; the design phase remains the framework's Part 3, PRD first and the grill second.
+
+## Persisting (multi-session)
+
+Keep the shared state file current as the strategy lands (see the framework skill's "Saving and resuming"). The deepened positioning, moat, sequence, incumbent-response, and bets feed **Market Selection** — record that answer against `target-market` and `incumbent-gap` via the state tool, and store the SWOT as the `swot` artifact (op `artifact`). The module's own sub-stage verdicts (positioning, moat, beachhead, incumbent-response, bets) have no web-app question: stash them with op `park` (a key like `strategy.moat`), never in answers. If neither `tl_state` nor `tl` is available, carry the strategy ledger in chat.