opencode-codegraph 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.8 - 2026-03-20
+
+- add normalized workflow states (`refresh_needed`, `trace_pending`, `review_required`, `ready_to_continue`) across dogfooding status and review trace flows
+- surface a recommended command alongside next-action guidance in session-start, status, and post-commit summaries
+- align `/review`, `/audit`, and `/update` around the same status-derived command guidance
+
+## 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

package/README.md

@@ -39,9 +39,14 @@ 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.
+- a normalized workflow state so the session can distinguish `refresh_needed`, `trace_pending`, `review_required`, and `ready_to_continue`.
 
 ### Post-Commit Updates
 
@@ -51,6 +56,8 @@ After `git commit`, the plugin triggers incremental CPG re-parsing via GoCPG and
 - why it matters
 - top recommendations
 - one clear next action
+- one suggested command to run next
+- one normalized workflow state
 
 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.
 

package/package.json

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

package/src/index.ts

@@ -17,13 +17,16 @@ import { CodeGraphAPI } from "./api"
 import {
   extractFileRefs,
   fileNeedsRegistrationCheck,
+  formatDogfoodStatusSummary,
   formatPendingReviewTraceSummary,
   formatReviewTraceSummary,
   getHeadCommit,
   isGitCommit,
   messageSuggestsEditing,
+  recommendedCommandFromReviewTrace,
   recommendedNextActionFromReviewTrace,
   readReviewTraceSnapshot,
+  workflowStateFromReviewTrace,
   whatChangedFromReviewTrace,
   whyItMattersFromReviewTrace,
 } from "./util"
@@ -42,16 +45,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
@@ -112,11 +125,15 @@ const codegraphPlugin: Plugin = async (input) => {
             output.metadata = {
               ...output.metadata,
               codegraph_review_trace_status: traceSnapshot.status || "unknown",
+              codegraph_review_trace_workflow_state:
+                traceSnapshot.workflow_state || workflowStateFromReviewTrace(traceSnapshot),
               codegraph_review_trace_phase: traceSnapshot.phase || "unknown",
               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_recommended_command:
+                traceSnapshot.recommended_command || recommendedCommandFromReviewTrace(traceSnapshot),
               codegraph_review_trace_what_changed: whatChangedFromReviewTrace(traceSnapshot),
               codegraph_review_trace_why_it_matters: whyItMattersFromReviewTrace(traceSnapshot),
             }
@@ -125,11 +142,13 @@ const codegraphPlugin: Plugin = async (input) => {
             output.metadata = {
               ...output.metadata,
               codegraph_review_trace_status: "pending_or_missing",
+              codegraph_review_trace_workflow_state: "trace_pending",
               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.",

package/src/util.ts

@@ -14,6 +14,22 @@ export type ReviewTraceSnapshot = {
   review_severity_counts?: Record<string, number>
   review_recommendations?: string[]
   error?: string | null
+  workflow_state?: string
+  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
+  workflow_state?: string
+  recommended_next_action?: string
+  recommended_command?: string
 }
 
 /**
@@ -146,6 +162,8 @@ export function formatPendingReviewTraceSummary(commit: string | null): string {
     "### What to do now",
     "",
     "- Wait briefly for review trace completion, then run `/status` to check the latest result.",
+    "- Suggested command: `/status`",
+    "- Workflow state: `trace_pending`",
   ].join("\n")
 }
 
@@ -156,6 +174,8 @@ export function formatReviewTraceSummary(snapshot: ReviewTraceSnapshot): string
   const whatChanged = whatChangedFromReviewTrace(snapshot)
   const whyItMatters = whyItMattersFromReviewTrace(snapshot)
   const nextAction = recommendedNextActionFromReviewTrace(snapshot)
+  const nextCommand = recommendedCommandFromReviewTrace(snapshot)
+  const workflowState = workflowStateFromReviewTrace(snapshot)
 
   const lines = ["## CodeGraph Post-Commit Summary", ""]
 
@@ -176,6 +196,8 @@ export function formatReviewTraceSummary(snapshot: ReviewTraceSnapshot): string
   }
 
   lines.push("### What to do now", "", `- ${nextAction}`)
+  lines.push(`- Suggested command: \`${nextCommand}\``)
+  lines.push(`- Workflow state: \`${workflowState}\``)
 
   return lines.join("\n")
 }
@@ -236,12 +258,12 @@ export function recommendedNextActionFromReviewTrace(snapshot: ReviewTraceSnapsh
     ? snapshot.review_recommendations.filter(Boolean)
     : []
 
+  if (workflowStateFromReviewTrace(snapshot) === "trace_pending") {
+    return "Wait for review trace completion, then inspect findings and recommendations."
+  }
   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."
   }
@@ -254,6 +276,83 @@ 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
+  const workflowState = workflowStateFromReviewTrace(snapshot)
+
+  if (workflowState === "trace_pending") {
+    return "/status"
+  }
+  if (snapshot.error) {
+    return "/review"
+  }
+  if (status && status !== "completed") {
+    return "/review"
+  }
+  if (typeof findingsCount === "number" && findingsCount > 0) {
+    return "/review"
+  }
+  return "/review"
+}
+
+export function workflowStateFromReviewTrace(snapshot: ReviewTraceSnapshot): string {
+  const status = (snapshot.status || "").toLowerCase()
+  const findingsCount = snapshot.review_findings_count
+
+  if (snapshot.error) {
+    return "review_required"
+  }
+  if (status === "running" || status === "pending_or_missing") {
+    return "trace_pending"
+  }
+  if (status && status !== "completed") {
+    return "review_required"
+  }
+  if (typeof findingsCount === "number" && findingsCount > 0) {
+    return "review_required"
+  }
+  return "ready_to_continue"
+}
+
+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 workflowState = snapshot.workflow_state
+  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 (workflowState) {
+    lines.push(`- Workflow state: ${workflowState}`)
+  }
+  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",