opencode-codegraph 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.7 - 2026-03-20
+
+- add command-oriented next-step guidance (`/status`, `/update`, `/review`) to review-trace and dogfooding status flows
+- unify `/review`, `/audit`, and `/update` around the shared `dogfood status --json` backend
+- keep session-start and post-commit guidance aligned on the same recommended command semantics
+
+## 0.1.6 - 2026-03-20
+
+- add explicit pending post-commit summary when durable review trace is not yet available
+- guide developers to `/status` instead of leaving post-commit review state ambiguous
+- document pending-trace behavior in plugin and OpenCode workflow docs
+
 ## 0.1.5 - 2026-03-20
 
 - add unified next-action summary to review-trace status output

package/README.md

@@ -39,13 +39,30 @@ Plugin injects:
 
 If the message also suggests an edit intent (`refactor`, `fix`, `modify`, `update`, etc.), the plugin appends a pre-edit warning block with complexity, fan-out, dead-code, and security hints for the referenced file.
 
-### System Prompt
-
-Every conversation includes a project summary with file count, top complexity hotspots, and open security findings.
+### System Prompt
+
+Every conversation includes:
+
+- a project summary with file count, top complexity hotspots, and open security findings;
+- a lightweight dogfooding status block when available, including freshness, current `HEAD`, review-trace state, and recommended next action.
+- a recommended command (`/status`, `/update`, or `/review`) when the workflow can point to a deterministic next step.
 
 ### Post-Commit Updates
 
-After `git commit`, the plugin triggers incremental CPG re-parsing via GoCPG and syncs the ChromaDB vector store. If durable review-trace artifacts exist for the new `HEAD`, the plugin also appends a short review-trace summary with findings, recommendations, and a single next action to take.
+After `git commit`, the plugin triggers incremental CPG re-parsing via GoCPG and syncs the ChromaDB vector store. If durable review-trace artifacts exist for the new `HEAD`, the plugin also appends a structured post-commit block with:
+
+- what changed in the review trace
+- why it matters
+- top recommendations
+- one clear next action
+- one suggested command to run next
+
+If the durable review trace is not available yet, the plugin still appends a pending summary telling the developer to check `/status` instead of leaving the post-commit state ambiguous.
+
+This means the post-commit UX now has two explicit states:
+
+- trace ready -> structured summary with findings, recommendations, and next action
+- trace pending/missing -> structured pending summary with deterministic follow-up
 
 ### Custom Tools
 
@@ -89,7 +106,7 @@ Place in `.opencode/commands/`:
 | `experimental.chat.system.transform` | Inject project summary into system prompt |
 | `chat.message` | Add CPG context for mentioned files |
 | `chat.message` (edit intent) | Add pre-edit warnings for files likely to be modified |
-| `tool.execute.after` | Trigger CPG update after git commit and append review-trace summary with next action |
+| `tool.execute.after` | Trigger CPG update after git commit and append structured post-commit review summary |
 | `permission.ask` | Auto-allow `codegraph_*` tools |
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codegraph",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "OpenCode plugin for CodeGraph CPG-powered code analysis",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -17,12 +17,17 @@ import { CodeGraphAPI } from "./api"
 import {
   extractFileRefs,
   fileNeedsRegistrationCheck,
+  formatDogfoodStatusSummary,
+  formatPendingReviewTraceSummary,
   formatReviewTraceSummary,
   getHeadCommit,
   isGitCommit,
   messageSuggestsEditing,
+  recommendedCommandFromReviewTrace,
   recommendedNextActionFromReviewTrace,
   readReviewTraceSnapshot,
+  whatChangedFromReviewTrace,
+  whyItMattersFromReviewTrace,
 } from "./util"
 
 const codegraphPlugin: Plugin = async (input) => {
@@ -39,16 +44,26 @@ const codegraphPlugin: Plugin = async (input) => {
     // -----------------------------------------------------------------
     // 1. System prompt: inject CPG project summary
     // -----------------------------------------------------------------
-    "experimental.chat.system.transform": async (_inp, output) => {
-      try {
-        const summary = await api.getProjectSummary(projectId)
-        if (summary) {
-          output.system.push(summary)
-        }
-      } catch {
-        // CodeGraph API not available — skip silently
-      }
-    },
+    "experimental.chat.system.transform": async (_inp, output) => {
+      try {
+        const rawStatus = await $`python -m src.cli.import_commands dogfood status --json`.quiet().text()
+        const statusSummary = formatDogfoodStatusSummary(JSON.parse(rawStatus))
+        if (statusSummary) {
+          output.system.push(statusSummary)
+        }
+      } catch {
+        // Dogfooding status unavailable — keep session startup lightweight
+      }
+
+      try {
+        const summary = await api.getProjectSummary(projectId)
+        if (summary) {
+          output.system.push(summary)
+        }
+      } catch {
+        // CodeGraph API not available — skip silently
+      }
+    },
 
     // -----------------------------------------------------------------
     // 2. Chat message: auto-enrich with CPG context for mentioned files
@@ -114,13 +129,35 @@ const codegraphPlugin: Plugin = async (input) => {
               codegraph_review_trace_recommendations:
                 traceSnapshot.review_recommendations?.slice(0, 3) || [],
               codegraph_review_trace_next_action: recommendedNextActionFromReviewTrace(traceSnapshot),
+              codegraph_review_trace_recommended_command:
+                traceSnapshot.recommended_command || recommendedCommandFromReviewTrace(traceSnapshot),
+              codegraph_review_trace_what_changed: whatChangedFromReviewTrace(traceSnapshot),
+              codegraph_review_trace_why_it_matters: whyItMattersFromReviewTrace(traceSnapshot),
+            }
+          } else {
+            traceSummary = formatPendingReviewTraceSummary(commit)
+            output.metadata = {
+              ...output.metadata,
+              codegraph_review_trace_status: "pending_or_missing",
+              codegraph_review_trace_phase: "awaiting_trace",
+              codegraph_review_trace_findings: null,
+              codegraph_review_trace_recommendations: [],
+              codegraph_review_trace_next_action:
+                "Wait briefly for review trace completion, then run /status to check the latest result.",
+              codegraph_review_trace_recommended_command: "/status",
+              codegraph_review_trace_what_changed: [
+                `Incremental CPG update was triggered for ${commit.slice(0, 12)}.`,
+                "Durable review trace is not available yet or has not been written.",
+              ],
+              codegraph_review_trace_why_it_matters:
+                "Post-commit findings and recommendations may still be pending, so the commit is not fully evaluated yet.",
             }
           }
         }
 
         // Notify user via output metadata (visible in OpenCode UI)
         output.title = traceSummary
-          ? "CodeGraph: CPG update triggered + review trace found"
+          ? "CodeGraph: post-commit review summary ready"
           : "CodeGraph: CPG update triggered"
         output.metadata = {
           ...output.metadata,

package/src/util.ts

@@ -14,6 +14,19 @@ export type ReviewTraceSnapshot = {
   review_severity_counts?: Record<string, number>
   review_recommendations?: string[]
   error?: string | null
+  recommended_command?: string
+}
+
+export type DogfoodStatusSnapshot = {
+  cpg_status?: {
+    is_fresh?: boolean
+    freshness_reason?: string
+    commits_behind?: number
+    db_exists?: boolean
+  }
+  head_commit?: string
+  review_trace?: ReviewTraceSnapshot | null
+  recommended_next_action?: string
 }
 
 /**
@@ -129,18 +142,68 @@ export async function readReviewTraceSnapshot(
   return null
 }
 
+export function formatPendingReviewTraceSummary(commit: string | null): string {
+  const commitLabel = commit ? ` for \`${commit.slice(0, 12)}\`` : ""
+  return [
+    "## CodeGraph Post-Commit Summary",
+    "",
+    "### What changed",
+    "",
+    `- Incremental CPG update was triggered${commitLabel}.`,
+    "- Durable review trace is not available yet or has not been written.",
+    "",
+    "### Why it matters",
+    "",
+    "- Post-commit findings and recommendations may still be pending, so the commit is not fully evaluated yet.",
+    "",
+    "### What to do now",
+    "",
+    "- Wait briefly for review trace completion, then run `/status` to check the latest result.",
+    "- Suggested command: `/status`",
+  ].join("\n")
+}
+
 export function formatReviewTraceSummary(snapshot: ReviewTraceSnapshot): string | null {
-  const status = snapshot.status || "unknown"
-  const phase = snapshot.phase || "unknown"
-  const findingsCount = snapshot.review_findings_count
   const recommendations = Array.isArray(snapshot.review_recommendations)
     ? snapshot.review_recommendations.filter(Boolean)
     : []
+  const whatChanged = whatChangedFromReviewTrace(snapshot)
+  const whyItMatters = whyItMattersFromReviewTrace(snapshot)
+  const nextAction = recommendedNextActionFromReviewTrace(snapshot)
+  const nextCommand = recommendedCommandFromReviewTrace(snapshot)
 
-  const lines = ["## CodeGraph Review Trace", "", `- Status: ${status}`, `- Phase: ${phase}`]
+  const lines = ["## CodeGraph Post-Commit Summary", ""]
 
-  if (typeof findingsCount === "number") {
-    lines.push(`- Findings: ${findingsCount}`)
+  if (whatChanged) {
+    lines.push("### What changed", "", ...whatChanged.map((item) => `- ${item}`), "")
+  }
+
+  if (whyItMatters) {
+    lines.push("### Why it matters", "", `- ${whyItMatters}`, "")
+  }
+
+  if (recommendations.length) {
+    lines.push("### Top recommendations", "")
+    for (const recommendation of recommendations.slice(0, 3)) {
+      lines.push(`- ${recommendation}`)
+    }
+    lines.push("")
+  }
+
+  lines.push("### What to do now", "", `- ${nextAction}`)
+  lines.push(`- Suggested command: \`${nextCommand}\``)
+
+  return lines.join("\n")
+}
+
+export function whatChangedFromReviewTrace(snapshot: ReviewTraceSnapshot): string[] {
+  const items: string[] = []
+  const status = snapshot.status || "unknown"
+  const phase = snapshot.phase || "unknown"
+  items.push(`Review trace status is ${status} (phase: ${phase}).`)
+
+  if (typeof snapshot.review_findings_count === "number") {
+    items.push(`CodeGraph reported ${snapshot.review_findings_count} review finding(s).`)
   }
 
   const severityCounts = snapshot.review_severity_counts || {}
@@ -149,26 +212,37 @@ export function formatReviewTraceSummary(snapshot: ReviewTraceSnapshot): string
     .map(([severity, count]) => `${severity}:${count}`)
     .join(", ")
   if (severitySummary) {
-    lines.push(`- Severity: ${severitySummary}`)
+    items.push(`Severity mix: ${severitySummary}.`)
   }
 
   if (snapshot.error) {
-    lines.push(`- Error: ${snapshot.error}`)
+    items.push(`Review trace recorded an error: ${snapshot.error}`)
   }
 
-  if (recommendations.length) {
-    lines.push("", "### Recommendations")
-    for (const recommendation of recommendations.slice(0, 3)) {
-      lines.push(`- ${recommendation}`)
-    }
-  }
+  return items
+}
 
-  const nextAction = recommendedNextActionFromReviewTrace(snapshot)
-  if (nextAction) {
-    lines.push("", `**Next action:** ${nextAction}`)
-  }
+export function whyItMattersFromReviewTrace(snapshot: ReviewTraceSnapshot): string {
+  const severityCounts = snapshot.review_severity_counts || {}
+  const high = severityCounts.high || 0
+  const medium = severityCounts.medium || 0
 
-  return lines.length > 2 ? lines.join("\n") : null
+  if (snapshot.error) {
+    return "The post-commit feedback loop is incomplete, so current review guidance may be missing or stale."
+  }
+  if ((snapshot.status || "").toLowerCase() === "running") {
+    return "The review trace is still running, so findings and recommendations can still change."
+  }
+  if (high > 0) {
+    return "High-severity findings were recorded, so the commit may need immediate follow-up before merge or push."
+  }
+  if (medium > 0) {
+    return "Medium-severity findings were recorded, so follow-up review is recommended before treating the commit as clean."
+  }
+  if (typeof snapshot.review_findings_count === "number" && snapshot.review_findings_count > 0) {
+    return "The review trace found issues worth checking, even if none were marked high severity."
+  }
+  return "No review findings were recorded, so the commit looks clean from the current trace perspective."
 }
 
 export function recommendedNextActionFromReviewTrace(snapshot: ReviewTraceSnapshot): string {
@@ -196,6 +270,59 @@ export function recommendedNextActionFromReviewTrace(snapshot: ReviewTraceSnapsh
   return "No review findings recorded; continue with /review or push once the rest of your checks are green."
 }
 
+export function recommendedCommandFromReviewTrace(snapshot: ReviewTraceSnapshot): string {
+  const status = (snapshot.status || "").toLowerCase()
+  const findingsCount = snapshot.review_findings_count
+
+  if (snapshot.error) {
+    return "/review"
+  }
+  if (status === "running") {
+    return "/status"
+  }
+  if (status && status !== "completed") {
+    return "/review"
+  }
+  if (typeof findingsCount === "number" && findingsCount > 0) {
+    return "/review"
+  }
+  return "/review"
+}
+
+export function formatDogfoodStatusSummary(snapshot: DogfoodStatusSnapshot): string | null {
+  const cpg = snapshot.cpg_status || {}
+  const isFresh = cpg.is_fresh
+  const freshnessReason = cpg.freshness_reason || "unknown"
+  const commitsBehind = cpg.commits_behind
+  const headCommit = snapshot.head_commit ? snapshot.head_commit.slice(0, 12) : null
+  const reviewTrace = snapshot.review_trace || null
+  const traceStatus = reviewTrace?.status || "missing"
+  const nextAction = snapshot.recommended_next_action
+  const nextCommand = (snapshot as { recommended_command?: string }).recommended_command
+
+  if (typeof isFresh === "undefined" && !headCommit && !nextAction) {
+    return null
+  }
+
+  const lines = ["## CodeGraph Dogfooding Status", ""]
+  if (typeof isFresh !== "undefined") {
+    const freshness = isFresh ? "fresh" : "stale"
+    const behind = typeof commitsBehind === "number" ? `, commits behind: ${commitsBehind}` : ""
+    lines.push(`- CPG freshness: ${freshness} (reason: ${freshnessReason}${behind})`)
+  }
+  if (headCommit) {
+    lines.push(`- HEAD: ${headCommit}`)
+  }
+  lines.push(`- Review trace: ${traceStatus}`)
+  if (nextAction) {
+    lines.push(`- Next action: ${nextAction}`)
+  }
+  if (nextCommand) {
+    lines.push(`- Suggested command: ${nextCommand}`)
+  }
+  return lines.join("\n")
+}
+
 // File extensions recognized as source code
 const SOURCE_EXTENSIONS = new Set([
   "py",