opencode-plugin-flow 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 One short entry per release, written for users deciding whether to upgrade.
 
+## [8.1.0] - 2026-08-19
+
+Inspect surveys can finish with blockers, and `/flow-auto` hands back a findings list.
+
+- Compact `flow_status` and close delivery now carry a derived `findingsDigest`
+  over every identified finding across attempts. `/flow-auto` prints that list
+  when it parks or stops instead of going silent after a blocked review.
+- **Session v5 schema:** `PlanFeature.kind` is optional `change` or `inspect`.
+  Absent is `change`. A failed inspect review completes that slice so later
+  features can start without `flow_feature_reset`. `completed` then means the
+  survey finished, not that the tree is clean. Existing documents keep the
+  repair loop.
+
+Install or update:
+
+```bash
+opencode plugin opencode-plugin-flow@8.1.0 --global --force
+```
+
 ## [8.0.0] - 2026-08-18
 
 One evidence record, a thinner run loop, and a freeze on further declarations.

package/README.md

@@ -40,7 +40,7 @@ expensive, and it is overhead when it is not.
 Install the exact npm release through OpenCode:
 
 ```bash
-opencode plugin opencode-plugin-flow@8.0.0 --global --force
+opencode plugin opencode-plugin-flow@8.1.0 --global --force
 ```
 
 Omit `--global` for project scope. Version pins are exact and never update on
@@ -51,7 +51,7 @@ The equivalent manual project configuration is:
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-plugin-flow@8.0.0"]
+  "plugin": ["opencode-plugin-flow@8.1.0"]
 }
 ```
 

package/dist/index.js

@@ -109,7 +109,8 @@ If a Flow tool is absent, report an incomplete plugin load; never simulate state
 ## Recovery
 
 On interruption, read compact status; load \`flow-run\` for an active or blocked feature
-and use execution or reviewer status, never prose, for lifecycle truth.
+and use execution or reviewer status, never prose, for lifecycle truth. At a
+checkpoint or lease stop, print compact \`findingsDigest\` before any delivery map.
 
 Summaries keep plan/source IDs \`verified\` or \`incomplete\`. A prior finding is
 terminally \`fixed\` only when review passes with current evidence. A failed
@@ -198,7 +199,8 @@ Save one plan with:
   gate is the command every broad observation must run; a failed or
   claimed-broad gate still vetoes review.
 - \`features\`: ordered outcome slices, each with a stable \`id\`, \`title\`,
-  \`summary\`, bounded \`targets\`, concrete \`validation\`, and \`dependsOn\` ids.
+  \`summary\`, bounded \`targets\`, concrete \`validation\`, \`dependsOn\` ids, and
+  optional \`kind\`.
 
 Each feature needs one observable outcome judgeable from bounded evidence and
 focused validation. Split only independent failures or true dependencies; file
@@ -213,6 +215,13 @@ outcome and its evidence.
 A \`validation\` entry naming a command is recorded byte-for-byte; prose there stays
 reviewer judgment, never a fabricated result.
 
+If the request is inspect-only (review, audit, survey, no promised edit), invent
+no repair features. Save at most a small set of inspect features with
+\`kind: "inspect"\`, whose \`validation\` is reviewer inspection, whose \`targets\`
+are existing paths, and whose \`decisions\` state that no source edit is
+authorized. The gate may be the repo's existing check. Ask before turning an
+inspect request into repairs.
+
 Before saving, confirm:
 
 - every requirement maps to a feature or an explicit non-goal;
@@ -277,17 +286,15 @@ the manager's summary. Check that:
 - changed behavior is correct at public and downstream call sites;
 - validation is strong enough for the behavior and main failure modes;
 - scope did not drift and unrelated user work was preserved;
-- relevant adjacent states, failure/cleanup ordering, repetition, retry,
-  interruption, reentrancy, concurrency, and overlapping invariants still work;
 - the feature's actual base diff includes no unexplained deletion, rename, file
   type, generated artifact, or executable/file-mode change; and
 - persistence, concurrency, security, migration, compatibility, package, UI,
   and recovery risks were examined when relevant.
 
-Finish the supplied feature-specific risk checklist, represented by a bounded
-matrix for concurrency or state-machine work. Continue that matrix after finding
-one blocker so independently detectable interleavings arrive in the same review
-cohort.
+Finish the supplied feature-specific risk checklist. Continue a concurrency or
+state-machine matrix after one blocker only when \`assignment.packet.riskLenses\`
+is non-empty or the packet summary includes a matrix. Otherwise inspect the
+changed artifacts, the supplied validation, and live \`priorFindings\`.
 
 Scope plan/source IDs by assignment kind. An ordinary feature review records
 dispositions only for IDs mapped to the active feature or explicitly supplied
@@ -311,8 +318,8 @@ not a failure; a missing or conflicting baseline fact, or a material mode,
 platform, race, or failure-path claim without proof, is.
 
 Flow deliberately projects no raw command output; use the durable command, exit
-code, completeness, digest, source binding, and your workspace inspection. A weak or
-unclear coverage claim is an evidence gap.
+code, completeness, digest, source binding, and your workspace inspection. A weak
+coverage claim is an evidence gap.
 
 For a final assignment, also inspect broad validation and confirm docs,
 commands, package surfaces, and remaining gaps are consistent with completion.
@@ -326,8 +333,8 @@ IDs in summary or evidence.
 
 Report every problem you find. Severity is a routing decision the runtime acts
 on, not a filter on what to mention: \`blocking\` when the issue invalidates the
-approved outcome, \`advisory\` otherwise. When you are unsure, report it as
-\`advisory\` rather than omitting it.
+approved outcome, \`advisory\` otherwise. If unsure, report it as
+\`advisory\` rather than omitting it. Inspect kind completes with blockers.
 
 Set \`scopeBlocker: true\` on a blocking finding whose repair requires material
 work outside the approved plan, and identify the boundary in \`evidence\`. The
@@ -515,7 +522,8 @@ feature.
 
 ### Blocked review
 
-Follow \`nextAction\` with the one detail projection. The runtime already weighs
+Follow \`nextAction\` with the one detail projection for routing, then print
+compact \`findingsDigest\` as the user-facing list. The runtime already weighs
 \`failedReviewCount\` and \`blockedFeature.scopeBlocker\`.
 
 - Ready \`await-user-direction\` has no blocked run left to reset. Identify the
@@ -534,8 +542,8 @@ Follow \`nextAction\` with the one detail projection. The runtime already weighs
   feature, pass that exact \`featureId\` as \`nextFeatureId\` on
   \`flow_feature_reset\`.
 
-Direct \`/flow-run\` reports this one feature's cumulative outcome and
-\`nextAction\`, then stops. Under \`/flow-auto\`, return to its lifecycle loop.
+Direct \`/flow-run\` reports compact \`findingsDigest\` and \`nextAction\`, then
+stops. Under \`/flow-auto\`, return to its lifecycle loop.
 `;
 
 // src/guidance/ids.ts
@@ -560,7 +568,9 @@ var FLOW_MANAGER_KERNEL = [
   ].join(" "),
   [
     "- Make one automatic fresh full retry only when the projected `nextAction`",
-    "is `flow_feature_reset`; otherwise checkpoint."
+    "is `flow_feature_reset`; otherwise checkpoint.",
+    "On `await-user-direction` or a lease stop, print compact `findingsDigest`",
+    "without inventing ids."
   ].join(" "),
   [
     "- Before review, require current-source evidence appropriate to the changed outcome,",
@@ -972,6 +982,9 @@ function planEvidence(plan) {
 function planGate(plan) {
   return planEvidence(plan).find((entry) => entry.scope === "gate")?.command;
 }
+function featureKind(feature) {
+  return feature?.kind === "inspect" ? "inspect" : "change";
+}
 function reviewResultSemanticIssues(result) {
   const issues = [];
   const blocking = result.findings.some((finding) => finding.severity === "blocking");
@@ -1713,6 +1726,7 @@ function completeFeature(session, input) {
     }
   }
   const findings = assignFindingIds(input.result.findings, findingIdPrefix(run.featureId, assignment.createdRevision));
+  const inspect = featureKind(session.plan?.features.find((feature) => feature.id === run.featureId)) === "inspect";
   const next = commit(session, "feature-complete", input.operationId, input, (draft, revision) => ({
     ...draft,
     runs: draft.runs.map((item) => {
@@ -1720,7 +1734,7 @@ function completeFeature(session, input) {
         return item;
       return {
         ...item,
-        state: input.result.verdict === "passed" ? "completed" : "blocked",
+        state: input.result.verdict === "passed" || inspect ? "completed" : "blocked",
         summary: input.summary,
         reviews: item.reviews.map((review) => review.id === assignment.id ? {
           ...review,
@@ -1815,7 +1829,7 @@ function closeSession(session, input) {
     fail("sessionId does not match active state.");
   assertMutable(session);
   if (input.kind === "completed" && sessionStatus(session) !== "completed") {
-    fail("A completed close requires every planned feature to pass review.");
+    fail("A completed close requires every planned feature to be complete.");
   }
   if (input.kind === "completed") {
     const unsatisfied = unsatisfiedExtraEvidence(session);
@@ -1875,8 +1889,14 @@ class ArchiveCollisionError extends Error {
 import { z } from "zod";
 
 // src/domain/session-invariants.ts
-function featurePassedBefore(session, featureId, revision) {
-  return session.runs.some((run) => run.featureId === featureId && run.reviews.some((review) => review.result?.verdict === "passed" && review.result.recordedRevision < revision));
+function featureSettledBefore(session, featureId, revision) {
+  const inspect = featureKind(session.plan?.features.find((feature) => feature.id === featureId)) === "inspect";
+  return session.runs.some((run) => run.featureId === featureId && run.reviews.some((review) => {
+    const result = review.result;
+    if (!result || result.recordedRevision >= revision)
+      return false;
+    return result.verdict === "passed" || inspect;
+  }));
 }
 function sessionInvariantIssues(session) {
   const issues = [];
@@ -1993,7 +2013,7 @@ function sessionInvariantIssues(session) {
       if (referenced.some((validation) => validation.recordedRevision >= review.createdRevision)) {
         issues.push(`Review '${review.id}' references later validation.`);
       }
-      const expectedKind = session.plan.features.every((feature) => feature.id === run.featureId || featurePassedBefore(session, feature.id, review.createdRevision)) ? "final" : "feature";
+      const expectedKind = session.plan.features.every((feature) => feature.id === run.featureId || featureSettledBefore(session, feature.id, review.createdRevision)) ? "final" : "feature";
       if (review.kind !== expectedKind) {
         issues.push(`Review '${review.id}' has the wrong derived kind.`);
       }
@@ -2011,7 +2031,10 @@ function sessionInvariantIssues(session) {
       issues.push(`Active run '${run.id}' contains a recorded outcome.`);
     }
     if (run.state === "completed" && last?.result?.verdict !== "passed") {
-      issues.push(`Completed run '${run.id}' lacks a passing review.`);
+      const inspect = featureKind(session.plan?.features.find((feature) => feature.id === run.featureId)) === "inspect";
+      if (!(inspect && last?.result?.verdict === "failed")) {
+        issues.push(`Completed run '${run.id}' lacks a passing review.`);
+      }
     }
     if (run.state === "blocked" && last?.result?.verdict !== "failed") {
       issues.push(`Blocked run '${run.id}' lacks a failed review.`);
@@ -2050,7 +2073,8 @@ var PlanFeatureSchema = z.object({
   summary: boundedText("Feature summary"),
   targets: z.array(boundedText("Feature target")).max(MAX_PLAN_FEATURES).default([]),
   validation: z.array(boundedText("Feature validation")).max(MAX_PLAN_FEATURES).default([]),
-  dependsOn: z.array(FeatureIdSchema).max(MAX_PLAN_FEATURES).default([])
+  dependsOn: z.array(FeatureIdSchema).max(MAX_PLAN_FEATURES).default([]),
+  kind: z.enum(["change", "inspect"]).optional()
 }).strict();
 var EvidenceEntrySchema = z.object({
   requirement: boundedText("Evidence requirement"),
@@ -2260,6 +2284,69 @@ var StatusInputSchema = z.object({
   ])
 }).strict();
 
+// src/application/findings-digest.ts
+function plannedFeatureIds(session) {
+  if (session.plan)
+    return session.plan.features.map((feature) => feature.id);
+  const ids = [];
+  for (const run of session.runs) {
+    if (ids.includes(run.featureId))
+      continue;
+    ids.push(run.featureId);
+  }
+  return ids;
+}
+function findingsDigest(session) {
+  const rows = [];
+  const indexById = new Map;
+  for (const featureId of plannedFeatureIds(session)) {
+    for (const run of session.runs) {
+      if (run.featureId !== featureId)
+        continue;
+      for (const review of run.reviews) {
+        const result = review.result;
+        if (!result)
+          continue;
+        for (const finding of result.findings) {
+          if (!finding.findingId)
+            continue;
+          const row = {
+            featureId,
+            findingId: finding.findingId,
+            severity: finding.severity,
+            summary: finding.summary,
+            attempt: run.attempt,
+            verdict: result.verdict,
+            live: false,
+            ...finding.evidence === undefined ? {} : { evidence: finding.evidence }
+          };
+          const existing = indexById.get(finding.findingId);
+          if (existing === undefined) {
+            indexById.set(finding.findingId, rows.length);
+            rows.push(row);
+          } else {
+            rows[existing] = row;
+          }
+        }
+      }
+    }
+  }
+  return rows.map((row) => ({
+    ...row,
+    live: liveFindingIds(session, row.featureId).includes(row.findingId)
+  }));
+}
+function digestReportLines(digest) {
+  if (digest.length === 0)
+    return ["Findings digest: none"];
+  const line = (row, kind) => `- ${kind} ${row.featureId} ${row.findingId} ${row.severity}: ${row.summary}`;
+  return [
+    "Findings digest:",
+    ...digest.filter((row) => row.live).map((row) => line(row, "live")),
+    ...digest.filter((row) => !row.live).map((row) => line(row, "historical"))
+  ];
+}
+
 // src/application/delivery.ts
 var LIMITATIONS = [
   "Artifact paths and the canonical gate are caller declarations; Flow validates binding, not completeness or fitness.",
@@ -2340,6 +2427,7 @@ function formatReport(delivery) {
     `Progress: ${delivery.progress.completed} of ${delivery.progress.total} features complete`,
     "Features:",
     ...lines,
+    ...digestReportLines(delivery.findingsDigest),
     `Assurance: ${delivery.assurance.conclusion.replaceAll("-", " ")}`,
     "Assurance checks:",
     ...delivery.assurance.checks.map((item) => `- ${item.status} [${TIER_LABELS[item.tier]}] ${item.label}: ${item.explanation}`),
@@ -2361,6 +2449,7 @@ function deliveryProjection(session) {
   const latest = grouped.flatMap(({ runs }) => runs.slice(-1));
   const latestArtifacts = new Set(latest.flatMap((run) => run.artifactsChanged.map((item) => item.path)));
   const allArtifacts = new Set(session.runs.flatMap((run) => run.artifactsChanged.map((item) => item.path)));
+  const digest = findingsDigest(session);
   const delivery = {
     goal: session.goal,
     closure: { kind: session.closure.kind, summary: session.closure.summary },
@@ -2376,17 +2465,15 @@ function deliveryProjection(session) {
         attempts: runs.length,
         latestState: run?.state ?? "not-started",
         outcomeSummary: run?.summary ?? null,
-        terminalFindings: run?.reviews.at(-1)?.result?.findings.map(({ severity, summary }) => ({
-          severity,
-          summary
-        })) ?? []
+        terminalFindings: digest.filter((row) => row.featureId === feature.id && row.live).map(({ severity, summary }) => ({ severity, summary }))
       };
     }),
     reportedArtifacts: {
       latestAttempts: [...latestArtifacts].sort(),
       supersededAttemptsOnly: [...allArtifacts].filter((path) => !latestArtifacts.has(path)).sort()
     },
-    assurance: assuranceProjection(session)
+    assurance: assuranceProjection(session),
+    findingsDigest: digest
   };
   return { ...delivery, report: formatReport(delivery) };
 }
@@ -2462,7 +2549,8 @@ function compactProjection(session, pendingReviewSourceStale = false) {
     blockedFeature,
     progress: featureProgress(session),
     nextAction: nextAction(session, pendingReviewSourceStale, blockedFeature),
-    archiveRetry: retryRequest ? { request: retryRequest } : null
+    archiveRetry: retryRequest ? { request: retryRequest } : null,
+    findingsDigest: findingsDigest(session)
   };
 }
 function archivedProjection(session) {
@@ -2550,7 +2638,8 @@ function idleProjection(view) {
     view,
     status: "idle",
     revision: 0,
-    nextAction: "flow_plan_save"
+    nextAction: "flow_plan_save",
+    findingsDigest: []
   };
 }
 function project(session, request, pendingReviewSourceStale = false) {
@@ -3801,6 +3890,10 @@ var CONTINUATION_ROUTE = [
   "for a fresh close use compact session id/revision plus a fresh operation id,",
   "and replay archiveRetry exactly from its projected request."
 ].join(" ");
+var HANDBACK_ROUTE = [
+  "Call flow_status with the compact view first.",
+  "Print findingsDigest as the user-facing list. Do not invent ids."
+].join(" ");
 function inspectMessage(parts) {
   let token = null;
   let text = "";
@@ -3826,6 +3919,9 @@ function isCheckpoint(projection) {
 function isPendingReviewer(projection) {
   return projection.status === "running" && projection.nextAction === "dispatch-flow-reviewer";
 }
+function isHandback(projection) {
+  return projection.status === "blocked" || projection.nextAction === "flow_feature_reset" || projection.nextAction === "dispatch-flow-reviewer";
+}
 
 class AutoDriveCoordinator {
   #lease = null;
@@ -3875,6 +3971,31 @@ class AutoDriveCoordinator {
     lease.lastPromptedRevision = null;
     this.#setTiming("waiting-for-user");
   }
+  async#promptHandback(lease, projection) {
+    if (!isHandback(projection))
+      return;
+    if (lease.handbackPromptedRevision === projection.revision)
+      return;
+    if (!lease.delivery)
+      return;
+    lease.handbackPromptedRevision = projection.revision;
+    lease.messageId = null;
+    this.#setTiming("active");
+    lease.inFlight = "prompt";
+    try {
+      const handback = [
+        `Flow is handing control back at compact revision ${projection.revision}.`,
+        HANDBACK_ROUTE,
+        `Then follow ${projection.nextAction} or stop at await-user-direction.`,
+        "Do not expand the approved goal."
+      ].join(" ");
+      await this.#options.prompt(lease.hostSessionId, `${handback}
+
+${FLOW_MANAGER_KERNEL}`, lease.delivery, { [FLOW_AUTO_METADATA_KEY]: lease.token });
+    } catch (error) {
+      this.#stop(lease, `Flow auto prompt failed: ${String(error)}`);
+    }
+  }
   async#read(lease) {
     try {
       return await this.#options.readProjection();
@@ -3897,6 +4018,7 @@ class AutoDriveCoordinator {
       baseline: null,
       delivery: null,
       lastPromptedRevision: null,
+      handbackPromptedRevision: null,
       checkpoint: null,
       pendingReply: false,
       inFlight: null,
@@ -4093,8 +4215,12 @@ ${FLOW_MANAGER_KERNEL}`;
       const mutationAdvanced = advance !== undefined && projection.revision === advance && isMechanical(projection);
       if (lease.pendingReply) {
         lease.pendingReply = false;
-        if (boundary && (!checkpoint || projection.revision > checkpoint.revision))
+        if (boundary && (!checkpoint || projection.revision > checkpoint.revision)) {
+          await this.#promptHandback(lease, projection);
+          if (this.#lease !== lease)
+            return;
           return void this.#waitAt(lease, projection.revision);
+        }
         if (!checkpoint || !boundary && !mutationAdvanced)
           return void this.deactivate(hostSessionId);
         checkpoint.answered = true;
@@ -4104,15 +4230,27 @@ ${FLOW_MANAGER_KERNEL}`;
       if (boundary) {
         if (checkpoint && projection.revision < checkpoint.revision)
           return void this.deactivate(hostSessionId);
+        await this.#promptHandback(lease, projection);
+        if (this.#lease !== lease)
+          return;
         return void this.#waitAt(lease, projection.revision);
       }
+      if (!isMechanical(projection)) {
+        const already = lease.handbackPromptedRevision === projection.revision;
+        await this.#promptHandback(lease, projection);
+        if (this.#lease !== lease)
+          return;
+        if (!already && lease.handbackPromptedRevision === projection.revision) {
+          this.#setTiming("paused");
+          return;
+        }
+        return void this.deactivate(hostSessionId);
+      }
       if (checkpoint) {
         if (projection.revision <= checkpoint.revision || !mutationAdvanced)
           return void this.deactivate(hostSessionId);
         lease.checkpoint = null;
       }
-      if (!isMechanical(projection))
-        return void this.deactivate(hostSessionId);
       if (lease.lastPromptedRevision === projection.revision) {
         this.#setTiming("paused");
         return this.#warn(`Flow auto-drive paused after revision ${projection.revision} made no lifecycle progress.`);
@@ -4380,7 +4518,8 @@ var planFeature = host.object({
   summary: text,
   targets: host.array(text).max(MAX_PLAN_FEATURES).default([]),
   validation: host.array(text).max(MAX_PLAN_FEATURES).default([]),
-  dependsOn: host.array(featureId).max(MAX_PLAN_FEATURES).default([])
+  dependsOn: host.array(featureId).max(MAX_PLAN_FEATURES).default([]),
+  kind: host.enum(["change", "inspect"]).optional()
 }).strict();
 var plan = host.object({
   summary: text,
@@ -5023,4 +5162,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=84B9887B14A5141164756E2164756E21
+//# debugId=4CB19287BD614D3B64756E2164756E21