feat(schema): card narrative fields

scripts/setup-remote.ts

@@ -223,6 +223,46 @@ async function ensureCommitSummaryFields(pb: PocketBase): Promise<void> {
   }
 }
 
+/**
+ * Add the `narrative`, `narrative_version`, `narrative_shas` fields to cards.
+ *
+ * `narrative` is the AI-generated client-facing progress update. `narrative_shas`
+ * is the set fingerprint (see shaFingerprint in src/lib/ai/narrative.ts) of
+ * the linked commits that produced it, so the service can detect when the
+ * commit set changes and re-generate rather than overwriting fresh text with
+ * stale text. `narrative_version` is the prompt version, same idea as
+ * commit summary_version.
+ *
+ * Re-runs are safe: fields are not duplicated.
+ */
+async function ensureCardNarrativeFields(pb: PocketBase): Promise<void> {
+  const cards = await pb.collections.getOne("cards");
+  const have = new Set(cards.fields.map((f: { name: string }) => f.name));
+
+  const additions = [
+    { name: "narrative", type: "text", required: false, max: 8000 },
+    { name: "narrative_version", type: "number", required: false, onlyInt: true },
+    { name: "narrative_shas", type: "text", required: false, max: 20000 },
+  ];
+
+  const fields = [...(cards.fields as unknown[])];
+  let changed = false;
+
+  for (const field of additions) {
+    if (!have.has(field.name)) {
+      fields.push({ ...field, presentable: false, hidden: false, system: false });
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    await pb.collections.update(cards.id, { fields });
+    console.log("  + cards fields: narrative, narrative_version, narrative_shas");
+  } else {
+    console.log("  = card narrative fields already present");
+  }
+}
+
 async function ensureCardNumbers(pb: PocketBase): Promise<void> {
   const cards = await pb.collections.getOne("cards");
   const have = new Set(cards.fields.map((f: { name: string }) => f.name));
@@ -819,6 +859,9 @@ async function main(): Promise<void> {
   // Add the card number field and backfill existing cards.
   await ensureCardNumbers(pb);
 
+  // Add the AI-generated card narrative fields used by Phase 3c.
+  await ensureCardNarrativeFields(pb);
+
   console.log("Done.");
 }
 

src/lib/pb/types.ts

@@ -82,6 +82,11 @@ export interface CardRecord extends BaseRecord {
   archived: boolean;
   /** Per-project sequential number, for `[#42]` references in commit messages. */
   number: number;
+  /** Client-facing progress narrative, generated from linked commits. */
+  narrative: string;
+  narrative_version: number;
+  /** Fingerprint of the commit set the narrative was written from. */
+  narrative_shas: string;
 }
 
 export interface SubtaskRecord extends BaseRecord {