@cyber-dash-tech/revela 0.17.0 → 0.17.2

package/designs/summit/DESIGN.md

@@ -470,7 +470,7 @@ These rules are mandatory for Summit.
 
 ### Layout Types
 
-Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the 1-based `DECKS.json` `slides[].index` value. Use the QA column to decide which value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
+Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the canonical positive 1-based artifact slide identity from the approved deck plan or DOM order. Indexes must be unique and strictly increase. Use the QA column to decide which `slide-qa` value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
 
 Normal `qa=true` content layouts should start with a slide-level title block unless the layout marker explicitly says otherwise. Use an eyebrow for chapter/section context, then an `h2` that states the slide's claim or takeaway. Body boxes, charts, media, tables, and text panels should sit below or beside that title region rather than replacing it.
 

package/lib/commands/help.ts

@@ -29,8 +29,8 @@ export async function handleHelp(
     `**Workflow**\n\n` +
     `1. \`init\` — discover workspace sources and capture intent\n` +
     `2. \`research\` — close evidence gaps and bind support\n` +
-    `3. \`story\` — inspect audience, thesis, claims, evidence, risks, and approval\n` +
-    `4. \`make\` — generate deck or brief from approved story state\n` +
+    `3. \`story\` — inspect audience, thesis, claims, evidence, risks, and diagnostics\n` +
+    `4. \`make\` — generate deck or brief from canonical story state\n` +
     `5. \`review\` — comment on and inspect rendered deck artifacts\n` +
     `6. \`export\` — export deck artifacts to PDF or PPTX\n\n` +
     `---\n\n` +
@@ -41,8 +41,8 @@ export async function handleHelp(
     `\`/revela init\`                                 — initialize or refresh workspace story state\n` +
     `\`/revela research\`                             — research, bind evidence, and reduce story gaps\n` +
     `\`/revela story [-l language]\`                   — open the read-only story workspace UI\n` +
-    `\`/revela make --deck\`                          — make a deck from approved story state\n` +
-    `\`/revela make --brief [file.md]\`                — render executive brief from approved story\n` +
+    `\`/revela make --deck\`                          — make a deck from story state and deck-plan/\n` +
+    `\`/revela make --brief [file.md]\`                — render executive brief from story state\n` +
     `\`/revela review --deck\`                        — open deck reading, insight, and comment workspace\n` +
     `\`/revela export --deck pdf [file.html]\`         — export HTML deck to PDF\n` +
     `\`/revela export --deck pptx [file.html] [--notes]\` — export HTML deck to PPTX\n` +

package/lib/commands/init.ts

@@ -8,16 +8,17 @@ export function buildInitPrompt({
   workspaceRoot?: string
 }): string {
   const mode = exists
-    ? `A ${DECKS_STATE_FILE} file already exists. Read it first through the revela-decks tool and update it conservatively.`
-    : `No ${DECKS_STATE_FILE} file exists yet. Initialize the Markdown narrative vault through the revela-decks tool before writing narrative meaning.`
+    ? `A ${DECKS_STATE_FILE} file already exists as legacy/cache state. Read it first through the revela-decks tool and update it conservatively only for compatibility metadata.`
+    : `No ${DECKS_STATE_FILE} file exists yet. Keep this workspace file-native: initialize the Markdown narrative vault before writing narrative meaning and do not create ${DECKS_STATE_FILE}.`
 
   return `Initialize Revela narrative workspace state.
 
 Goal:
-- Build or refresh ${DECKS_STATE_FILE} and the Markdown narrative vault from local workspace evidence.
+- Initialize or refresh the Markdown narrative vault and file-native source inventory from local workspace evidence.
 - Treat init as repeatable ingest: discover files, register source materials, follow returned ingest task hints, and distill stable narrative meaning.
 - Capture primary audience, belief before/after, decision/action, thesis, central claims, evidence availability, objections, risks, source materials, artifact history, and open questions.
 - Do not treat initialization as permission to write a deck. Do not require slide count, visual style, design selection, output path, layout choices, or component choices unless the user explicitly asks to render.
+- Treat central claims as chapter-ready claims, not evidence fragments: a central claim should be able to support framing/context, proof/evidence, decision implication, and explicit boundary/gap/risk material. If local material only supports a narrow fact, record it as supporting evidence or a supporting claim instead of promoting it to central importance.
 
 Current state:
 - ${mode}
@@ -32,7 +33,7 @@ Workspace boundary rules:
 - If the current workspace appears too broad, stop and ask the user which workspace subdirectory to initialize instead of scanning outside or deeply across everything.
 
 Expected tool use during init:
-- \`revela-decks init\` and \`revela-decks initNarrativeVault\` are expected controlled workspace-state/vault boundaries. Empty-looking optional fields in tool UI are a schema display artifact, not user-provided evidence.
+- \`revela-decks init\` and \`revela-decks initNarrativeVault\` are expected controlled file-native/vault boundaries. In fresh workspaces they must not create ${DECKS_STATE_FILE}; if legacy state already exists, they may update compatibility metadata conservatively. Empty-looking optional fields in tool UI are a schema display artifact, not user-provided evidence.
 - Treat \`authoringContract\` returned by \`read(summary: true)\`, \`initNarrativeVault\`, or \`narrativeInventory\` as the Markdown authoring guide: valid node types, plain id convention, inline relation syntax, forbidden compatibility actions, and optional helper templates.
 - Treat \`markdownQa\` returned by \`read(summary: true)\`, \`compileNarrativeVault\`, or \`revela-decks markdownQa\` as post-authoring repair feedback that is separate from compiler diagnostics. Fix \`repairCards\` by smallest repair; do not invent missing claims, evidence, source paths, URLs, quotes, or caveats just to clear QA. If \`compileNarrativeVault\` output does not visibly include \`markdownQa\`, call \`revela-decks markdownQa\` before final reporting.
 - Before authoring claims, evidence, relations, objections, risks, or research gaps, inspect \`narrativeInventory\` from \`read(summary: true)\` or call \`revela-decks narrativeInventory\`. Reuse existing ids and relation targets. Do not invent evidence ids, claim ids, or relation targets before checking inventory unless you are intentionally creating the missing node in Markdown.
@@ -58,7 +59,7 @@ Required workflow:
 5. For selected relevant tasks, read directly when \`suggestedAction: "read_directly"\`; call \`revela-extract-document-materials\` first when \`suggestedAction: "extract_then_read"\`. Do not extract every document by default.
 6. Before writing narrative meaning, inspect \`narrativeInventory\` from the latest \`read(summary: true)\` result or call \`revela-decks narrativeInventory\`. Then distill stable findings into \`revela-narrative/**/*.md\` using the Markdown authoring guide. Completeness is not a gate: write partial claims, caveats, unsupported scope, and research gaps rather than waiting for a complete story. Use optional helpers such as \`upsertVaultResearchGap\`, \`upsertVaultEvidence\`, or \`bindResearchFindings\` only when they fit the exact update. Preserve frontmatter ids and existing section headings when editing Markdown. Write nodes first; add inline \`## Relations\` edges afterward only when explicit.
 7. After Markdown changes, rely on the vault write hook or call \`revela-decks markdownQa\`, then \`revela-decks compileNarrativeVault\`; keep \`markdownQa.repairCards\` separate from compiler blockers and fix both before treating the narrative as usable. If no explicit \`markdownQa\` result is visible after compile, call \`revela-decks markdownQa\` as a manual fallback. Do not use \`upsertNarrative\`.
-8. If explicit deck/artifact information exists, record conservative deck specs only from visible information. Do not infer hidden evidence from generated artifacts.
+8. If explicit deck/artifact information exists, record conservative artifact context in file-native outputs or existing compatibility state only from visible information. Do not infer hidden evidence from generated artifacts.
 9. Report initialized/updated/migrated state plus counts and paths for added, changed, newer-than-vault, unchanged, \`ingest.ingestCandidates\`, and \`ingest.suggestedTasks\`. Always include \`Markdown QA: clean\` or \`Markdown QA blockers:\` in the final report. If Markdown QA blockers remain, do not say the workspace initialized cleanly; say the vault was initialized but Markdown repairs remain.
 
 Evidence boundary:
@@ -67,6 +68,7 @@ Evidence boundary:
 - Preserve graph meaning by writing explicit edges in node-local \`## Relations\` sections after nodes exist. Use plain node-id wikilinks and optional inline rationale.
 - Intent briefs, proposals, and user-authored plans may support audience, decision, thesis, stakeholder framing, and stated internal intent. They do not by themselves prove market size, competitor performance, product-market fit, operating-model effectiveness, or external factual claims.
 - If a source states an intended strategy but not its external factual basis, record the strategy as a claim with partial or missing support and add a research gap instead of binding it as strong evidence.
+- If a central claim cannot yet sustain a future claim-led chapter, keep the insufficiency visible through evidence status, unsupported scope, caveats, or a research gap rather than padding the future deck with generic slides.
 - A successful vault compile means the vault is structurally valid. It is not evidence readiness, narrative approval, or permission to make a deck/brief.
 
 Narrative questions to ask only when missing:
@@ -80,11 +82,11 @@ Narrative questions to ask only when missing:
 - What objections, risks, assumptions, or caveats could break the argument?
 
 Memory rules:
-- Only write facts supported by workspace files or explicit user statements into ${DECKS_STATE_FILE} workspace state, source materials, narrative compatibility fields, deck memory, and open questions.
+- Only write facts supported by workspace files or explicit user statements into file-native narrative/source files or, when ${DECKS_STATE_FILE} already exists, conservative compatibility metadata such as source materials, deck memory, and open questions.
 - Only write user preferences if the user explicitly stated that Revela should remember them.
 - Do not infer personal preferences from one-off requests.
 - Do not store secrets, credentials, API keys, tokens, account details, or sensitive personal information.
-- Do not mark narrative approval, render override, or writeReadiness as ready during init.
+- Do not create or update approval, render override, or writeReadiness workflow state during init.
 - Treat this workspace as a single deck project. If the user wants another deck, guide them to create another workspace/folder rather than adding a second deck record.
 - If new evidence conflicts with existing memory, preserve both briefly and add an Open Question instead of silently overwriting.
 

package/lib/commands/narrative.ts

@@ -147,7 +147,7 @@ export function buildNarrativeViewPrompt(options: { workspaceRoot: string; langu
     relations: map.claimRelations.map((relation) => ({ id: relation.id, fromClaimId: relation.fromClaimId, toClaimId: relation.toClaimId, relation: relation.relation, rationale: relation.rationale, inferred: relation.inferred })),
     objections: map.objections.map((objection) => ({ id: objection.id, claimId: objection.claimId, priority: objection.priority, text: objection.text, response: objection.response })),
     risks: map.risks.map((risk) => ({ id: risk.id, claimId: risk.claimId, severity: risk.severity, text: risk.text, mitigation: risk.mitigation })),
-    researchGaps: map.researchGaps.map((gap) => ({ id: gap.id, targetType: gap.targetType, targetId: gap.targetId, status: gap.status, priority: gap.priority, question: gap.question })),
+    researchGaps: map.researchGaps.map((gap) => ({ id: gap.id, targetType: gap.targetType, targetId: gap.targetId, status: gap.status, priority: gap.priority, question: gap.question, findingsFile: gap.findingsFile, evidenceBindingIds: gap.evidenceBindingIds, notes: gap.notes })),
     artifactCoverage: map.artifactCoverage.map((artifact) => ({ type: artifact.type, outputPath: artifact.outputPath, stale: artifact.stale, coverageStatus: artifact.coverageStatus, affectedClaimIds: artifact.affectedClaimIds, missingClaimIds: artifact.missingClaimIds, slideRefs: artifact.slideRefs.map((ref) => ({ claimId: ref.claimId, slideIndex: ref.slideIndex, role: ref.role, match: ref.match, location: ref.location })) })),
   }
 
@@ -165,18 +165,27 @@ Hard rules:
 - Do not invent new claims, evidence, relations, slide coverage, source paths, findings files, quotes, or caveats.
 - Preserve every claimId exactly.
 - Preserve every relation endpoint exactly: fromClaimId, toClaimId, relation.
-- You may only organize and localize display copy for the UI: pageTitle, summaryLine, section labels, claim card displayTitle, roleLabel, narrativeJob, evidenceSummary, supportRationale, supportedScope, unsupportedScope, objectionsSummary, risksSummary, riskOrGapSummary, researchGapsSummary, relation displayLabel, and relation displayRationale.
+- You may only organize and localize display copy for the UI: pageTitle, summaryLine, section labels, claim card displayTitle, roleLabel, narrativeJob, evidenceSummary, supportRationale, supportedScope, unsupportedScope, objectionsSummary, risksSummary, riskOrGapSummary, researchGapsSummary, research gap displayQuestion, relation displayLabel, and relation displayRationale.
 - For inferred relations, do not provide relation displayLabel or displayRationale; inferred relations are unconfirmed order notes, not causal/support/dependency judgments.
 - relation displayRationale may only localize or clarify an existing canonical relation rationale. If relation.rationale is missing or the relation is inferred, do not provide displayRationale; the UI will show the missing or inferred status.
 - Keep source paths, findings files, claim IDs, narrative hash, and numbers unchanged.
-- Translate normal UI/display text into the target language request: pageTitle, summaryLine, labels, claim displayTitle, roleLabel, narrativeJob, evidenceSummary, supportRationale, supportedScope, unsupportedScope, objectionsSummary, risksSummary, riskOrGapSummary, researchGapsSummary, relation displayLabel, and relation displayRationale.
+- Translate normal UI/display text into the target language request: pageTitle, summaryLine, labels, claim displayTitle, roleLabel, narrativeJob, evidenceSummary, supportRationale, supportedScope, unsupportedScope, objectionsSummary, risksSummary, riskOrGapSummary, researchGapsSummary, research gap displayQuestion, relation displayLabel, and relation displayRationale.
 - For every claim in a non-English target language, provide displayTitle so the selected-claim panel does not fall back to canonical English claim text.
-- For every selected-claim detail field that has canonical user-facing text, provide the matching localized display field when it exists: supportedScope for supported scope, unsupportedScope for evidence boundaries, supportRationale for why the evidence supports the claim, objectionsSummary for objections, risksSummary for risks, and researchGapsSummary for research gaps.
+- For every evidence/detail field that has canonical user-facing text, provide the matching localized display field when it exists: supportedScope for supported scope, unsupportedScope for evidence boundaries, supportRationale for why the evidence supports the claim, objectionsSummary for objections, risksSummary for risks, and researchGapsSummary for canonical research gaps.
 - Do not translate claim IDs, relation endpoints, narrative hash, source paths, findings files, URLs, numbers, or quoted/source facts.
+- For every canonical research gap in a non-English target language, provide researchGapCards[].displayQuestion so gap cards do not fall back to canonical English question text. Preserve gapId exactly and do not change the gap meaning.
 - Use natural business and manufacturing terminology in the target language, not word-by-word machine translation.
 - If a fact is missing, describe it as missing instead of filling it in.
 - If vaultDiagnostics.blockers is present in the compact map, keep Story read-only but surface the blocker state in summaryLine and the relevant claim card riskOrGapSummary when applicable. Include diagnostic file/nodeId/code/message/suggestedAction in display copy; do not invent missing evidence, source trace, quotes, or caveats to hide the blocker.
 - Do not turn Story into a workflow dashboard: diagnostic copy is for reading context only, not command suggestions or mutation planning.
+- Story UI is evidence-first: clicking a claim shows evidence/gap cards; evidence cards must carry the evidence description, why it supports the claim, and source trace; clicking evidence shows only canonical gaps linked to that evidence.
+- The selected-claim panel is only an evidence/research-gap card list. Do not repeat canonical claim text there; the claim itself is already visible in Claim Flow.
+- Claim cards should not explain gaps or risks through riskOrGapSummary when the same topic belongs in evidence/gap cards. Keep claim cards focused on role, narrative job, and evidence summary.
+- Do not make evidence detail a schema dump. Do not default to unsupportedScope, caveat, IDs, target fields, or evidenceBindingIds for evidence cards; evidence cards should explain what the source says, why it supports the claim, and where it came from.
+- Do not invent, infer, or soften new gaps in display copy. Show research gaps only when they exist in compactMap.researchGaps; do not turn unsupportedScope, weak evidence, caveats, objections, risks, or your own judgment into a gap.
+- researchGapsSummary and riskOrGapSummary may only summarize existing canonical research gaps or diagnostics. If no canonical gap exists for the claim, leave gap-specific display copy empty instead of implying a gap.
+- Localize new Story labels when useful: selectedEvidence, evidenceList, gap, gaps, noEvidence, selectEvidencePrompt, sourceTrace, evidenceSource, whyThisSupports, linkedGaps, selectedGap, and noLinkedGaps.
+- Gap detail may only use canonical research gap fields from the compact map: id, targetType, targetId, status, priority, question, findingsFile, evidenceBindingIds, and notes.
 
 Chinese localization rules when the target language request is Chinese, zh, zh-CN, --cn, 中文, or Simplified Chinese:
 - Use natural business/manufacturing Chinese, not word-by-word machine translation.

package/lib/commands/pdf.ts

@@ -7,12 +7,11 @@
  * Example: decks/my-deck.html → decks/my-deck.pdf
  */
 
+import { existsSync, readdirSync } from "fs"
 import { resolve } from "path"
-import { hasDecksState, readDecksState } from "../decks-state"
 import { exportToPdf } from "../pdf/export"
 import { assertExportQAPassed } from "../qa/export-gate"
 import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
-import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export async function handlePdf(
   filePath: string,
@@ -22,15 +21,15 @@ export async function handlePdf(
   const root = resolve(workspaceRoot)
   const resolvedFile = resolvePdfDeckFile(root, filePath)
 
-  if (!resolvedFile) {
+  if (!resolvedFile.ok) {
     await send(
-      "**Usage:** `/revela export --deck pdf [file_path]`\n\n" +
-      "Example: `/revela export --deck pdf decks/my-deck.html`"
+      `**PDF export cannot start**\n\n${resolvedFile.error}\n\n` +
+      "Usage: `/revela export --deck pdf [file_path]`"
     )
     return
   }
 
-  const abs = resolvedFile.absoluteFile
+  const abs = resolvedFile.deck.absoluteFile
   await send(`Running pre-export QA for \`${abs}\`...`)
 
   try {
@@ -38,7 +37,7 @@ export async function handlePdf(
     await send(`Exporting \`${abs}\` to PDF...`)
     const result = await exportToPdf(abs)
     recordRenderedArtifact(root, {
-      sourceHtmlPath: resolvedFile.file,
+      sourceHtmlPath: resolvedFile.deck.file,
       outputPath: result.outputPath,
       type: "pdf",
       actor: "revela-pdf",
@@ -56,17 +55,27 @@ export async function handlePdf(
   }
 }
 
-function resolvePdfDeckFile(workspaceRoot: string, filePath: string): { file: string; absoluteFile: string } | undefined {
+function resolvePdfDeckFile(workspaceRoot: string, filePath: string): { ok: true; deck: { file: string; absoluteFile: string } } | { ok: false; error: string } {
   const explicit = filePath.trim()
   if (explicit) {
     const absoluteFile = resolve(workspaceRoot, explicit)
-    return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+    if (!existsSync(absoluteFile)) return { ok: false, error: `Deck HTML not found: ${explicit}` }
+    if (!/\.html?$/i.test(absoluteFile)) return { ok: false, error: `File must be an HTML file: ${explicit}` }
+    return { ok: true, deck: { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile } }
   }
 
-  if (!hasDecksState(workspaceRoot)) return undefined
-  const state = readDecksState(workspaceRoot)
-  const activePath = resolveActiveHtmlDeckPath(state)
-  if (!activePath) return undefined
-  const absoluteFile = resolve(workspaceRoot, activePath)
-  return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+  const htmlFiles = listDeckHtmlFiles(workspaceRoot)
+  if (htmlFiles.length === 0) return { ok: false, error: "No deck HTML found in decks/. Pass a file path or generate a deck first." }
+  if (htmlFiles.length > 1) return { ok: false, error: `Multiple deck HTML files found in decks/: ${htmlFiles.join(", ")}. Pass the deck path explicitly.` }
+  const absoluteFile = resolve(workspaceRoot, htmlFiles[0])
+  return { ok: true, deck: { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile } }
+}
+
+function listDeckHtmlFiles(workspaceRoot: string): string[] {
+  const dir = resolve(workspaceRoot, "decks")
+  if (!existsSync(dir)) return []
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".html"))
+    .map((entry) => `decks/${entry.name}`)
+    .sort((a, b) => a.localeCompare(b))
 }

package/lib/commands/pptx.ts

@@ -9,11 +9,9 @@
 
 import { existsSync, readdirSync } from "fs"
 import { relative, resolve, sep } from "path"
-import { hasDecksState, isDeckHtmlPath, readDecksState } from "../decks-state"
 import { assertDeckHtmlContractValid } from "../deck-html/contract"
 import { exportToPptx } from "../pptx/export"
 import { recordRenderedArtifact } from "../workspace-state/rendered-artifacts"
-import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export interface PptxArgs {
   filePath: string
@@ -23,7 +21,7 @@ export interface PptxArgs {
 export interface ResolvedPptxDeck {
   file: string
   absoluteFile: string
-  source: "render-target" | "decks-state" | "fallback" | "file-path"
+  source: "discovered" | "file-path"
 }
 
 function formatSecs(ms: number): string {
@@ -47,18 +45,6 @@ export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedP
     return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "file-path" }
   }
 
-  if (hasDecksState(root)) {
-    const state = readDecksState(root)
-    const outputPath = resolveActiveHtmlDeckPath(state)
-    if (outputPath && isDeckHtmlPath(outputPath)) {
-      const absoluteFile = resolve(root, outputPath)
-      if (existsSync(absoluteFile)) {
-        const source = state.renderTargets.some((target) => target.type === "html_deck" && target.outputPath === outputPath) ? "render-target" : "decks-state"
-        return { file: workspaceRelative(root, absoluteFile), absoluteFile, source }
-      }
-    }
-  }
-
   const htmlFiles = listDeckHtmlFiles(root)
   if (htmlFiles.length === 0) {
     throw new Error("No deck HTML found in decks/. Generate a deck first or pass a file path.")
@@ -68,7 +54,7 @@ export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedP
   }
 
   const absoluteFile = resolve(root, htmlFiles[0])
-  return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "fallback" }
+  return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "discovered" }
 }
 
 export function buildPptxNotesPrompt(deck: ResolvedPptxDeck): string {

package/lib/commands/research.ts

@@ -16,6 +16,7 @@ export function buildResearchPrompt({
 Goal:
 - Reduce open gaps, unsupported scope, weak evidence, unattached findings, and overextended relation rationale for the current story.
 - Drive research from canonical narrative gaps: unsupported central claims, objections, risks, decision questions, explicit researchGaps, and claim_chain_gap warnings.
+- Drive research from central-claim chapter sufficiency, not only missing proof. Each central claim should aim for framing/background support, one or two bound evidence items or cases/quantitative signals, and implication/risk/boundary material before it is treated as deck-ready.
 - Treat /revela research as authorization to bind clearly supported findings through the safe \`bindResearchFindings\` boundary without asking for item-by-item user confirmation.
 - Preserve evidence boundaries: eliminate caveats only when evidence or narrower wording actually resolves them; otherwise keep precise caveats visible.
 - Do not write decks, briefs, or design artifacts during research.
@@ -50,6 +51,7 @@ Allowed mutations:
 
 Binding criteria:
 - supported claim id exists and is expressed as \`## Relations\` with \`- supports: [[claim-id]]\` for new evidence; quote/snippet is traceable and not invented; source URL/path/findingsFile is present; supportScope and unsupportedScope are explicit; caveat is preserved; strength is strong or useful partial; binding does not expand the claim. Frontmatter \`claimId\` is compatibility fallback, not the preferred graph source.
+- For central claims, prefer evidence that helps one of the future chapter jobs: framing/background, proof/case/quantitative signal, or implication/risk/boundary. If research only finds a weak context fact, bind or record it narrowly and keep the chapter sufficiency gap open.
 
 Stop conditions:
 - No open externally researchable gaps remain.