@productbrain/mcp 0.0.1-beta.5912 → 0.0.1-beta.5946

package/dist/{chunk-PTC2REQA.js → chunk-7T4HSTNG.js}

@@ -1554,6 +1554,8 @@ var groundingGovernanceEntrySchema = z4.object({
   collectionSlug: z4.string()
 });
 var groundingReportSchema = z4.object({
+  // TASK-156: null preserves uncertainty for unavailable checks or an older server response.
+  scanTruncated: z4.boolean().nullable(),
   related: z4.array(groundingRelatedEntrySchema),
   duplicates: z4.array(groundingDuplicateEntrySchema),
   governance: z4.array(groundingGovernanceEntrySchema)
@@ -1680,6 +1682,9 @@ function reconcileBatchPreviewDuplicate(tracker, args) {
   return null;
 }
 
+// src/lib/readinessNotices.ts
+var READINESS_PROVISIONAL_LINE = "Readiness is provisional: its sample omitted accepted entries. Counts are lower bounds, apparent gaps may already be covered, and the overall stage is unverified.";
+
 // src/tools/smart-capture.ts
 var GENERIC_PROFILE = {
   governedDraft: false,
@@ -2265,9 +2270,8 @@ async function handleCapture(server, { collection, name, description, context, e
     };
   }
   const profile = await getProfile(resolvedCollection);
-  const skipAutoDiscoveryEarly = links && links.length > 0;
   const groundingStart = Date.now();
-  const groundingPromise = !skipAutoDiscoveryEarly && (name || description) ? kernelQuery("chain.suggestLinksForCapture", {
+  const groundingPromise = name || description ? kernelQuery("chain.suggestLinksForCapture", {
     entries: [{ name, description: description ?? "", collectionHint: resolvedCollection }],
     limit: 5,
     threshold: 2
@@ -2286,6 +2290,8 @@ async function handleCapture(server, { collection, name, description, context, e
     collectionSlug: g.collectionSlug
   }));
   const groundingReport = {
+    // null preserves uncertainty for unavailable checks or an older server response.
+    scanTruncated: typeof groundingEntry?.scanTruncated === "boolean" ? groundingEntry.scanTruncated : null,
     related: groundingRelated.map((r) => ({
       entryId: r.entryId,
       name: r.name,
@@ -2303,9 +2309,10 @@ async function handleCapture(server, { collection, name, description, context, e
     })),
     governance: groundingGovernance
   };
+  const groundingCaveat = !groundingEntry ? "Grounding could not be completed; duplicate presence is unknown. Review existing entries before creating another." : groundingReport.scanTruncated !== false ? "Grounding covered a bounded sample; completeness is unverified and additional matching entries may exist. Review existing entries before creating another." : "";
   if (suggestOnly) {
     const hasSuggestions = groundingReport.related.length > 0 || groundingReport.duplicates.length > 0;
-    const summaryText = hasSuggestions ? `Grounding preview for "${name}": ${groundingReport.related.length} related, ${groundingReport.duplicates.length} possible duplicates. No entry created.` : `Grounding preview for "${name}": no similar entries found. Safe to capture.`;
+    const summaryText = hasSuggestions ? `Grounding preview for "${name}": ${groundingReport.related.length} related, ${groundingReport.duplicates.length} possible duplicates. No entry created.` : groundingEntry ? `Grounding preview for "${name}": no similar entries found in this check. No entry created.` : `Grounding preview for "${name}": duplicate check unavailable. No entry created.`;
     return {
       content: [{
         type: "text",
@@ -2313,7 +2320,9 @@ async function handleCapture(server, { collection, name, description, context, e
 
 ${summaryText}
 
-` + (groundingReport.related.length > 0 ? `## Related entries
+` + (groundingCaveat ? `${groundingCaveat}
+
+` : "") + (groundingReport.related.length > 0 ? `## Related entries
 ${groundingReport.related.map((r) => `- **${r.entryId}** ${r.name} [${r.collectionSlug}] \u2014 ${r.reasoning}`).join("\n")}
 
 ` : "") + (groundingReport.duplicates.length > 0 ? `## Possible duplicates
@@ -2569,7 +2578,7 @@ Use \`entries action=get\` to inspect the existing entry, or \`entries action=up
   const linksSuggested = [];
   const userLinkResults = [];
   const advisedLinks = [];
-  let conflictCandidates = [];
+  const conflictCandidates = groundingReport.duplicates.filter((candidate) => candidate.matchType === "possible_duplicate" && candidate.entryId !== finalEntryId).slice(0, 3).map((candidate) => ({ entryId: candidate.entryId, name: candidate.name, collection: candidate.collectionSlug }));
   const pendingRelations = [];
   const skipAutoDiscovery = links && links.length > 0;
   const searchQuery = extractSearchTerms(name, description);
@@ -2646,7 +2655,6 @@ Use \`entries action=get\` to inspect the existing entry, or \`entries action=up
       const reason = c.confidence >= AUTO_LINK_CONFIDENCE_THRESHOLD ? "high relevance (already linked)" : `"${c.name.toLowerCase().split(/\s+/).filter((w) => `${name} ${description}`.toLowerCase().includes(w) && w.length > 3).slice(0, 2).join('", "')}" appears in content`;
       linksSuggested.push({ entryId: c.entryId, name: c.name, collection: c.collSlug, reason, preview: c.preview });
     }
-    conflictCandidates = candidates.filter((c) => c.entryId && c.entryId !== finalEntryId).slice(0, 3).map((c) => ({ entryId: c.entryId, name: c.name, collection: c.collSlug }));
   }
   if (links && links.length > 0 && finalEntryId) {
     for (const link of links) {
@@ -2678,8 +2686,8 @@ Use \`entries action=get\` to inspect the existing entry, or \`entries action=up
     entryWarnings.push(`Auto-linking partially failed: ${err instanceof Error ? err.message : "unknown error"}`);
     return null;
   }) : Promise.resolve(null);
-  const cardinalityPromise = resolvedCK ? kernelQuery("chain.checkCardinalityWarning", { canonicalKey: resolvedCK }).catch(() => null) : Promise.resolve(null);
-  const contradictionPromise = runContradictionCheck(name, description);
+  const cardinalityPromise = resolvedCK ? kernelQuery("chain.checkCardinalityWarning", { canonicalKey: resolvedCK, excludeEntryId: internalId }).catch(() => null) : Promise.resolve(null);
+  const contradictionPromise = runContradictionCheck(name, description, finalEntryId, internalId);
   const coachingPromise = coachingFromCreate !== void 0 ? Promise.resolve(coachingFromCreate) : kernelMutation("quality.evaluateHeuristicAndSchedule", {
     entryId: finalEntryId,
     context: "capture"
@@ -2769,13 +2777,6 @@ Use \`entries action=get\` to inspect the existing entry, or \`entries action=up
   }
   const freshGovernanceMode = await refreshWorkspaceGovernanceMode();
   const shouldAutoCommit = shouldAutoCommitCapture(autoCommit, freshGovernanceMode);
-  if (shouldAutoCommit && finalEntryId && conflictCandidates.length === 0) {
-    try {
-      const conflictResults = await kernelQuery("chain.searchEntries", { query: name });
-      conflictCandidates = (conflictResults ?? []).filter((r) => r.entryId && r.entryId !== finalEntryId && r._id !== internalId).slice(0, 3).map((r) => ({ entryId: r.entryId, name: r.name, collection: r.collectionSlug ?? "unknown" }));
-    } catch {
-    }
-  }
   let finalStatus = "draft";
   let commitError = null;
   let commitRefusal = null;
@@ -2925,6 +2926,7 @@ Use \`entries action=get\` to inspect the existing entry, or \`entries action=up
       lines.push(`${i + 1}. **${s.entryId ?? "(no ID)"}**: ${s.name} [${s.collection}]${preview2}`);
     }
   }
+  if (groundingCaveat) lines.push("", groundingCaveat);
   if (format === "human") {
     const hasDuplicates = groundingReport.duplicates.length > 0;
     const hasRelated = groundingReport.related.length > 0;
@@ -2962,11 +2964,11 @@ Use \`entries action=get\` to inspect the existing entry, or \`entries action=up
     for (const rs of relationSuggestionsFromCreate) {
       lines.push(`- **${rs.relationType}** \u2192 ${rs.targetEntryId} "${rs.targetName}" (confidence: ${rs.confidence})`);
     }
-    lines.push(`_Create with: \`relations action=create fromId="${finalEntryId}" toId="TARGET-ID" type="TYPE"\`_`);
+    lines.push(`_Create with: \`relations action=create from="${finalEntryId}" to="TARGET-ID" type="TYPE"\`_`);
   }
   if (authorityDomainFromCreate) {
     lines.push("");
-    lines.push(`domain: ${authorityDomainFromCreate.slug} (proposal pending \u2014 ratify at session close)`);
+    lines.push(`domain: ${authorityDomainFromCreate.slug} (proposal pending \u2014 closing the session does not ratify it. A workspace owner or admin can review it with \`pb authority-domains review\` before deciding whether to ratify.)`);
   }
   if (formativeHints.length > 0) {
     trackCaptureQualityHints(wsCtx.workspaceId, {
@@ -3001,11 +3003,11 @@ Use \`entries action=get\` to inspect the existing entry, or \`entries action=up
   }
   if (contradictionWarnings.length > 0) {
     lines.push("");
-    lines.push("\u26A0 Contradiction check: proposed entry matched existing governance entries:");
+    lines.push("\u26A0 Contradiction check: captured entry matched existing governance entries:");
     for (const w of contradictionWarnings) {
       lines.push(`- ${w.name} (${w.collection}, ${w.entryId}) \u2014 has 'governs' relation to ${w.governsCount} entries`);
     }
-    lines.push("Run `context action=gather` on these entries before accepting.");
+    lines.push("Review the matched governance entries and reconcile any actual conflict.");
   }
   if (entryWarnings.length > 0) {
     lines.push("");
@@ -3043,7 +3045,9 @@ Use \`entries action=get\` to inspect the existing entry, or \`entries action=up
   }
   try {
     const readiness = await kernelQuery("chain.workspaceReadiness");
-    if (readiness && readiness.gaps && readiness.gaps.length > 0) {
+    if (readiness?.sampleTruncated) {
+      lines.push("", `## Workspace Readiness: ${readiness.score}% (provisional sample)`, READINESS_PROVISIONAL_LINE);
+    } else if (readiness && readiness.gaps && readiness.gaps.length > 0) {
       const topGaps = readiness.gaps.slice(0, 2);
       lines.push("");
       lines.push(`## Workspace Readiness: ${readiness.score}%`);
@@ -3694,10 +3698,10 @@ _Use \`entries action=move\` to correct any misclassified entries._`);
     const entriesWithOverlaps = created.filter((r) => r.overlapCount && r.overlapCount > 0);
     if (entriesWithOverlaps.length > 0) {
       lines.push("");
-      lines.push("## Potential Overlaps");
-      lines.push(`${entriesWithOverlaps.length} ${entriesWithOverlaps.length === 1 ? "entry has" : "entries have"} similar existing entries. Consider reviewing for duplicates:`);
+      lines.push("## Related-entry Suggestions");
+      lines.push(`${entriesWithOverlaps.length} ${entriesWithOverlaps.length === 1 ? "entry has" : "entries have"} link candidates. Review their relevance before linking:`);
       for (const r of entriesWithOverlaps) {
-        lines.push(`- **${r.entryId}**: ${r.name} \u2014 ${r.overlapCount} similar ${r.overlapCount === 1 ? "entry" : "entries"}`);
+        lines.push(`- **${r.entryId}**: ${r.name} \u2014 ${r.overlapCount} link ${r.overlapCount === 1 ? "candidate" : "candidates"}`);
       }
     }
   }
@@ -3865,7 +3869,7 @@ async function recordCommitFailure({
     }
   }
 }
-async function runContradictionCheck(name, description) {
+async function runContradictionCheck(name, description, excludeEntryId, excludeDocId) {
   const warnings = [];
   try {
     const keyTerms = tokenizeText(`${name} ${description}`).filter((w) => w.length >= 4 && !STOP_WORDS.has(w)).slice(0, 8);
@@ -3875,7 +3879,13 @@ async function runContradictionCheck(name, description) {
       kernelQuery("chain.searchEntries", { query: searchQuery, collectionSlug: "business-rules" }),
       kernelQuery("chain.searchEntries", { query: searchQuery, collectionSlug: "architecture" })
     ]);
-    const allGov = [...govResults ?? [], ...archResults ?? []].slice(0, 5);
+    const seen = /* @__PURE__ */ new Set();
+    const allGov = [...govResults ?? [], ...archResults ?? []].filter((entry) => {
+      const id = entry.entryId ?? entry._id;
+      if (!id || excludeEntryId && entry.entryId === excludeEntryId || excludeDocId && entry._id === excludeDocId || seen.has(id)) return false;
+      seen.add(id);
+      return true;
+    }).slice(0, 5);
     for (const entry of allGov) {
       const entryTokens = new Set(tokenizeText(`${entry.name} ${entry.data?.description ?? ""}`));
       const matched = keyTerms.filter((t) => entryTokens.has(t));
@@ -4859,7 +4869,7 @@ var entriesSchema = z10.object({
   entryIds: z10.array(z10.string().max(200)).min(1).max(20).optional().describe("Entry IDs for 'batch', e.g. ['TYPE-strategy', 'STR-jljeg7']"),
   collection: z10.string().max(200).optional().describe("Collection slug \u2014 for 'list'/'search': scope filter, e.g. 'glossary', 'tracking-events'. For 'preflight': the collection the entry would be composed into (required)."),
   status: entriesStatusFilterSchema.optional().describe(
-    "For 'list': one lifecycle value (draft|active|accepted|deprecated|archived; active/accepted are the same trust level). For 'search': one value OR an array of up to 5 (e.g. ['active','accepted']). For 'update': draft|active|deprecated|archived ONLY \u2014 'accepted' is set via 'commit', never 'update'. Workflow values use `workflowStatus` instead."
+    "For 'list': defaults to accepted entries (active/accepted); use status='draft' to discover drafts. One lifecycle value (draft|active|accepted|deprecated|archived). For 'search': one value OR an array of up to 5 (e.g. ['active','accepted']). For 'update': draft|active|deprecated|archived ONLY \u2014 'accepted' is set via 'commit', never 'update'. Workflow values use `workflowStatus` instead."
   ),
   tag: z10.string().max(200).optional().describe("For 'list': filter by internal tag."),
   label: z10.string().max(200).optional().describe("For 'list': filter by label slug \u2014 matches entries across all collections."),
@@ -4943,7 +4953,7 @@ var entriesActionUnion = z10.discriminatedUnion("action", [
 ]);
 var ENTRIES_ACTION_SPECS = {
   preflight: { params: ["collection", "canonicalKey", "links"], description: "Inspect structure before composition; no writes or permission grant." },
-  list: { params: ["collection", "status", "tag", "label"], description: "Browse entries; all params optional." },
+  list: { params: ["collection", "status", "tag", "label"], description: "Browse accepted entries by default; status='draft' lists drafts. All params optional." },
   get: { params: ["entryId"], description: "Fetch one entry by ID." },
   batch: { params: ["entryIds"], description: "Fetch up to 20 entries by ID." },
   search: { params: ["query", "collection", "status"], description: "Full-text search; query is required (min 2 chars)." },
@@ -5337,7 +5347,7 @@ async function handleBatch(entryIds) {
 async function handleList(collection, status2, tag, label) {
   let entries;
   if (label) {
-    entries = await kernelQuery("chain.listEntriesByLabel", { labelSlug: label });
+    entries = await kernelQuery("chain.listEntriesByLabel", { labelSlug: label, acceptedOnly: !status2 });
     if (status2) {
       entries = entries.filter((e) => e.status === status2);
     }
@@ -5349,10 +5359,11 @@ async function handleList(collection, status2, tag, label) {
     });
   }
   if (entries.length === 0) {
+    const emptyMessage = `No entries match the given filters.${!status2 ? " Default list scope is accepted entries (active/accepted); use status='draft' to discover drafts." : ` Status filter: ${status2}.`}`;
     return {
-      content: [{ type: "text", text: "No entries match the given filters." }],
+      content: [{ type: "text", text: emptyMessage }],
       structuredContent: success(
-        "No entries match the given filters.",
+        emptyMessage,
         { entries: [], total: 0 },
         [{ tool: "collections", description: "List collections", parameters: { action: "list" } }]
       )
@@ -7210,8 +7221,9 @@ function formatSteeringBrief(result2) {
   lines.push(`${delta.newEntries.length} new entries since last steering brief${delta.truncated ? " (TRUNCATED)" : ""}`);
   lines.push("");
   lines.push("## Workspace Readiness");
-  lines.push(`Score: **${readiness.score}%** (${readiness.passedChecks}/${readiness.totalChecks} checks passed)`);
-  if (readiness.gaps.length > 0) {
+  lines.push(`Score: **${readiness.score}%**${readiness.sampleTruncated ? " (provisional sample)" : ""} (${readiness.passedChecks}/${readiness.totalChecks} checks passed)`);
+  if (readiness.sampleTruncated) lines.push(READINESS_PROVISIONAL_LINE);
+  if (!readiness.sampleTruncated && readiness.gaps.length > 0) {
     lines.push("");
     lines.push("**Gaps:**");
     for (const gap of readiness.gaps.slice(0, 5)) {
@@ -7228,7 +7240,7 @@ function formatSteeringBrief(result2) {
   return {
     content: [{ type: "text", text: lines.join("\n") }],
     structuredContent: success(
-      `Steering brief: ${changes.entries.length} changes, ${delta.newEntries.length} new entries, ${readiness.score}% readiness.`,
+      `Steering brief: ${changes.entries.length} changes, ${delta.newEntries.length} new entries, ${readiness.score}% readiness${readiness.sampleTruncated ? " (provisional sample; gaps unverified)" : ""}.`,
       { ...result2, trustFilterActive: true }
     )
   };
@@ -8745,19 +8757,30 @@ function sanitizeSingleLineField(str) {
 }
 
 // src/tools/orient-rituals.ts
+var SPINE_UNAVAILABLE_LINE = "Spine check: unavailable \u2014 orient fetch failed, retry `orient`";
 function buildRitualsSurfaceLines(view, opts) {
   const lines = [""];
   if (opts?.fetchFailed) {
     lines.push("Direction: unavailable \u2014 orient fetch failed, retry `orient`");
-    lines.push("Spine check: unavailable \u2014 orient fetch failed, retry `orient`");
+    lines.push(SPINE_UNAVAILABLE_LINE);
     return lines;
   }
   lines.push(view?.directionLine ?? "Direction: not computed yet \u2014 `pb direction refresh`");
   if (view?.verdictAskLine) lines.push(view.verdictAskLine);
-  lines.push(view?.spineLine ?? "Spine check: not computed yet \u2014 `pb quality spine-check`");
+  if (view?.spineLine) lines.push(view.spineLine);
   if (view?.atCapLine) lines.push(view.atCapLine);
   return lines;
 }
+async function fetchAndRenderSetupSpineLine(kernelQuery2) {
+  try {
+    const view = await kernelQuery2("chain.getRitualsSurface", {
+      now: Math.floor(Date.now() / 6e4) * 6e4
+    });
+    return view?.spineLine ? [view.spineLine] : [];
+  } catch {
+    return [SPINE_UNAVAILABLE_LINE];
+  }
+}
 function toSafeCodeSpan(text) {
   const longestBacktickRun = (text.match(/`+/g) ?? []).reduce((max, run) => Math.max(max, run.length), 0);
   const fence = "`".repeat(longestBacktickRun + 1);
@@ -9096,15 +9119,18 @@ function pickNextTensionPrompt(openTensions) {
     cta: "Want to discuss this tension or capture a decision about it?"
   };
 }
-async function buildSetupResponse(agentSessionId) {
+async function buildSetupResponse(agentSessionId, sampleTruncated) {
   await kernelMutation(
     "setup.stampMcpOnlySurface",
     {}
   );
   const skill = await loadSkillBody(PB_SETUP_SKILL_ENTRY_ID);
   const { oriented, orientationStatus } = await tryMarkOriented(agentSessionId);
+  const spineLines = await fetchAndRenderSetupSpineLine(kernelQuery);
   return {
-    text: skill.body,
+    text: `${skill.body}${spineLines.length > 0 ? `
+${spineLines.join("\n")}` : ""}${sampleTruncated ? `
+${READINESS_PROVISIONAL_LINE} Reuse existing knowledge when following setup.` : ""}`,
     structuredContent: success(
       `pb-setup ready. Delivering SKILL-pb-setup body (${skill.body.length} chars).`,
       {
@@ -9112,9 +9138,11 @@ async function buildSetupResponse(agentSessionId) {
         skillEntryId: skill.entryId,
         skillBody: skill.body,
         stage: "setup",
+        sampleTruncated,
         oriented,
         orientationStatus,
         ...agentSessionId ? { sessionId: agentSessionId } : {},
+        ...spineLines[0] !== void 0 ? { spineLine: spineLines[0] } : {},
         instructions: "Read skillBody and follow it; use entries/orient MCP tools per PAT-227."
       }
     )
@@ -9149,8 +9177,9 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors, task) {
     errors.push(`Readiness: ${e instanceof Error ? e.message : String(e)}`);
   }
   const lines = [];
-  const isLowReadiness = readiness !== null && readiness.score < 50;
-  const isHighReadiness = readiness !== null && readiness.score >= 50;
+  const isLowReadiness = readiness !== null && !readiness.sampleTruncated && readiness.score < 50;
+  if (readiness?.sampleTruncated) lines.push(READINESS_PROVISIONAL_LINE, "");
+  const showExistingContext = readiness !== null && (readiness.sampleTruncated || readiness.score >= 50);
   const stage = readiness?.stage ?? null;
   const captureBehaviorNote = wsCtx.governanceMode === "open" ? "_In Open mode, user-authored captures are accepted immediately unless you ask me to keep them as drafts._" : "_Everything I capture stays pending until you confirm._";
   const coherence = await buildCoherenceSection();
@@ -9208,9 +9237,9 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors, task) {
         lines.push("");
       }
     }
-    lines.push("_Need a collection that doesn't exist yet? Just ask \u2014 I'll set it up._");
+    lines.push("_Need a collection that doesn't exist yet? Creating one is not available through this tool. Ask a platform admin to provision it, or enable the module ontology pack that owns it._");
     lines.push("");
-  } else if (isHighReadiness) {
+  } else if (showExistingContext) {
     let activeBets = [];
     try {
       const betsEntries = await kernelQuery("chain.listEntries", { collectionSlug: "work-packages" });
@@ -9276,7 +9305,7 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors, task) {
         const committedCollections = new Set(committed.map((e) => e.collectionId));
         if (committed.length >= 10 && committedCollections.size >= 3) {
           lines.push("");
-          lines.push(`_${committed.length} entries across ${committedCollections.size} collections on the Chain._`);
+          lines.push(`_Context sample: ${committed.length} accepted/active entries across ${committedCollections.size} collections._`);
         }
       } catch {
       }
@@ -9328,13 +9357,13 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors, task) {
     lines.push("");
   }
   const { oriented, orientationStatus } = await tryMarkOriented(agentSessionId, coherence?.snapshot ?? void 0);
-  const stageLabel = stage ?? "active";
+  const stageLabel = `${stage ?? "active"}${readiness?.sampleTruncated ? " (provisional sample)" : ""}`;
   const gapCount = readiness?.gaps?.length ?? 0;
   const summaryParts = [`Product Brain ready. Stage: ${stageLabel}.`];
-  if (gapCount > 0) summaryParts.push(`${gapCount} gap${gapCount === 1 ? "" : "s"}.`);
+  if (gapCount > 0) summaryParts.push(`${gapCount} ${readiness?.sampleTruncated ? "potential " : ""}gap${gapCount === 1 ? "" : "s"}${readiness?.sampleTruncated ? " in sampled entries; absence unverified" : ""}.`);
   if (openTensions.length > 0) summaryParts.push(`${openTensions.length} open tension${openTensions.length === 1 ? "" : "s"}.`);
   const next = [];
-  if (gapCount > 0) {
+  if (gapCount > 0 && !readiness?.sampleTruncated) {
     next.push({ tool: "capture", description: "Fill a gap", parameters: {} });
   }
   if (openTensions.length > 0) {
@@ -9346,6 +9375,7 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors, task) {
       summaryParts.join(" "),
       {
         stage,
+        sampleTruncated: readiness?.sampleTruncated ?? null,
         readinessScore: readiness?.score ?? null,
         totalGaps: gapCount,
         openTensions: openTensions.length,
@@ -9381,14 +9411,16 @@ async function handleStartPb({ task }) {
     };
   }
   let stage = null;
+  let sampleTruncated = false;
   try {
     const readiness = await kernelQuery("chain.workspaceReadiness");
     stage = readiness?.stage ?? "blank";
+    sampleTruncated = readiness?.sampleTruncated === true;
   } catch {
     errors.push("Readiness check unavailable \u2014 showing workspace summary.");
   }
   if (stage === "blank" || stage === "seeded") {
-    const result2 = await buildSetupResponse(agentSessionId);
+    const result2 = await buildSetupResponse(agentSessionId, sampleTruncated);
     return {
       content: textContent(`${result2.text}
 
@@ -9396,7 +9428,7 @@ ${FEEDBACK_SUBMIT_HINT}`),
       structuredContent: result2.structuredContent
     };
   }
-  if (stage === "grounded" || stage === "connected") {
+  if (!sampleTruncated && (stage === "grounded" || stage === "connected")) {
     void kernelMutation("chain.setOnboardingCompleted", {}).catch(() => {
     });
   }
@@ -9701,16 +9733,17 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
   } catch (e) {
     errors.push(`Readiness: ${e instanceof Error ? e.message : String(e)}`);
   }
-  if (readiness?.stage === "blank") {
+  const sampleTruncated = readiness?.sampleTruncated === true || orientView?.sampleTruncated === true;
+  if (readiness?.stage === "blank" && !sampleTruncated) {
     const scanLines = [
       `# Welcome to ${wsCtx?.workspaceName ?? "your workspace"}`,
       "",
-      "Your workspace is fresh \u2014 let's set it up.",
+      "No accepted user-authored entries were found; drafts may already exist.",
       "",
-      "**Recommended:** call the `start` tool instead of `orient` for the best first-run experience.",
-      "It will guide you through setting up your workspace \u2014 you can tell me about your product, scan your codebase, or use a preset.",
+      "For your current task, follow the spine guidance below: discover and reuse existing knowledge before creating anything.",
+      "Capture only what the task needs, inspect its returned status, and read it back. Accept it only if it remains a draft; already accepted or committed entries need no extra acceptance.",
       "",
-      "Or tell me about your product and I'll start capturing knowledge directly."
+      "Full onboarding is optional: call `orient action=start` if you want guided workspace setup. If you already ran setup, continue your task without restarting it."
     ];
     scanLines.push(...buildRitualsSurfaceLines(orientView, { fetchFailed: orientFetchFailed || orientView?.fetchFailed === true }));
     let oriented = false;
@@ -9728,16 +9761,17 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
     const blankResult = {
       content: [{ type: "text", text: scanLines.join("\n") }],
       structuredContent: success(
-        "Workspace is blank. Use `orient action=start` for guided setup.",
-        { stage: "blank", readinessScore: readiness?.score ?? 0, oriented, orientationStatus: orientationStatus2, redirectHint: "Use `orient action=start` for the full guided setup experience." },
-        [{ tool: "orient", description: "Guided workspace setup", parameters: { action: "start" } }]
+        "No accepted user-authored entries found. Follow the spine guidance for your task; full onboarding is optional.",
+        { stage: "blank", readinessScore: readiness?.score ?? 0, oriented, orientationStatus: orientationStatus2, redirectHint: "Optional full onboarding: `orient action=start`. Continue an existing task using the spine guidance." },
+        task ? [] : [{ tool: "orient", description: "Optional full workspace onboarding", parameters: { action: "start" } }]
       )
     };
     reportOrientWrapperBytes(blankResult, false, resolvedTier, taskMeaningful);
     return blankResult;
   }
-  const lines = [];
-  const isLowReadiness = readiness && readiness.score < 50;
+  const lines = sampleTruncated ? [READINESS_PROVISIONAL_LINE, ""] : [];
+  const isLowReadiness = !sampleTruncated && readiness && readiness.score < 50;
+  const stageQualifier = sampleTruncated ? " (provisional sample)" : "";
   if (wsCtx) {
     lines.push(`# ${wsCtx.workspaceName}`);
     lines.push(`_Workspace \`${wsCtx.workspaceSlug}\` \u2014 Product Brain is healthy._`);
@@ -9757,7 +9791,7 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
   }
   if (mode === "brief") {
     const briefStage = readiness?.stage ?? (readiness?.score != null ? readiness.score < 50 ? "seeded" : "grounded" : "unknown");
-    lines.push(`Brain stage: ${briefStage}`);
+    lines.push(`Brain stage: ${briefStage}${stageQualifier}`);
     lines.push(...buildDirectionLines(orientView));
     if (orientView?.strategicContext) {
       const sc = orientView.strategicContext;
@@ -9821,12 +9855,12 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
       lines.push("");
       lines.push(...briefWna);
     }
-    const briefGaps = readiness?.gaps ?? [];
+    const briefGaps = sampleTruncated ? [] : readiness?.gaps ?? [];
     if (briefGaps.length > 0) {
       const oneLiner = formatGapOneLiner(briefGaps[0]);
       if (oneLiner) lines.push(oneLiner);
     }
-    const briefClassificationGaps = briefGaps.filter((g) => g.id?.startsWith?.(PURPOSE_GAP_PREFIX));
+    const briefClassificationGaps = (readiness?.gaps ?? []).filter((g) => g.id?.startsWith?.(PURPOSE_GAP_PREFIX));
     if (briefClassificationGaps.length > 0) {
       lines.push(`${briefClassificationGaps.length} collection(s) with weak purpose \u2014 classification may be inaccurate.`);
     }
@@ -9912,10 +9946,11 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
     const briefResult = {
       content: [{ type: "text", text: lines.join("\n") }],
       structuredContent: success(
-        `Oriented (brief). Stage: ${readiness?.stage ?? "unknown"}.`,
+        `Oriented (brief). Stage: ${readiness?.stage ?? "unknown"}${stageQualifier}.`,
         {
           mode: "brief",
           stage: readiness?.stage ?? "unknown",
+          sampleTruncated,
           oriented: hasTaskGrounding ? isSessionOriented() : false,
           sessionId: agentSessionId,
           taskGroundingStatus: hasTaskGrounding ? "task_scoped" : task ? "missing_task_context" : "workspace_only",
@@ -9955,7 +9990,7 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
   if (isLowReadiness && wsCtx?.createdAt) {
     const ageDays = Math.floor((Date.now() - wsCtx.createdAt) / (1e3 * 60 * 60 * 24));
     if (ageDays >= 30) {
-      lines.push(`Your workspace has been around for ${ageDays} days and is still at the **${orientStage}** stage.`);
+      lines.push(`Your workspace has been around for ${ageDays} days and is still at the **${orientStage}${stageQualifier}** stage.`);
       lines.push("Let's close the gaps \u2014 or if the current structure doesn't fit, we can reshape it.");
       lines.push("");
     }
@@ -9986,7 +10021,7 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
         lines.push("");
       }
     }
-    lines.push("_Need a collection that doesn't exist yet? Just ask \u2014 I'll set it up._");
+    lines.push("_Need a collection that doesn't exist yet? Creating one is not available through this tool. Ask a platform admin to provision it, or enable the module ontology pack that owns it._");
     lines.push("");
   } else if (readiness) {
     const fmt = (e) => {
@@ -10006,7 +10041,7 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
       fullCoherenceSnapshot = fullCoherence.snapshot ?? void 0;
     }
     if (task) {
-      lines.push(`**Brain stage: ${orientStage}.** Working on: **${task}**`);
+      lines.push(`**Brain stage: ${orientStage}${stageQualifier}.** Working on: **${task}**`);
       lines.push("");
       lines.push(...buildDirectionLines(orientView));
       if (orientView?.strategicContext) {
@@ -10233,7 +10268,7 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
         lines.push(...formatRecoveryBlock(recoveryBlock));
       }
     } else {
-      lines.push(`**Brain stage: ${orientStage}.**`);
+      lines.push(`**Brain stage: ${orientStage}${stageQualifier}.**`);
       lines.push("");
       const scNoTaskLines = buildDirectionLines(orientView);
       if (scNoTaskLines.length > 0) lines.push(...scNoTaskLines, "");
@@ -10349,10 +10384,11 @@ async function _handleOrient({ mode = "full", tier, task, scope, startupSignals,
   const fullResult = {
     content: [{ type: "text", text: lines.join("\n") }],
     structuredContent: success(
-      `Oriented (full). Stage: ${orientStage}. ${isLowReadiness ? "Low readiness \u2014 gaps remain." : "Ready."}`,
+      `Oriented (full). Stage: ${orientStage}${stageQualifier}. ${sampleTruncated ? "Provisional readiness sample." : isLowReadiness ? "Low readiness \u2014 gaps remain." : "Ready."}`,
       {
         mode: "full",
         stage: orientStage,
+        sampleTruncated,
         oriented: hasTaskGrounding ? isSessionOriented() : false,
         sessionId: agentSessionId,
         taskGroundingStatus: hasTaskGrounding ? "task_scoped" : task ? "missing_task_context" : "workspace_only",
@@ -12194,6 +12230,51 @@ async function handleAuditRun(entryId, phase) {
   };
 }
 
+// src/lib/spineVerdictRead.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isStructural(value) {
+  if (!isRecord(value) || typeof value.passed !== "boolean" || !isStringArray(value.missing) || !isRecord(value.duplicateSingletons) || !isStringArray(value.unconnectedStrategyIds) || value.visionConnectedToPurpose !== null && typeof value.visionConnectedToPurpose !== "boolean") return false;
+  for (const key of ["purpose", "vision"]) {
+    const ids = value.duplicateSingletons[key];
+    if (ids !== null && !isStringArray(ids)) return false;
+  }
+  for (const key of [
+    "strategiesWithUnknownConnectivity",
+    "unconnectedObjectiveIds",
+    "objectivesWithUnknownConnectivity",
+    "unconnectedKeyResultIds",
+    "keyResultsWithUnknownConnectivity"
+  ]) {
+    if (value[key] != null && !isStringArray(value[key])) return false;
+  }
+  return value.visionPurposeConnectivityTruncated === void 0 || typeof value.visionPurposeConnectivityTruncated === "boolean";
+}
+function isStrategy(value) {
+  if (!isRecord(value) || typeof value.entryId !== "string" || !isRecord(value.refusal) || typeof value.refusal.hasRefusalSignal !== "boolean") return false;
+  return value.rogerMartin === null || isRecord(value.rogerMartin) && typeof value.rogerMartin.isStrategicChoice === "boolean" && typeof value.rogerMartin.reasoning === "string";
+}
+function isStory(value) {
+  return value === null || isRecord(value) && typeof value.passed === "boolean" && (value.failedCriterion === null || typeof value.failedCriterion === "string") && Array.isArray(value.criteria) && value.criteria.every((item) => isRecord(item) && typeof item.id === "string" && typeof item.passed === "boolean" && typeof item.reasoning === "string");
+}
+function readSpineVerdict(value) {
+  if (!isRecord(value) || typeof value.noSpineEntries !== "boolean") return { kind: "malformed" };
+  if (value.noSpineEntries) return { kind: "empty" };
+  if (!isStructural(value.structural) || !Array.isArray(value.perStrategy) || !value.perStrategy.every(isStrategy) || !isStory(value.story)) return { kind: "malformed" };
+  for (const key of ["strategiesTruncated", "perStrategyEvaluationTruncated", "objectivesTruncated", "keyResultsTruncated"]) {
+    if (value[key] !== void 0 && typeof value[key] !== "boolean") return { kind: "malformed" };
+  }
+  return { kind: "graded", verdict: value };
+}
+function describeSpineStaleness(changedMemberCount, membershipTruncated = false) {
+  const reason = changedMemberCount > 0 ? `${membershipTruncated ? "at least " : ""}${changedMemberCount} entr${changedMemberCount === 1 ? "y" : "ies"} changed or joined/left the spine since this was computed` : "freshness could not be verified; the changed-entry count is unknown";
+  return reason + (membershipTruncated ? "; membership scan incomplete" : "");
+}
+
 // src/tools/spine-check.ts
 async function handleSpineCheck(story, refresh = false) {
   const scheduleResult = await kernelMutation(
@@ -12203,26 +12284,59 @@ async function handleSpineCheck(story, refresh = false) {
   const row = await kernelQuery("quality.getLatestSpineVerdict", {});
   const stillRunning = scheduleResult.scheduled;
   if (!row) {
-    const text = stillRunning ? "Spine check started \u2014 no prior result exists yet. It runs asynchronously (LLM calls can take 25s+ each); re-run this in a few seconds to read the result." : "No spine check has been run yet, and none is currently running. Pass refresh:true to start one.";
+    const text = stillRunning ? "Spine check started \u2014 no prior result exists yet. It runs asynchronously (LLM calls can take 25s+ each); re-run this in a few seconds to read the result." : scheduleResult.reason === "already-in-flight" ? "A spine check is already running \u2014 no prior result exists yet. Re-run quality action=spine-check in a few seconds to read its result." : "No spine check has been run yet, and none is currently running. Pass refresh:true to start one.";
     return {
       content: [{ type: "text", text }],
-      structuredContent: success(text, { hasVerdict: false, checkStarted: stillRunning })
+      structuredContent: success(text, {
+        hasVerdict: false,
+        checkStarted: stillRunning,
+        stillRunning: stillRunning || scheduleResult.reason === "already-in-flight"
+      })
     };
   }
-  const { verdict } = row;
-  if (verdict.noSpineEntries) {
+  const parsed = readSpineVerdict(row.verdict);
+  const freshnessData = { stale: row.stale, staleMemberIds: row.staleMemberIds, membershipTruncated: row.membershipTruncated ?? false };
+  const staleReason = describeSpineStaleness(row.staleMemberIds.length, row.membershipTruncated);
+  if (parsed.kind === "empty") {
+    const pending = stillRunning || scheduleResult.reason === "already-in-flight";
+    const freshness = (row.stale ? ` Stale: ${staleReason}.` : "") + (pending ? " A check is running; re-run quality action=spine-check in a few seconds to read its result." : row.stale ? " Run quality action=spine-check refresh=true to refresh it." : "");
+    const text = `The last spine check found no accepted purpose, vision or strategy.${freshness}`;
     return {
-      content: [{ type: "text", text: "No spine entries yet \u2014 nothing to check." }],
-      structuredContent: success("No spine entries yet.", { hasVerdict: true, noSpineEntries: true })
+      content: [{ type: "text", text }],
+      structuredContent: success(text, {
+        hasVerdict: true,
+        noSpineEntries: true,
+        ...freshnessData,
+        stillRunning: pending,
+        scheduled: scheduleResult.scheduled,
+        scheduleReason: scheduleResult.reason
+      })
     };
   }
+  if (parsed.kind === "malformed") {
+    const pending = stillRunning || scheduleResult.reason === "already-in-flight";
+    const text = `Stored spine verdict is malformed \u2014 ${pending ? "a check is running; re-run quality action=spine-check in a few seconds to read its result." : "run quality action=spine-check refresh=true to replace it."}`;
+    return {
+      content: [{ type: "text", text }],
+      structuredContent: success(text, {
+        hasVerdict: true,
+        malformed: true,
+        ...freshnessData,
+        scheduled: scheduleResult.scheduled,
+        stillRunning: pending,
+        scheduleReason: scheduleResult.reason
+      })
+    };
+  }
+  const { verdict } = parsed;
   const lines = ["## Spine Check"];
   if (stillRunning) {
     lines.push(`> A new check was just triggered and is still running asynchronously \u2014 the result below is from the PREVIOUS run (${new Date(row.createdAt).toISOString()}). Re-run in a few seconds for the fresh result.`, "");
   } else if (scheduleResult.reason === "already-in-flight") {
     lines.push(`> A check is already running (started earlier, not by this call) \u2014 showing the best available result (${new Date(row.createdAt).toISOString()}). Re-run in a few seconds.`, "");
-  } else if (row.stale) {
-    lines.push(`> STALE \u2014 ${row.staleMemberIds.length} member entry(ies) changed since this was computed. Pass refresh:true to recompute.`, "");
+  }
+  if (row.stale) {
+    lines.push(`> STALE \u2014 ${staleReason}.${stillRunning || scheduleResult.reason === "already-in-flight" ? "" : " Pass refresh:true to recompute."}`, "");
   }
   const s = verdict.structural;
   lines.push(`Structural completeness: ${s.passed ? "PASS" : "FAIL"}`);
@@ -12249,7 +12363,7 @@ async function handleSpineCheck(story, refresh = false) {
     lines.push("", `One-story judgment [unvalidated, on-demand]: ${verdict.story.passed ? "PASS" : "FAIL"}`);
     if (!verdict.story.passed && verdict.story.failedCriterion) lines.push(`Failed criterion: ${verdict.story.failedCriterion}`);
   } else if (row.includesStoryPass) {
-    lines.push("", "One-story judgment: requested, but the LLM pass did not return a usable result (timeout or parse failure). Pass refresh:true to retry \u2014 a plain re-run will not reschedule it.");
+    lines.push("", "One-story judgment: requested, but the LLM pass did not return a usable result (timeout or parse failure). Run quality action=spine-check story=true refresh=true to retry \u2014 a plain re-run will not reschedule it.");
   } else {
     lines.push("", "One-story judgment: not run this pass \u2014 pass story=true to run it.");
   }
@@ -12262,7 +12376,7 @@ async function handleSpineCheck(story, refresh = false) {
         noSpineEntries: false,
         structuralPassed: s.passed,
         storyPassed: verdict.story?.passed ?? null,
-        stale: row.stale,
+        ...freshnessData,
         stillRunning,
         scheduled: scheduleResult.scheduled,
         scheduleReason: scheduleResult.reason
@@ -12351,7 +12465,12 @@ var qualitySpineCheckOutputSchema = z24.object({
   noSpineEntries: z24.boolean().optional(),
   structuralPassed: z24.boolean().optional(),
   storyPassed: z24.boolean().nullable().optional(),
-  stale: z24.boolean().optional()
+  stale: z24.boolean().optional(),
+  // TASK-156: a capped membership scan must stay distinguishable from a complete one, and a
+  // malformed verdict needs its own discriminator — both were silently stripped before this.
+  staleMemberIds: z24.array(z24.string()).optional(),
+  membershipTruncated: z24.boolean().optional(),
+  malformed: z24.boolean().optional()
 });
 function registerQualityTools(server) {
   const qualityHandlers = {
@@ -14629,8 +14748,8 @@ async function handleWorkspaceStatus() {
   const { score, totalChecks, passedChecks, checks, gaps, stats, governanceMode } = result2;
   const scoringVersion = result2.scoringVersion ?? "v1";
   const stage = result2.stage ?? "seeded";
-  const stageLabel = STAGE_LABELS[stage] ?? stage;
-  const stageDescription = STAGE_DESCRIPTIONS[stage] ?? "";
+  const stageLabel = `${STAGE_LABELS[stage] ?? stage}${result2.sampleTruncated ? " (provisional sample)" : ""}`;
+  const stageDescription = result2.sampleTruncated ? READINESS_PROVISIONAL_LINE : STAGE_DESCRIPTIONS[stage] ?? "";
   const scoreBar = "\u2588".repeat(Math.round(score / 10)) + "\u2591".repeat(10 - Math.round(score / 10));
   const lines = [
     `# Brain Status: ${stageLabel}`,
@@ -14639,14 +14758,14 @@ async function handleWorkspaceStatus() {
     `${scoreBar} ${stageLabel} \xB7 ${score}%`,
     `**Governance:** ${governanceMode ?? "open"}${(governanceMode ?? "open") !== "open" ? " (accepts require proposal)" : ""}`,
     "",
-    "## Stats",
-    `- **Entries:** ${stats.totalEntries} (${stats.activeCount} active, ${stats.draftCount} draft)`,
+    "## Sampled counts",
+    `- **Entries:** ${stats.totalEntries} (${stats.activeCount} accepted/active, ${stats.draftCount} draft)`,
     `- **Relations:** ${stats.totalRelations}`,
     `- **Collections:** ${stats.collectionCount}`,
     `- **Orphaned:** ${stats.orphanedCount} committed entries with no relations`,
     ""
   ];
-  if (gaps.length > 0) {
+  if (gaps.length > 0 && !result2.sampleTruncated) {
     lines.push("## Gaps");
     for (const gap of gaps) {
       const action = gap.capabilityGuidance ?? gap.guidance;
@@ -14657,7 +14776,7 @@ async function handleWorkspaceStatus() {
   }
   const passed = checks.filter((c) => c.passed);
   if (passed.length > 0) {
-    lines.push("## Passing checks");
+    lines.push(result2.sampleTruncated ? "## Checks observed in the provisional sample" : "## Passing checks");
     for (const check of passed) {
       lines.push(`- [x] ${check.label} (${check.current}/${check.required})`);
     }
@@ -14671,6 +14790,7 @@ async function handleWorkspaceStatus() {
   }
   const statusData = {
     stage,
+    sampleTruncated: result2.sampleTruncated ?? null,
     scoringVersion,
     readinessScore: score,
     activeEntries: stats.activeCount,
@@ -14679,14 +14799,14 @@ async function handleWorkspaceStatus() {
     gaps: gaps.map((g) => ({
       id: g.id,
       label: g.label,
-      guidance: g.capabilityGuidance ?? g.guidance
+      guidance: result2.sampleTruncated ? "Unverified gap in sampled entries. Review existing knowledge before adding more." : g.capabilityGuidance ?? g.guidance
     })),
     ...orgHealth && { organisationHealth: orgHealth }
   };
   return {
     content: [{ type: "text", text: lines.join("\n") }],
     structuredContent: success(
-      `Brain: ${stageLabel} (${score}%). ${stats.activeCount} active entries, ${gaps.length} gap(s).`,
+      `Brain: ${stageLabel} (${score}%). ${stats.activeCount} accepted/active entries in the sample, ${gaps.length} ${result2.sampleTruncated ? "potential gap(s); absence unverified" : "gap(s)"}.`,
       statusData
     )
   };
@@ -14747,6 +14867,7 @@ var organisationHealthSchema = z29.object({
 });
 var healthStatusOutputSchema = z29.object({
   stage: z29.enum(["blank", "seeded", "grounded", "connected"]).optional().default("seeded"),
+  sampleTruncated: z29.boolean().nullable().optional(),
   scoringVersion: z29.enum(["v1", "v2"]).optional().default("v1"),
   readinessScore: z29.number(),
   activeEntries: z29.number(),
@@ -16941,4 +17062,4 @@ export {
   createProductBrainServer,
   initFeatureFlags
 };
-//# sourceMappingURL=chunk-PTC2REQA.js.map
+//# sourceMappingURL=chunk-7T4HSTNG.js.map