@cyber-dash-tech/revela 0.16.1 → 0.16.2

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/narrative-state/research-gaps.ts

@@ -1,9 +1,12 @@
+import { existsSync, readFileSync } from "fs"
+import { resolve, sep } from "path"
 import type { DecksState } from "../decks-state"
 import { recordWorkspaceAction } from "../workspace-state/actions"
 import { stableResearchGapId } from "./hash"
 import { normalizeNarrativeState } from "./normalize"
 import { reviewNarrativeState } from "./readiness"
 import type {
+  NarrativeClaim,
   NarrativeReadinessIssue,
   NarrativeResearchGap,
   NarrativeResearchGapStatus,
@@ -11,6 +14,62 @@ import type {
   NarrativeStateV1,
 } from "./types"
 
+export type ResearchTargetKind =
+  | "research_gap"
+  | "missing_evidence"
+  | "weak_evidence"
+  | "unsupported_scope"
+  | "unhandled_objection"
+  | "high_severity_risk"
+  | "unattached_findings"
+  | "claim_chain_gap"
+
+export type EvidenceBindingFailureReason =
+  | "missing_quote"
+  | "unclear_source"
+  | "over_broad_claim"
+  | "weak_source"
+  | "unsupported_scope"
+  | "caveat_conflict"
+  | "source_mismatch"
+  | "context_only_finding"
+
+export interface ResearchTarget {
+  id: string
+  kind: ResearchTargetKind
+  targetType: NarrativeResearchGapTargetType | "findings" | "relation"
+  targetId?: string
+  priority: "high" | "medium" | "low"
+  reason: string
+  question: string
+  status?: NarrativeResearchGapStatus | "unattached"
+  findingsFile?: string
+  claimId?: string
+  claimText?: string
+  requiredEvidence: string[]
+  bindingFailureReasons?: EvidenceBindingFailureReason[]
+  bindingDiagnostic?: EvidenceBindingDiagnostic
+}
+
+export interface ResearchTargetsResult {
+  targets: ResearchTarget[]
+  selected?: ResearchTarget
+}
+
+export interface EvidenceBindingDiagnostic {
+  findingsFile: string
+  bindable: boolean
+  failureReasons: EvidenceBindingFailureReason[]
+  explicit: {
+    source: boolean
+    quoteOrSnippet: boolean
+    supportScope: boolean
+    unsupportedScope: boolean
+    caveat: boolean
+    strength: boolean
+  }
+}
+
 export interface UpsertResearchGapInput {
   id?: string
   targetType?: NarrativeResearchGapTargetType
@@ -46,6 +105,20 @@ export interface CloseResearchGapResult {
   gap?: NarrativeResearchGap
 }
 
+export function deriveResearchTargets(state: DecksState, options: { now?: string; workspaceRoot?: string } = {}): ResearchTargetsResult {
+  const reviewed = reviewNarrativeState(state, { now: options.now })
+  const narrative = reviewed.state.narrative!
+  const targets = dedupeTargets([
+    ...targetsFromResearchGaps(narrative, options.workspaceRoot),
+    ...targetsFromClaims(narrative),
+    ...targetsFromObjections(narrative),
+    ...targetsFromRisks(narrative),
+    ...targetsFromReadinessIssues(reviewed.result.issues),
+    ...targetsFromUnattachedFindings(reviewed.state, narrative, options.workspaceRoot),
+  ]).sort(compareResearchTargets)
+  return { targets, selected: targets[0] }
+}
+
 export function deriveResearchGapsFromReadiness(state: DecksState, options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
   const reviewed = reviewNarrativeState(state, { now: options.now })
   return upsertResearchGapsInState(reviewed.state, gapsFromIssues(reviewed.state.narrative!, reviewed.result.issues), options)
@@ -137,6 +210,265 @@ function gapsFromIssues(narrative: NarrativeStateV1, issues: NarrativeReadinessI
   })
 }
 
+function targetsFromResearchGaps(narrative: NarrativeStateV1, workspaceRoot: string | undefined): ResearchTarget[] {
+  return (narrative.researchGaps ?? [])
+    .filter((gap) => gap.status !== "closed" && gap.status !== "evidence_bound")
+    .map((gap) => {
+      const claim = gap.targetType === "claim" ? narrative.claims.find((item) => item.id === gap.targetId) : undefined
+      const bindingDiagnostic = gap.findingsFile ? evidenceBindingDiagnostic(workspaceRoot, gap.findingsFile) : undefined
+      return {
+        id: `gap:${gap.id}`,
+        kind: "research_gap",
+        targetType: gap.targetType,
+        targetId: gap.targetId,
+        priority: gap.priority,
+        reason: gap.status === "findings_saved" || gap.status === "attached"
+          ? "Saved findings exist; inspect and bind explicit evidence before launching new research."
+          : "Open canonical research gap needs findings or binding progress.",
+        question: gap.question,
+        status: gap.status,
+        findingsFile: gap.findingsFile,
+        claimId: claim?.id,
+        claimText: claim?.text,
+        requiredEvidence: requiredEvidenceForClaim(claim),
+        bindingFailureReasons: bindingDiagnostic?.failureReasons ?? (gap.findingsFile ? ["missing_quote", "unclear_source", "unsupported_scope"] : undefined),
+        bindingDiagnostic,
+      } satisfies ResearchTarget
+    })
+}
+
+function targetsFromClaims(narrative: NarrativeStateV1): ResearchTarget[] {
+  return narrative.claims.flatMap((claim) => {
+    const targets: ResearchTarget[] = []
+    if (claim.evidenceRequired && claim.evidenceStatus === "missing") {
+      targets.push(claimTarget("missing_evidence", claim, claim.importance === "central" ? "high" : "medium", "Evidence-required claim has no bound support."))
+    }
+    if (claim.evidenceRequired && (claim.evidenceStatus === "weak" || claim.evidenceStatus === "partial")) {
+      targets.push(claimTarget("weak_evidence", claim, claim.importance === "central" ? "high" : "medium", `Claim evidence is ${claim.evidenceStatus}; strengthen source trace or narrow scope.`))
+    }
+    if (claim.unsupportedScope) {
+      targets.push(claimTarget("unsupported_scope", claim, claim.importance === "central" ? "high" : "medium", "Claim records unsupported scope that needs evidence, narrowing, or explicit caveat."))
+    }
+    return targets
+  })
+}
+
+function targetsFromObjections(narrative: NarrativeStateV1): ResearchTarget[] {
+  return narrative.objections
+    .filter((objection) => objection.priority === "high" && !objection.response)
+    .map((objection) => ({
+      id: `objection:${objection.id}`,
+      kind: "unhandled_objection",
+      targetType: "objection",
+      targetId: objection.id,
+      priority: "high",
+      reason: "High-priority objection has no recorded response or evidence boundary.",
+      question: `Find response or evidence for objection: ${objection.text}`,
+      claimId: objection.claimId,
+      claimText: narrative.claims.find((claim) => claim.id === objection.claimId)?.text,
+      requiredEvidence: ["response evidence or boundary", "source", "quote/snippet", "caveat"],
+    } satisfies ResearchTarget))
+}
+
+function targetsFromRisks(narrative: NarrativeStateV1): ResearchTarget[] {
+  return narrative.risks
+    .filter((risk) => risk.severity === "high" && !risk.mitigation)
+    .map((risk) => ({
+      id: `risk:${risk.id}`,
+      kind: "high_severity_risk",
+      targetType: "risk",
+      targetId: risk.id,
+      priority: "high",
+      reason: "High-severity risk has no mitigation or evidence boundary.",
+      question: `Find mitigation, evidence boundary, or caveat for risk: ${risk.text}`,
+      claimId: risk.claimId,
+      claimText: narrative.claims.find((claim) => claim.id === risk.claimId)?.text,
+      requiredEvidence: ["mitigation evidence or boundary", "source", "quote/snippet", "caveat"],
+    } satisfies ResearchTarget))
+}
+
+function targetsFromReadinessIssues(issues: NarrativeReadinessIssue[]): ResearchTarget[] {
+  return issues.flatMap((issue) => {
+    if (issue.type !== "claim_chain_gap") return []
+    return [{
+      id: `issue:${issue.type}:${stableResearchGapId(issue.message)}`,
+      kind: "claim_chain_gap",
+      targetType: "relation",
+      priority: issue.severity === "blocker" ? "high" : "medium",
+      reason: issue.message,
+      question: issue.suggestedAction,
+      requiredEvidence: ["claim relation rationale", "supporting source or explicit user rationale", "caveat if relation is assumption-based"],
+    } satisfies ResearchTarget]
+  })
+}
+
+function targetsFromUnattachedFindings(state: DecksState, narrative: NarrativeStateV1, workspaceRoot: string | undefined): ResearchTarget[] {
+  return (state.actions ?? []).flatMap((action) => {
+    if (action.type !== "research.findings_saved") return []
+    const path = typeof action.outputs?.path === "string" ? action.outputs.path : undefined
+    if (!path || isFindingsAttachedOrBound(state, narrative, path)) return []
+    const bindingDiagnostic = evidenceBindingDiagnostic(workspaceRoot, path)
+    return [{
+      id: `findings:${path}`,
+      kind: "unattached_findings",
+      targetType: "findings",
+      targetId: path,
+      priority: "medium",
+      reason: "Saved findings are not attached to a research axis or bound as canonical evidence.",
+      question: `Inspect and attach or bind saved findings: ${path}`,
+      status: "unattached",
+      findingsFile: path,
+      requiredEvidence: ["source", "quote/snippet", "support scope", "unsupported scope", "caveat", "strength"],
+      bindingFailureReasons: bindingDiagnostic?.failureReasons ?? ["missing_quote", "unclear_source", "context_only_finding", "unsupported_scope"],
+      bindingDiagnostic,
+    } satisfies ResearchTarget]
+  })
+}
+
+function evidenceBindingDiagnostic(workspaceRoot: string | undefined, findingsFile: string): EvidenceBindingDiagnostic | undefined {
+  const text = readWorkspaceText(workspaceRoot, findingsFile)
+  if (text === undefined) return undefined
+
+  const explicit = {
+    source: hasSourceTrace(text),
+    quoteOrSnippet: hasQuoteOrSnippet(text),
+    supportScope: hasField(text, ["support scope", "supported scope", "supports", "support"]),
+    unsupportedScope: hasField(text, ["unsupported scope", "unsupported", "not supported", "gaps"]),
+    caveat: hasField(text, ["caveat", "limitation", "limits", "boundary"]),
+    strength: hasField(text, ["strength", "support strength", "evidence strength"]),
+  }
+  const failureReasons: EvidenceBindingFailureReason[] = []
+  if (!explicit.quoteOrSnippet) failureReasons.push("missing_quote")
+  if (!explicit.source) failureReasons.push("unclear_source")
+  if (!explicit.supportScope || !explicit.unsupportedScope) failureReasons.push("unsupported_scope")
+  if (!explicit.caveat) failureReasons.push("caveat_conflict")
+  if (!explicit.strength) failureReasons.push("weak_source")
+  if (looksContextOnly(text, explicit)) failureReasons.push("context_only_finding")
+
+  return {
+    findingsFile,
+    bindable: failureReasons.length === 0,
+    failureReasons,
+    explicit,
+  }
+}
+
+function readWorkspaceText(workspaceRoot: string | undefined, relativePath: string): string | undefined {
+  if (!workspaceRoot) return undefined
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, relativePath)
+  if (target !== root && !target.startsWith(root + sep)) return undefined
+  if (!existsSync(target)) return undefined
+  return readFileSync(target, "utf-8")
+}
+
+function hasSourceTrace(text: string): boolean {
+  return /^sources:\s*$/im.test(text)
+    || /\[source:\s*[^\]]+\]/i.test(text)
+    || /^\s*-?\s*source:\s*\S+/im.test(text)
+    || /^\s*source\s+(path|url):\s*\S+/im.test(text)
+}
+
+function hasQuoteOrSnippet(text: string): boolean {
+  return hasField(text, ["quote", "snippet"])
+    || /["“][^"”]{20,}["”]/.test(text)
+    || /^>\s*\S.{20,}/m.test(text)
+}
+
+function hasField(text: string, labels: string[]): boolean {
+  return labels.some((label) => new RegExp(`(^|\\n)\\s*(?:[-*]\\s*)?${escapeRegex(label)}\\s*[:：]\\s*\\S`, "i").test(text)
+    || new RegExp(`^##+\\s+.*${escapeRegex(label)}`, "im").test(text))
+}
+
+function looksContextOnly(text: string, explicit: EvidenceBindingDiagnostic["explicit"]): boolean {
+  return /^##+\s+data\b/im.test(text) && !explicit.quoteOrSnippet && (!explicit.supportScope || !explicit.caveat)
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+function claimTarget(kind: Extract<ResearchTargetKind, "missing_evidence" | "weak_evidence" | "unsupported_scope">, claim: NarrativeClaim, priority: "high" | "medium", reason: string): ResearchTarget {
+  return {
+    id: `claim:${kind}:${claim.id}`,
+    kind,
+    targetType: "claim",
+    targetId: claim.id,
+    priority,
+    reason,
+    question: questionForClaimTarget(kind, claim),
+    claimId: claim.id,
+    claimText: claim.text,
+    requiredEvidence: requiredEvidenceForClaim(claim),
+    bindingFailureReasons: bindingFailuresForClaim(claim),
+  }
+}
+
+function questionForClaimTarget(kind: ResearchTargetKind, claim: NarrativeClaim): string {
+  if (kind === "missing_evidence") return `Find evidence for claim: ${claim.text}`
+  if (kind === "weak_evidence") return `Strengthen evidence for claim: ${claim.text}`
+  if (kind === "unsupported_scope") return `Resolve unsupported scope for claim: ${claim.text}`
+  return claim.text
+}
+
+function requiredEvidenceForClaim(claim: NarrativeClaim | undefined): string[] {
+  const base = ["source", "quote/snippet", "support scope", "unsupported scope", "caveat", "strength"]
+  if (!claim) return base
+  if (claim.unsupportedScope) return [...base, `address unsupported scope: ${claim.unsupportedScope}`]
+  return base
+}
+
+function bindingFailuresForClaim(claim: NarrativeClaim): EvidenceBindingFailureReason[] {
+  const reasons: EvidenceBindingFailureReason[] = ["missing_quote", "unclear_source"]
+  if (claim.evidenceStatus === "weak") reasons.push("weak_source")
+  if (claim.unsupportedScope) reasons.push("unsupported_scope", "over_broad_claim")
+  return reasons
+}
+
+function isFindingsAttachedOrBound(state: DecksState, narrative: NarrativeStateV1, path: string): boolean {
+  const attached = Object.values(state.decks ?? {}).some((deck) => deck.researchPlan.some((axis) => axis.findingsFile === path))
+  const bound = narrative.evidenceBindings.some((binding) => binding.findingsFile === path)
+  return attached || bound
+}
+
+function dedupeTargets(targets: ResearchTarget[]): ResearchTarget[] {
+  const seen = new Set<string>()
+  const result: ResearchTarget[] = []
+  for (const target of targets) {
+    const key = `${target.kind}:${target.targetType}:${target.targetId ?? target.claimId ?? target.question}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(target)
+  }
+  return result
+}
+
+function compareResearchTargets(a: ResearchTarget, b: ResearchTarget): number {
+  return priorityValue(a.priority) - priorityValue(b.priority)
+    || kindValue(a.kind) - kindValue(b.kind)
+    || a.question.localeCompare(b.question)
+}
+
+function priorityValue(priority: ResearchTarget["priority"]): number {
+  if (priority === "high") return 0
+  if (priority === "medium") return 1
+  return 2
+}
+
+function kindValue(kind: ResearchTargetKind): number {
+  const values: Record<ResearchTargetKind, number> = {
+    research_gap: 0,
+    unattached_findings: 1,
+    missing_evidence: 2,
+    weak_evidence: 3,
+    unsupported_scope: 4,
+    unhandled_objection: 5,
+    high_severity_risk: 6,
+    claim_chain_gap: 7,
+  }
+  return values[kind]
+}
+
 function researchableIssue(issue: NarrativeReadinessIssue): boolean {
   return issue.type === "missing_evidence" || issue.type === "weak_evidence" || issue.type === "unsupported_scope" || issue.type === "unhandled_objection" || issue.type === "missing_risk"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",

package/tools/decks.ts

@@ -30,7 +30,7 @@ import {
 } from "../lib/narrative-state/readiness"
 import { compileDeckPlanFromNarrative } from "../lib/narrative-state/render-plan"
 import { backfillSlideClaimRefsFromCoverage } from "../lib/narrative-state/coverage"
-import { closeResearchGapInState, deriveResearchGapsFromReadiness, updateResearchGapInState, upsertResearchGapsInState } from "../lib/narrative-state/research-gaps"
+import { closeResearchGapInState, deriveResearchGapsFromReadiness, deriveResearchTargets, updateResearchGapInState, upsertResearchGapsInState } from "../lib/narrative-state/research-gaps"
 import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "../lib/narrative-state/normalize"
 import { narrativeToBrief } from "../lib/narrative-state/project-compat"
 import type { NarrativeStateV1 } from "../lib/narrative-state/types"
@@ -68,7 +68,7 @@ export default tool({
     "It stores workspace narrative state, active deck specs, per-slide content/layout/components, and computes narrative or deck readiness.",
   args: {
     action: tool.schema
-      .enum(["read", "init", "upsertDeck", "upsertSlides", "upsertNarrative", "compileDeckPlan", "confirmDeckPlan", "backfillClaimRefs", "review", "reviewNarrative", "approveNarrative", "deriveResearchGaps", "upsertResearchGaps", "updateResearchGap", "closeResearchGap", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
+      .enum(["read", "init", "upsertDeck", "upsertSlides", "upsertNarrative", "compileDeckPlan", "confirmDeckPlan", "backfillClaimRefs", "review", "reviewNarrative", "approveNarrative", "deriveResearchGaps", "deriveResearchTargets", "upsertResearchGaps", "updateResearchGap", "closeResearchGap", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
       .describe("Action to perform on DECKS.json."),
     summary: tool.schema.boolean().optional().describe("For read: return a compact summary instead of full state."),
     goal: tool.schema.string().optional().describe("For upsertDeck: deck goal."),
@@ -484,6 +484,11 @@ export default tool({
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: derived.result, narrative: derived.state.narrative }, null, 2)
       }
 
+      if (args.action === "deriveResearchTargets") {
+        const result = deriveResearchTargets(state, { workspaceRoot })
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result }, null, 2)
+      }
+
       if (args.action === "upsertResearchGaps") {
         if (!args.researchGaps?.length) return JSON.stringify({ ok: false, error: "researchGaps are required for upsertResearchGaps" })
         const upserted = upsertResearchGapsInState(state, args.researchGaps as any[])