@cyber-dash-tech/revela 0.15.4 → 0.16.2

package/lib/commands/narrative.ts

@@ -124,7 +124,13 @@ 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 })),
     researchGaps: map.researchGaps.map((gap) => ({ id: gap.id, targetType: gap.targetType, targetId: gap.targetId, status: gap.status, priority: gap.priority, question: gap.question })),
-    artifactCoverage: map.artifactCoverage.map((artifact) => ({ type: artifact.type, outputPath: artifact.outputPath, stale: artifact.stale, slideRefs: artifact.slideRefs.map((ref) => ({ claimId: ref.claimId, slideIndex: ref.slideIndex, role: ref.role, match: ref.match, location: ref.location })) })),
+    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 })) })),
+    workbench: {
+      summary: map.workbench.summary,
+      filters: map.workbench.filters,
+      renderTargetAction: map.workbench.renderTargetAction,
+      artifactCoverage: map.workbench.artifactCoverage.map((item) => ({ type: item.type, outputPath: item.outputPath, coverageStatus: item.coverageStatus, affectedClaimIds: item.affectedClaimIds, missingClaimIds: item.missingClaimIds, statusNote: item.statusNote, recommendedNextCommand: item.recommendedNextCommand })),
+    },
   }
 
   return `Prepare the read-only Revela narrative UI display model.
@@ -141,11 +147,11 @@ 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, riskOrGapSummary, relation displayLabel, and relation displayRationale.
+- You may only organize and localize display copy for the UI: pageTitle, summaryLine, section labels including Story workbench labels, claim card displayTitle, roleLabel, narrativeJob, evidenceSummary, riskOrGapSummary, 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, riskOrGapSummary, relation displayLabel, and relation displayRationale.
+- Translate normal UI/display text into the target language request: pageTitle, summaryLine, labels including workbench labels, claim displayTitle, roleLabel, narrativeJob, evidenceSummary, riskOrGapSummary, relation displayLabel, and relation displayRationale.
 - Do not translate claim IDs, relation endpoints, narrative hash, source paths, findings files, URLs, numbers, or quoted/source facts.
 - 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.

package/lib/commands/research.ts

@@ -25,18 +25,19 @@ Current state:
 ${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
 
 Closed-loop workflow:
-1. Call \`revela-decks\` action \`read\`, then \`reviewNarrative\`.
-2. If current research gaps are missing or stale, call \`deriveResearchGaps\` when useful. Do not invent gaps that are not tied to a claim, objection, risk, decision, or narrative issue.
+1. Call \`revela-decks\` action \`read\`, then \`reviewNarrative\`, then \`deriveResearchTargets\`. Treat the returned \`selected\` target as the deterministic first target unless it is clearly blocked by user-only information.
+2. If current research gaps are missing or stale, call \`deriveResearchGaps\` when useful, then call \`deriveResearchTargets\` again. Do not invent gaps that are not tied to a claim, objection, risk, decision, or narrative issue.
 3. Run up to 3 research loops unless the stop conditions below are met earlier.
-4. At the start of each loop, choose the highest-value 2-3 targets: open/in-progress high-priority gaps, unattached saved findings, unsupported central claims, weak evidence, high-priority objections/risks, and claim_chain_gap relations. Prefer targets that can improve readiness or materially reduce caveats. Do not repeat searches for claims already strongly supported.
-5. If a target already has saved findings, prioritize binding/narrowing before doing more external search.
-6. For targets needing external evidence, mark matching gaps \`in_progress\` with \`revela-decks updateResearchGap\`, then delegate search to the \`revela-research\` subagent. Ask it for source URLs, quotes/snippets, dates or locations when available, caveats, remaining gaps, and a \`## Recommended evidence bindings\` section with claimId, quote, source, supportScope, unsupportedScope, caveat, and strength. Save findings with \`revela-research-save\` under \`researches/{topic}/{axis}.md\` using \`## Data\`, \`## Cases\`, \`## Images\`, and \`## Gaps\` sections as applicable.
-7. After findings are saved or existing findings are selected, read or inspect the findings file. Attach it with \`revela-decks attachResearchFindings\` when it maps to an existing research axis.
-8. Automatically bind evidence when all binding criteria are met. Use \`revela-decks applyEvidenceCandidates\` for concrete candidate ids when available, or \`upsertNarrative\` to preserve canonical evidence bindings with exact source, URL/path, quote/snippet, support scope, unsupported scope, caveat, and strength.
-9. Binding criteria: claimId exists; quote/snippet is traceable to the source and is not invented; source URL or workspace source path is present; supportScope and unsupportedScope are explicit; strength is strong or useful partial; caveat is preserved; binding does not expand the claim beyond the evidence.
-10. If a claim or relation is broader than the evidence, narrow the claim text, supportedScope, unsupportedScope, or relation rationale through \`upsertNarrative\` only when the narrower wording preserves the user's strategic meaning and source boundaries. Do not silently change the decision ask, central recommendation, or approval meaning.
-11. Update matching gaps after binding: use \`evidence_bound\` when canonical evidence was added, \`closed\` when the gap is resolved or non-researchable, \`findings_saved\` only when findings exist but binding criteria are not met, and \`open\` with notes when more external research is still warranted.
-12. Re-run \`reviewNarrative\` after each loop. Compare against the previous loop: fewer open gaps, fewer unattached findings, stronger evidence, narrower unsupported scope, or clearer internal-data caveats should count as progress.
+4. At the start of each loop, use \`deriveResearchTargets\` as the target order. Work the \`selected\` target first, then the next 1-2 highest-priority targets only when they are related. Do not repeat searches for claims already strongly supported.
+5. If a target has \`findingsFile\` or \`kind: "unattached_findings"\`, inspect \`bindingDiagnostic\` before doing external search. Prefer existing findings before external research.
+6. When \`bindingDiagnostic.bindable\` is false, do not bind or package the findings as strong evidence. Report the exact \`failureReasons\` such as \`missing_quote\`, \`unclear_source\`, \`unsupported_scope\`, \`caveat_conflict\`, \`weak_source\`, \`source_mismatch\`, or \`context_only_finding\`, then either narrow the claim safely or run targeted research for the missing fields.
+7. For targets needing external evidence, mark matching gaps \`in_progress\` with \`revela-decks updateResearchGap\`, then delegate search to the \`revela-research\` subagent. Ask it for source URLs, quotes/snippets, dates or locations when available, caveats, remaining gaps, and a \`## Recommended evidence bindings\` section with claimId, quote, source, supportScope, unsupportedScope, caveat, and strength. Save findings with \`revela-research-save\` under \`researches/{topic}/{axis}.md\` using \`## Data\`, \`## Cases\`, \`## Images\`, and \`## Gaps\` sections as applicable.
+8. After findings are saved or existing findings are selected, read or inspect the findings file. Attach it with \`revela-decks attachResearchFindings\` when it maps to an existing research axis. Re-run \`deriveResearchTargets\` so the next loop sees updated \`bindingDiagnostic\` and target order.
+9. Automatically bind evidence only when all binding criteria are met and the diagnostic is \`bindable: true\` or the same fields are explicit in the findings. Use \`revela-decks applyEvidenceCandidates\` for concrete candidate ids when available, or \`upsertNarrative\` to preserve canonical evidence bindings with exact source, URL/path, quote/snippet, support scope, unsupported scope, caveat, and strength.
+10. Binding criteria: claimId exists; quote/snippet is traceable to the source and is not invented; source URL or workspace source path is present; supportScope and unsupportedScope are explicit; strength is strong or useful partial; caveat is preserved; binding does not expand the claim beyond the evidence.
+11. If a claim or relation is broader than the evidence, narrow the claim text, supportedScope, unsupportedScope, or relation rationale through \`upsertNarrative\` only when the narrower wording preserves the user's strategic meaning and source boundaries. Do not silently change the decision ask, central recommendation, or approval meaning.
+12. Update matching gaps after binding: use \`evidence_bound\` when canonical evidence was added, \`closed\` when the gap is resolved or non-researchable, \`findings_saved\` only when findings exist but binding criteria are not met, and \`open\` with notes when more external research is still warranted.
+13. Re-run \`reviewNarrative\` and \`deriveResearchTargets\` after each loop. Compare against the previous loop: fewer open gaps, fewer unattached findings, stronger evidence, narrower unsupported scope, or clearer internal-data caveats should count as progress.
 
 Stop conditions:
 - No open externally researchable gaps remain.
@@ -47,20 +48,26 @@ Stop conditions:
 
 Report format:
 - Start with \`Research loop completed after <n> round(s).\`
-- List bound evidence by claim id and count.
-- List gaps closed or moved to evidence_bound.
-- List claims or relations narrowed, with the remaining unsupported scope.
-- List remaining caveats only as one of: \`internal_data_needed\`, \`not_publicly_researchable\`, \`source_quality_limit\`, or \`still_open\`.
-- If no binding happened, say why binding criteria failed and what exact source type is needed next.
-- End with the next smallest story action, not a generic request for user confirmation.
+- Then use these exact sections in order:
+  - \`Selected target\`: report \`kind\`, \`priority\`, \`reason\`, \`question\`, \`targetId\`, \`claimId\`, and any \`findingsFile\`.
+  - \`Existing findings inspected\`: for each file, report \`findingsFile\`, \`bindingDiagnostic.bindable\`, \`failureReasons\`, and which explicit fields were present: \`source\`, \`quoteOrSnippet\`, \`supportScope\`, \`unsupportedScope\`, \`caveat\`, \`strength\`. If none were inspected, write \`none\`.
+  - \`Attachments\`: list findings attached with axis/status, or \`none\`.
+  - \`Evidence bound\`: list evidence bindings by claim id, source, quote/snippet, supportScope, unsupportedScope, caveat, and strength, or \`none\`.
+  - \`Unbound findings\`: list every inspected but unbound findings file with structured failure reasons such as \`missing_quote\`, \`unclear_source\`, \`unsupported_scope\`, \`caveat_conflict\`, \`weak_source\`, \`source_mismatch\`, or \`context_only_finding\`. If none, write \`none\`.
+  - \`Gap updates\`: list gaps moved to \`in_progress\`, \`findings_saved\`, \`attached\`, \`evidence_bound\`, \`closed\`, or still \`open\` with notes.
+  - \`Narrative changes\`: list claims or relations narrowed, with remaining unsupported scope. If none, write \`none\`.
+  - \`Remaining caveats\`: use only \`internal_data_needed\`, \`not_publicly_researchable\`, \`source_quality_limit\`, or \`still_open\`.
+  - \`Next smallest story action\`: end with one concrete next command or action, not a generic request for confirmation.
+- If no binding happened, the \`Unbound findings\` or \`Remaining caveats\` section must say why binding criteria failed and what exact source type is needed next.
 
 Rules:
 - Do not use primary-agent broad websearch. Use the \`revela-research\` subagent for external search.
 - Do not invent quotes, source paths, URLs, page references, locations, or caveats.
 - Do not treat \`researches/**/*.md\` as canonical evidence until attached or evidence-bound, but do not stop at findings_saved when binding criteria are met.
+- Do not bypass \`deriveResearchTargets\`; target selection, \`selected\`, and \`bindingDiagnostic\` are deterministic inputs, not LLM judgement.
 - Do not mutate canonical claims merely to fit a source; narrow only to preserve evidence boundaries and avoid overstated claims.
 - Do not ask the user to approve each evidence binding. Ask only when binding would change strategic meaning, downgrade a central claim, rely on suspicious sources, or require narrative approval.
 - Do not store secrets, credentials, tokens, or sensitive personal information.
 
-Start now by reading ${DECKS_STATE_FILE} through \`revela-decks\`, reviewing current readiness, and running the first research/binding loop.`
+Start now by reading ${DECKS_STATE_FILE} through \`revela-decks\`, reviewing current readiness, deriving research targets, and running the first research/binding loop from the selected target.`
 }

package/lib/commands/review.ts

@@ -205,7 +205,7 @@ Workflow:
 8. For substantial decision decks, preserve a compact \`narrativeBrief\` through \`upsertDeck\` when the conversation or confirmed plan supports it. Do not invent stakeholder beliefs, objections, or risks; leave gaps visible if unknown.
 9. For substantial decision decks, launch the Task subagent with \`subagent_type: "revela-narrative-reviewer"\` after deck/slides are up to date. Ask it to read the current \`DECKS.json\`, run only its fixed rubric, use stable finding IDs, return \`Findings: none\` when all checks pass, and avoid optional pre-write improvements. Do not ask it to write state, call \`revela-decks review\`, or produce HTML.
 10. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
-11. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks; separate evidence/source warnings from narrative warnings when possible. If the review result includes \`evidenceCandidates\`, add a separate \`Candidate evidence bindings\` section with candidateId, slide index/title, supported claim scope, sourceKind, findingsFile/sourcePath, quote/snippet, caveat, evidenceDraft summary, unsupportedScope, and recommendedRewrite. Tell the user they may explicitly ask to apply selected candidate IDs; do not apply them during review. If candidates are absent but \`evidenceCandidateSearch\` is present, briefly report searched file counts and the best near misses so the user can tell whether review failed to search or searched but did not find a bindable match. If the reviewer returned findings, include them in a separate \`Narrative reviewer notes\` section and label them advisory.
+11. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks; separate evidence/source warnings from narrative warnings when possible. If the review result includes \`diagnostics\`, include a \`Plan and coverage diagnostics\` section with plan quality blockers/warnings, artifact \`coverageStatus\`, \`missingClaimIds\`, \`affectedClaimIds\`, stale reasons, and \`nextActions\`. If the review result includes \`evidenceCandidates\`, add a separate \`Candidate evidence bindings\` section with candidateId, slide index/title, supported claim scope, sourceKind, findingsFile/sourcePath, quote/snippet, caveat, evidenceDraft summary, unsupportedScope, and recommendedRewrite. Tell the user they may explicitly ask to apply selected candidate IDs; do not apply them during review. If candidates are absent but \`evidenceCandidateSearch\` is present, briefly report searched file counts and the best near misses so the user can tell whether review failed to search or searched but did not find a bindable match. If the reviewer returned findings, include them in a separate \`Narrative reviewer notes\` section and label them advisory.
 
 Minimum conditions for \`ready\`:
 - Topic, audience, slide count, language, and visual style/design are decided.
@@ -225,6 +225,7 @@ Report format:
 - Start with \`Ready: yes/no\`.
 - If blocked, list each blocker with slide index/title when the tool provides it, the issue type, and the suggested next action.
 - If warnings exist but the deck is otherwise ready, say the deck can be written but note the residual risks.
+- Include coverage-driven make diagnostics when returned: whether the active deck artifact coverage is current/stale/partial/missing, which required claims are missing, which claims are affected, and the next command/action recommended by the tool.
 - Report \`narrative_gap\` warnings as story-structure risks such as weak so-what, missing risk/assumption handling, conclusion before support, missing audience framing, or abrupt transition.
 - Do not invent evidence or silently downgrade blockers. Use the tool result as authoritative.
 - Do not convert \`revela-narrative-reviewer\` advisory findings into tool readiness issues. Keep them separate from \`revela-decks review\` blockers and warnings, and preserve the reviewer's stable finding IDs when reporting them.

package/lib/decks-state.ts

@@ -8,7 +8,7 @@ import {
   workspaceStatePath,
   writeWorkspaceState,
 } from "./workspace-state/repository"
-import { ensureActiveHtmlDeckRenderTarget } from "./workspace-state/render-targets"
+import { activeHtmlDeckRenderTarget, ensureActiveHtmlDeckRenderTarget } from "./workspace-state/render-targets"
 import {
   activeReviewTargetId,
   appendReviewSnapshot,
@@ -19,6 +19,7 @@ import {
 import { WORKSPACE_STATE_FILE, type RenderTarget, type ReviewSnapshot, type WorkspaceAction } from "./workspace-state/types"
 import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "./narrative-state/normalize"
 import { computeNarrativeHash } from "./narrative-state/hash"
+import { getArtifactClaimRefs } from "./narrative-state/queries"
 import type { NarrativeStateV1 } from "./narrative-state/types"
 
 export const DECKS_STATE_FILE = WORKSPACE_STATE_FILE
@@ -107,6 +108,13 @@ export interface DeckPlanReview {
   confirmedAt?: string
   confirmedBy?: "user"
   summary?: string
+  qualityChecks?: DeckPlanQualityCheck[]
+}
+
+export interface DeckPlanQualityCheck {
+  id: string
+  status: "pass" | "warning" | "blocker"
+  message: string
 }
 
 export interface NarrativeBrief {
@@ -206,6 +214,24 @@ export interface DeckStateReadinessResult {
   warnings: string[]
   issues: ReadinessIssue[]
   evidenceCandidates?: EvidenceBindingCandidate[]
+  diagnostics?: DeckReadinessDiagnostics
+}
+
+export interface DeckReadinessDiagnostics {
+  planQuality: DeckPlanQualityCheck[]
+  artifactCoverage?: ArtifactCoverageDiagnostic
+  nextActions: string[]
+}
+
+export interface ArtifactCoverageDiagnostic {
+  artifactId?: string
+  outputPath?: string
+  coverageStatus: "current" | "stale" | "partial" | "missing" | "unknown"
+  requiredClaimIds: string[]
+  coveredClaimIds: string[]
+  missingClaimIds: string[]
+  affectedClaimIds: string[]
+  staleReasons: string[]
 }
 
 export type ReadinessSeverity = "blocker" | "warning"
@@ -214,6 +240,8 @@ export type ReadinessIssueType =
   | "missing_required_input"
   | "missing_slide_spec"
   | "slide_plan_unconfirmed"
+  | "plan_quality"
+  | "artifact_coverage"
   | "research_not_ready"
   | "missing_evidence"
   | "weak_evidence"
@@ -444,6 +472,7 @@ export function confirmDeckPlan(state: DecksState, options: ConfirmDeckPlanOptio
     confirmedAt: options.now ?? new Date().toISOString(),
     confirmedBy: options.approvedBy ?? "user",
     summary: cleanOptionalText(options.note),
+    qualityChecks: pending?.qualityChecks,
   }
   deck.requiredInputs = { ...deck.requiredInputs, slidePlanConfirmed: true }
   deck.writeReadiness = { status: "blocked", blockers: [] }
@@ -579,7 +608,7 @@ export function reviewDeckState(state: DecksState, slug?: string, options: Revie
     }
   }
 
-  const issues = computeDeckReadinessIssues(deck, normalized.workspace, {
+  const issues = computeDeckReadinessIssues(normalized, deck, {
     ...options,
     narrativeHash: options.narrativeHash ?? computeNarrativeHash(normalizeNarrativeState(normalized)),
   })
@@ -604,6 +633,7 @@ export function reviewDeckState(state: DecksState, slug?: string, options: Revie
     warnings,
     issues,
     evidenceCandidates,
+    diagnostics: deckReadinessDiagnostics(normalized, deck, issues),
   }
   appendReviewSnapshot(normalized, createReviewSnapshot(normalized, { slug: deck.slug, result, reviewedAt }))
   return {
@@ -639,7 +669,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
     }
   }
 
-  const issues = computeDeckReadinessIssues(deck, normalized.workspace, {
+  const issues = computeDeckReadinessIssues(normalized, deck, {
     narrativeHash: computeNarrativeHash(normalizeNarrativeState(normalized)),
   })
   const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
@@ -715,6 +745,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
     blockers,
     warnings,
     issues,
+    diagnostics: deckReadinessDiagnostics(normalized, deck, issues),
   }
 }
 
@@ -871,9 +902,23 @@ function normalizeDeckPlanReview(input: DeckPlanReview | undefined): DeckPlanRev
     confirmedAt: cleanOptionalText(input.confirmedAt),
     confirmedBy: input.confirmedBy === "user" ? "user" : undefined,
     summary: cleanOptionalText(input.summary),
+    qualityChecks: normalizeDeckPlanQualityChecks(input.qualityChecks),
   }
 }
 
+function normalizeDeckPlanQualityChecks(input: DeckPlanQualityCheck[] | undefined): DeckPlanQualityCheck[] | undefined {
+  if (!Array.isArray(input)) return undefined
+  const checks = input.flatMap((item): DeckPlanQualityCheck[] => {
+    if (!item || typeof item !== "object") return []
+    const id = cleanOptionalText(item.id)
+    const message = cleanOptionalText(item.message)
+    if (!id || !message) return []
+    const status = item.status === "blocker" || item.status === "warning" ? item.status : "pass"
+    return [{ id, status, message }]
+  })
+  return checks.length > 0 ? checks : undefined
+}
+
 function currentDeckKey(state: DecksState): string | undefined {
   if (state.activeDeck && state.decks[state.activeDeck]) return state.activeDeck
   const keys = Object.keys(state.decks)
@@ -887,8 +932,9 @@ function currentDeckBlocker(state: DecksState): string {
   return `${DECKS_STATE_FILE} contains multiple deck records and no activeDeck. Select one current deck explicitly or move extra decks to separate workspaces.`
 }
 
-function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["workspace"], options: ReviewDeckStateOptions = {}): ReadinessIssue[] {
+function computeDeckReadinessIssues(state: DecksState, deck: DeckSpec, options: ReviewDeckStateOptions = {}): ReadinessIssue[] {
   const issues: ReadinessIssue[] = []
+  const workspace = state.workspace
   if (!deck.goal.trim()) issues.push(blockerIssue("missing_slide_spec", "Deck goal is missing", "Set the deck goal through revela-decks upsertDeck."))
   if (!isDeckHtmlPath(deck.outputPath)) {
     issues.push(blockerIssue(
@@ -919,6 +965,8 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
       ))
     }
   }
+  issues.push(...deckPlanQualityIssues(deck))
+  issues.push(...artifactCoverageIssues(state, deck))
   for (const slide of deck.slides) {
     const slideRef = { slideIndex: slide.index, slideTitle: slide.title }
     if (!slide.title.trim()) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} title is missing`, "Add a slide title to the slide spec.", slideRef))
@@ -985,6 +1033,96 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
   return issues
 }
 
+function deckPlanQualityIssues(deck: DeckSpec): ReadinessIssue[] {
+  const checks = deck.planReview?.qualityChecks ?? []
+  return checks.flatMap((check): ReadinessIssue[] => {
+    if (check.status === "pass") return []
+    const suggestedAction = check.status === "blocker"
+      ? "Re-run compileDeckPlan or revise the deck projection so the deterministic plan includes Cover, TOC, central claim coverage, compatible components, and Closing/Decision Ask before confirming or writing the deck."
+      : "Keep the stated claim boundaries visible in the plan and rendered artifact; do not stretch partial evidence beyond the supported scope."
+    return [{
+      type: "plan_quality",
+      severity: check.status,
+      message: check.message,
+      suggestedAction,
+    }]
+  })
+}
+
+function artifactCoverageIssues(state: DecksState, deck: DeckSpec): ReadinessIssue[] {
+  const coverage = artifactCoverageDiagnostic(state, deck)
+  if (!coverage) return []
+  const issues: ReadinessIssue[] = []
+  if (coverage.missingClaimIds.length > 0) {
+    issues.push(blockerIssue(
+      "artifact_coverage",
+      `Active deck plan is missing required narrative claims: ${coverage.missingClaimIds.join(", ")}`,
+      "Re-run compileDeckPlan or revise the deck projection so every central or evidence-required claim appears in the planned slides before writing the deck.",
+    ))
+  }
+  if (coverage.coverageStatus === "stale") {
+    issues.push(blockerIssue(
+      "artifact_coverage",
+      `Active deck artifact coverage is stale: ${coverage.staleReasons.join("; ") || "narrative or render target changed"}`,
+      "Re-run /revela make --deck so the deck plan and artifact coverage are regenerated from the current approved narrative state.",
+    ))
+  } else if (coverage.coverageStatus === "partial") {
+    issues.push(warningIssue(
+      "artifact_coverage",
+      `Active deck artifact coverage is partial: ${coverage.affectedClaimIds.join(", ") || "some claims are not fully mapped"}`,
+      "Keep the partial coverage visible in the make report and review the affected claims before exporting or presenting the deck.",
+    ))
+  }
+  return issues
+}
+
+function deckReadinessDiagnostics(state: DecksState, deck: DeckSpec, issues: ReadinessIssue[]): DeckReadinessDiagnostics {
+  const planQuality = deck.planReview?.qualityChecks ?? []
+  const artifactCoverage = artifactCoverageDiagnostic(state, deck)
+  return {
+    planQuality,
+    ...(artifactCoverage ? { artifactCoverage } : {}),
+    nextActions: readinessNextActions(issues, artifactCoverage),
+  }
+}
+
+function artifactCoverageDiagnostic(state: DecksState, deck: DeckSpec): ArtifactCoverageDiagnostic | undefined {
+  const target = activeHtmlDeckRenderTarget(state)
+  const artifact = getArtifactClaimRefs(state).find((item) => item.type === "html_deck" && normalizeDeckPath(item.outputPath ?? "") === normalizeDeckPath(deck.outputPath))
+  const data = target?.data ?? {}
+  const requiredClaimIds = stringArray(data.requiredClaimIds)
+  const coveredClaimIds = stringArray(data.coveredClaimIds)
+  const missingClaimIds = [...new Set([...(artifact?.missingClaimIds ?? []), ...stringArray(data.missingClaimIds)])].sort()
+  const affectedClaimIds = [...new Set([...(artifact?.affectedClaimIds ?? []), ...missingClaimIds])].sort()
+  const staleReasons = artifact?.staleReasons ?? []
+  const coverageStatus = artifact?.coverageStatus ?? (target ? (missingClaimIds.length > 0 ? "missing" : "current") : "unknown")
+  if (!target && !artifact && requiredClaimIds.length === 0 && coveredClaimIds.length === 0 && missingClaimIds.length === 0) return undefined
+  return {
+    artifactId: artifact?.artifactId ?? target?.id,
+    outputPath: artifact?.outputPath ?? target?.outputPath ?? deck.outputPath,
+    coverageStatus,
+    requiredClaimIds: [...new Set([...(artifact?.claimIds ?? []), ...requiredClaimIds, ...missingClaimIds])].filter((id) => requiredClaimIds.length === 0 || requiredClaimIds.includes(id) || missingClaimIds.includes(id)).sort(),
+    coveredClaimIds: [...new Set([...(artifact?.claimIds ?? []), ...coveredClaimIds])].filter((id) => missingClaimIds.length === 0 || !missingClaimIds.includes(id)).sort(),
+    missingClaimIds,
+    affectedClaimIds,
+    staleReasons,
+  }
+}
+
+function readinessNextActions(issues: ReadinessIssue[], coverage?: ArtifactCoverageDiagnostic): string[] {
+  const actions = issues
+    .filter((issue) => issue.severity === "blocker" || issue.type === "plan_quality" || issue.type === "artifact_coverage")
+    .map((issue) => issue.suggestedAction)
+  if (coverage?.missingClaimIds.length) actions.unshift("Review missingClaimIds in artifactCoverage and recompile the deterministic deck plan before writing HTML.")
+  if (coverage?.coverageStatus === "stale") actions.unshift("Regenerate the deck plan from the current narrative before writing or exporting artifacts.")
+  return [...new Set(actions)].slice(0, 5)
+}
+
+function stringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return [...new Set(value.filter((item): item is string => typeof item === "string" && item.trim().length > 0).map((item) => item.trim()))].sort()
+}
+
 function findEvidenceBindingCandidates(deck: DeckSpec, slide: SlideSpec, claimText: string, options: ReviewDeckStateOptions): { candidates: EvidenceBindingCandidate[]; search?: EvidenceCandidateSearchDiagnostic } {
   if (!options.workspaceRoot) return { candidates: [] }
   const queryText = slideSearchText(slide)

package/lib/narrative-state/display.ts

@@ -29,6 +29,16 @@ export interface NarrativeDisplayLabels {
   risks: string
   researchGaps: string
   coveredSlides: string
+  storyWorkbench: string
+  workbenchNote: string
+  artifactCoverage: string
+  noRenderTargets: string
+  nextActions: string
+  missingClaims: string
+  affectedClaims: string
+  affectedSlides: string
+  notes: string
+  recommendedNextCommand: string
   noClaims: string
   none: string
 }
@@ -79,6 +89,16 @@ export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage):
       risks: "风险",
       researchGaps: "研究缺口",
       coveredSlides: "已覆盖页面",
+      storyWorkbench: "Story 工作台",
+      workbenchNote: "按证据缺口、风险、异议和产物覆盖过滤主张；这里只读展示下一步命令，不修改叙事状态。",
+      artifactCoverage: "产物覆盖",
+      noRenderTargets: "未记录 render target",
+      nextActions: "下一步",
+      missingClaims: "缺失主张",
+      affectedClaims: "受影响主张",
+      affectedSlides: "受影响页面",
+      notes: "说明",
+      recommendedNextCommand: "建议命令",
       noClaims: "没有记录主张",
       none: "无",
     }
@@ -101,6 +121,16 @@ export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage):
       risks: "リスク",
       researchGaps: "調査ギャップ",
       coveredSlides: "対応スライド",
+      storyWorkbench: "Story ワークベンチ",
+      workbenchNote: "根拠ギャップ、リスク、反論、成果物カバレッジでクレームを絞り込みます。ここでは次のコマンドだけを読み取り専用で示し、ナラティブ状態は変更しません。",
+      artifactCoverage: "成果物カバレッジ",
+      noRenderTargets: "render target は記録されていません",
+      nextActions: "次のアクション",
+      missingClaims: "不足クレーム",
+      affectedClaims: "影響クレーム",
+      affectedSlides: "影響スライド",
+      notes: "メモ",
+      recommendedNextCommand: "推奨コマンド",
       noClaims: "クレームは記録されていません",
       none: "なし",
     }
@@ -122,6 +152,16 @@ export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage):
     risks: "Risks",
     researchGaps: "Research gaps",
     coveredSlides: "Covered slides",
+    storyWorkbench: "Story workbench",
+    workbenchNote: "Filter claims by evidence gaps, risks, objections, and artifact coverage. This view only suggests next commands; it does not mutate narrative state.",
+    artifactCoverage: "Artifact coverage",
+    noRenderTargets: "No render targets recorded",
+    nextActions: "Next actions",
+    missingClaims: "Missing claims",
+    affectedClaims: "Affected claims",
+    affectedSlides: "Affected slides",
+    notes: "Notes",
+    recommendedNextCommand: "Recommended next command",
     noClaims: "No claims recorded",
     none: "None",
   }