@cyber-dash-tech/revela 0.15.4 → 0.16.2

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.15.4",
+  "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[])

package/tools/narrative-view.ts

@@ -34,6 +34,16 @@ export default tool({
         risks: tool.schema.string().optional(),
         researchGaps: tool.schema.string().optional(),
         coveredSlides: tool.schema.string().optional(),
+        storyWorkbench: tool.schema.string().optional(),
+        workbenchNote: tool.schema.string().optional(),
+        artifactCoverage: tool.schema.string().optional(),
+        noRenderTargets: tool.schema.string().optional(),
+        nextActions: tool.schema.string().optional(),
+        missingClaims: tool.schema.string().optional(),
+        affectedClaims: tool.schema.string().optional(),
+        affectedSlides: tool.schema.string().optional(),
+        notes: tool.schema.string().optional(),
+        recommendedNextCommand: tool.schema.string().optional(),
         noClaims: tool.schema.string().optional(),
         none: tool.schema.string().optional(),
       }).optional(),
@@ -49,7 +59,7 @@ export default tool({
         fromClaimId: tool.schema.string(),
         toClaimId: tool.schema.string(),
         relation: tool.schema.enum(["leads_to", "supports", "depends_on", "contrasts_with", "constrains", "answers"]),
-          displayLabel: tool.schema.string().optional().describe("Display-only localization of an existing canonical relation label. Omit for inferred relations."),
+        displayLabel: tool.schema.string().optional().describe("Display-only localization of an existing canonical relation label. Omit for inferred relations."),
         displayRationale: tool.schema.string().optional().describe("Display-only localization of an existing canonical rationale. Omit when canonical rationale is missing or the relation is inferred."),
       })).optional(),
     }).optional().describe("Localized and organized display-only projection. It must not add facts or alter IDs."),