@cat-factory/app 0.28.0 → 0.28.1

package/app/components/requirements/RequirementsReviewWindow.vue

@@ -214,10 +214,24 @@ async function setStatus(item: RequirementReviewItem, itemStatus: ReviewItemStat
 const recommending = computed(() =>
   blockId.value ? requirements.isRecommending(blockId.value) : false,
 )
-// Recommendations still awaiting a human decision (the ones to surface for review).
-const pendingRecommendations = computed<RequirementRecommendation[]>(() =>
+// Recommendations the Writer has produced that still await a human decision (`ready`).
+const readyRecommendations = computed<RequirementRecommendation[]>(() =>
   (review.value?.recommendations ?? []).filter((r) => r.status === 'ready'),
 )
+// Placeholders the Requirement Writer is still producing in the background (`pending`).
+const generatingRecommendations = computed<RequirementRecommendation[]>(() =>
+  (review.value?.recommendations ?? []).filter((r) => r.status === 'pending'),
+)
+// "ready / total" progress for the in-flight batch (null when nothing is generating). Scoped to
+// the current wave via `createdAt` (all placeholders in one request share the timestamp), so
+// stale `ready` recommendations the human hasn't acted on from an earlier batch don't inflate it.
+const recommendationProgress = computed(() => {
+  const generating = generatingRecommendations.value
+  if (generating.length === 0) return null
+  const batchTimes = new Set(generating.map((r) => r.createdAt))
+  const ready = readyRecommendations.value.filter((r) => batchTimes.has(r.createdAt)).length
+  return { ready, total: ready + generating.length }
+})
 function isMarkedForRecommend(item: RequirementReviewItem): boolean {
   return markedForRecommend.value.has(item.id)
 }
@@ -228,18 +242,37 @@ function toggleRecommend(item: RequirementReviewItem) {
   markedForRecommend.value = next
 }
 
-// Fire the Writer over the whole marked batch at once (grounded on the project's
-// best-practice standards, specs/tech-specs and web search).
+// Fire the Writer over the whole marked batch (grounded on the project's best-practice
+// standards, specs/tech-specs and web search). ASYNCHRONOUS: it returns at once with `pending`
+// placeholders that fill in live; the user can close the window and is notified when the batch
+// is ready. Flush any typed-but-unblurred answers first so nothing the human entered is lost.
 async function requestRecommendations() {
   if (!blockId.value || markedForRecommend.value.size === 0) return
   const ids = [...markedForRecommend.value]
   try {
-    await requirements.requestRecommendations(blockId.value, ids)
+    await flushDrafts()
+    const updated = await requirements.requestRecommendations(blockId.value, ids)
     markedForRecommend.value = new Set()
-    toast.add({
-      title: `Requesting ${ids.length} recommendation${ids.length === 1 ? '' : 's'}…`,
-      icon: 'i-lucide-sparkles',
-    })
+    const n = ids.length
+    const plural = n === 1 ? '' : 's'
+    // On a parked run the request returns at once with `pending` placeholders the durable driver
+    // fills in the background; off-path (no active pipeline) there is no driver, so the Writer
+    // ran inline and the recommendations are already settled. Tell the human which actually
+    // happened rather than always promising a background callback.
+    const stillGenerating = (updated?.recommendations ?? []).some((r) => r.status === 'pending')
+    toast.add(
+      stillGenerating
+        ? {
+            title: `Preparing ${n} recommendation${plural} in the background`,
+            description:
+              "Your answers are saved — close this if you like; we'll notify you when they're ready.",
+            icon: 'i-lucide-sparkles',
+          }
+        : {
+            title: `${n} recommendation${plural} ready`,
+            icon: 'i-lucide-sparkles',
+          },
+    )
   } catch (e) {
     notifyError('Could not request recommendations', e)
   }
@@ -567,18 +600,47 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                 </div>
               </div>
 
-              <!-- Requirement-Writer recommendations awaiting a human decision -->
+              <!-- Requirement-Writer recommendations: awaiting a human decision (`ready`) and/or
+                   still generating in the background (`pending`) -->
               <section
-                v-if="pendingRecommendations.length"
+                v-if="readyRecommendations.length || generatingRecommendations.length"
                 class="mt-6 border-t border-slate-800 pt-5"
               >
-                <div class="mb-3 flex items-center gap-1.5 text-[11px] text-indigo-300">
+                <div class="mb-3 flex items-center gap-2 text-[11px] text-indigo-300">
                   <UIcon name="i-lucide-wand-2" class="h-3.5 w-3.5" />
                   <span class="font-semibold uppercase tracking-wide">Recommended answers</span>
+                  <span
+                    v-if="recommendationProgress"
+                    class="ml-auto flex items-center gap-1.5 normal-case text-indigo-300/80"
+                  >
+                    <UIcon name="i-lucide-loader-circle" class="h-3.5 w-3.5 animate-spin" />
+                    {{ recommendationProgress.ready }} / {{ recommendationProgress.total }} ready
+                  </span>
                 </div>
+
+                <!-- still-generating placeholders (one per requested finding) -->
+                <div v-if="generatingRecommendations.length" class="mb-3 flex flex-col gap-3">
+                  <div
+                    v-for="rec in generatingRecommendations"
+                    :key="rec.id"
+                    class="flex items-start gap-2 rounded-lg border border-dashed border-indigo-900/50 bg-indigo-950/10 p-3"
+                  >
+                    <UIcon
+                      name="i-lucide-loader-circle"
+                      class="mt-0.5 h-4 w-4 shrink-0 animate-spin text-indigo-300"
+                    />
+                    <div class="min-w-0">
+                      <span class="text-sm font-medium text-white">{{
+                        rec.sourceFinding.title
+                      }}</span>
+                      <p class="text-xs text-indigo-300/70">Generating a grounded suggestion…</p>
+                    </div>
+                  </div>
+                </div>
+
                 <div class="flex flex-col gap-3">
                   <div
-                    v-for="rec in pendingRecommendations"
+                    v-for="rec in readyRecommendations"
                     :key="rec.id"
                     class="rounded-lg border border-indigo-900/50 bg-indigo-950/20 p-3"
                   >

package/app/composables/api/reviews.ts

@@ -83,11 +83,17 @@ export function reviewsApi({ http, ws }: ApiContext) {
       ),
 
     // Ask the Requirement Writer to recommend grounded answers for a batch of findings (by
-    // item id). Returns the review with `ready` recommendations for the human to act on.
-    requestRecommendations: (workspaceId: string, blockId: string, itemIds: string[]) =>
+    // item id). Returns the review with `pending` placeholder recommendations; they fill in
+    // (`ready`) asynchronously via the `requirements` stream as the Writer produces each.
+    requestRecommendations: (
+      workspaceId: string,
+      blockId: string,
+      itemIds: string[],
+      note?: string,
+    ) =>
       http<RequirementReview | null>(
         `${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/requirement-review/recommend`,
-        { method: 'POST', body: { itemIds } },
+        { method: 'POST', body: { itemIds, ...(note ? { note } : {}) } },
       ),
 
     // Accept a recommendation (becomes the finding's answer), reject it, or re-request it

package/app/stores/requirements.ts

@@ -44,14 +44,21 @@ export const useRequirementsStore = defineStore('requirements', () => {
   function reviewFor(blockId: string): RequirementReview | null {
     return reviews.value[blockId] ?? null
   }
+  /** Whether the Requirement Writer is still producing recommendations for a block (a `pending`
+   * placeholder exists). Server-derived, so the "Recommending…" state survives the window closing
+   * and a page reload — the client-local `recommending` set only covers the request round-trip. */
+  function hasPendingRecommendations(blockId: string): boolean {
+    return (reviews.value[blockId]?.recommendations ?? []).some((r) => r.status === 'pending')
+  }
   /**
    * The async background stage a block's review is in, or null. While the driver folds the
-   * answers (`incorporating`) then re-reviews the document (`reviewing`), NO human action is
-   * needed — so the board suppresses the "Approval needed" gate and shows this working state
-   * instead, with copy that names which of the two stages is running.
+   * answers (`incorporating`) then re-reviews the document (`reviewing`), or the Requirement
+   * Writer is producing recommendations (`recommending`), NO human action is needed — so the
+   * board suppresses the "Approval needed" gate and shows this working state instead, with copy
+   * that names which stage is running.
    */
   function backgroundStage(blockId: string): 'incorporating' | 'reviewing' | 'recommending' | null {
-    if (recommending.value.has(blockId)) return 'recommending'
+    if (recommending.value.has(blockId) || hasPendingRecommendations(blockId)) return 'recommending'
     const status = reviews.value[blockId]?.status
     return status === 'incorporating' || status === 'reviewing' ? status : null
   }
@@ -176,19 +183,26 @@ export const useRequirementsStore = defineStore('requirements', () => {
   }
 
   function isRecommending(blockId: string): boolean {
-    return recommending.value.has(blockId)
+    return recommending.value.has(blockId) || hasPendingRecommendations(blockId)
   }
 
   /**
    * Ask the Requirement Writer to recommend answers for a batch of findings (by item id).
-   * Runs the Writer inline (grounded on best-practice fragments → spec/tech-spec → web) and
-   * returns the review with `ready` recommendations to accept/reject. Shows a `recommending`
-   * background stage on the board while it runs.
+   * ASYNCHRONOUS: returns at once with `pending` placeholder recommendations (the Writer runs
+   * per finding in the durable driver), which fill in (`ready`) via live `requirements` stream
+   * events; a notification calls the user back when the batch is ready. The board shows the
+   * `recommending` background stage while any placeholder is pending. Optional `note` steers the
+   * whole batch.
    */
-  async function requestRecommendations(blockId: string, itemIds: string[]) {
+  async function requestRecommendations(blockId: string, itemIds: string[], note?: string) {
     withFlag(recommending, blockId, true)
     try {
-      const updated = await api.requestRecommendations(workspace.requireId(), blockId, itemIds)
+      const updated = await api.requestRecommendations(
+        workspace.requireId(),
+        blockId,
+        itemIds,
+        note,
+      )
       if (updated) store(updated)
       return updated
     } finally {

package/app/types/requirements.ts

@@ -50,8 +50,12 @@ export type RequirementReviewStatus =
 /** How a human resolves a review that hit its iteration cap. */
 export type ResolveRequirementsExceededChoice = 'extra-round' | 'proceed' | 'stop-reset'
 
-/** Lifecycle of a Requirement-Writer recommendation. */
-export type RecommendationStatus = 'ready' | 'accepted' | 'rejected'
+/**
+ * Lifecycle of a Requirement-Writer recommendation. `pending` is a placeholder created the
+ * moment the human requests it — the Writer is still producing the suggestion in the background
+ * (the async story); it fills in to `ready` via the `requirements` stream.
+ */
+export type RecommendationStatus = 'pending' | 'ready' | 'accepted' | 'rejected'
 
 /**
  * A Requirement-Writer suggestion for one finding. First-class on the review (survives the
@@ -60,7 +64,7 @@ export type RecommendationStatus = 'ready' | 'accepted' | 'rejected'
  */
 export interface RequirementRecommendation {
   id: string
-  sourceFinding: { title: string; detail: string }
+  sourceFinding: { title: string; detail: string; itemId?: string }
   recommendedText: string
   status: RecommendationStatus
   note: string | null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",