opencode-codegraph 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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
+- surface next-action guidance in post-commit OpenCode plugin metadata and review-trace summaries
+- document the next-action workflow in plugin and integration docs
+
 ## 0.1.4 - 2026-03-20
 
 - add conversational pre-edit guidance when a chat message suggests code modification

package/README.md

@@ -45,7 +45,19 @@ Every conversation includes a project summary with file count, top complexity ho
 
 ### 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 and recommendations.
+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
+
+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 +101,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 |
+| `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,16 +1,16 @@
 {
   "name": "opencode-codegraph",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "OpenCode plugin for CodeGraph CPG-powered code analysis",
   "type": "module",
   "main": "src/index.ts",
   "exports": {
     ".": "./src/index.ts"
   },
-  "files": [
-    "src",
-    "CHANGELOG.md"
-  ],
+  "files": [
+    "src",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsc"

package/src/index.ts

@@ -17,11 +17,15 @@ import { CodeGraphAPI } from "./api"
 import {
   extractFileRefs,
   fileNeedsRegistrationCheck,
+  formatPendingReviewTraceSummary,
   formatReviewTraceSummary,
   getHeadCommit,
   isGitCommit,
   messageSuggestsEditing,
+  recommendedNextActionFromReviewTrace,
   readReviewTraceSnapshot,
+  whatChangedFromReviewTrace,
+  whyItMattersFromReviewTrace,
 } from "./util"
 
 const codegraphPlugin: Plugin = async (input) => {
@@ -112,13 +116,33 @@ const codegraphPlugin: Plugin = async (input) => {
               codegraph_review_trace_findings: traceSnapshot.review_findings_count ?? null,
               codegraph_review_trace_recommendations:
                 traceSnapshot.review_recommendations?.slice(0, 3) || [],
+              codegraph_review_trace_next_action: recommendedNextActionFromReviewTrace(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_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

@@ -129,18 +129,65 @@ 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.",
+  ].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 lines = ["## CodeGraph Post-Commit Summary", ""]
 
-  const lines = ["## CodeGraph Review Trace", "", `- Status: ${status}`, `- Phase: ${phase}`]
+  if (whatChanged) {
+    lines.push("### What changed", "", ...whatChanged.map((item) => `- ${item}`), "")
+  }
 
-  if (typeof findingsCount === "number") {
-    lines.push(`- Findings: ${findingsCount}`)
+  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}`)
+
+  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,21 +196,62 @@ 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
+}
+
+export function whyItMattersFromReviewTrace(snapshot: ReviewTraceSnapshot): string {
+  const severityCounts = snapshot.review_severity_counts || {}
+  const high = severityCounts.high || 0
+  const medium = severityCounts.medium || 0
+
+  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."
+}
 
-  return lines.length > 2 ? lines.join("\n") : null
+export function recommendedNextActionFromReviewTrace(snapshot: ReviewTraceSnapshot): string {
+  const status = (snapshot.status || "").toLowerCase()
+  const findingsCount = snapshot.review_findings_count
+  const recommendations = Array.isArray(snapshot.review_recommendations)
+    ? snapshot.review_recommendations.filter(Boolean)
+    : []
+
+  if (snapshot.error) {
+    return "Investigate the review-trace error, then run /review once the pipeline is healthy."
+  }
+  if (status === "running") {
+    return "Wait for review trace completion, then inspect findings and recommendations."
+  }
+  if (status && status !== "completed") {
+    return "Check the latest review trace status again and rerun /review if the result is incomplete."
+  }
+  if (typeof findingsCount === "number" && findingsCount > 0) {
+    if (recommendations.length) {
+      return "Apply the top CodeGraph recommendations, then run /review to confirm the fixes."
+    }
+    return "Inspect the reported findings, fix the highest-risk issues, then run /review again."
+  }
+  return "No review findings recorded; continue with /review or push once the rest of your checks are green."
 }
 
 // File extensions recognized as source code