feat(acceptance-criteria): implement change tracking and note creation for acceptance criteria updates

Author: tikazyq

.devlog/entries/287-migrate-existing-json-devlog-entries-to-postgresql.json

@@ -7,8 +7,15 @@
   "status": "new",
   "priority": "high",
   "createdAt": "2025-07-27T14:46:29.476Z",
-  "updatedAt": "2025-07-27T14:46:29.476Z",
-  "notes": [],
+  "updatedAt": "2025-07-27T15:27:24.888Z",
+  "notes": [
+    {
+      "id": "d27fc3ec-db94-4b68-94b1-ea9745c2d110",
+      "timestamp": "2025-07-27T15:27:24.888Z",
+      "category": "progress",
+      "content": "Starting JSON to PostgreSQL migration. User has truncated existing PG entries and wants fast bulk migration approach. Need to:\n1. Explore existing JSON devlog structure \n2. Map to flattened DevlogEntry structure from #286\n3. Create efficient bulk insert script\n4. Use PostgreSQL connection from .env file"
+    }
+  ],
   "files": [],
   "relatedDevlogs": [],
   "context": {

packages/core/src/entities/devlog-entry.entity.ts

@@ -85,11 +85,4 @@ export class DevlogEntryEntity {
 
   @JsonColumn({ default: getStorageType() === 'sqlite' ? '[]' : [], name: 'acceptance_criteria' })
   acceptanceCriteria!: string[];
-
-  // Simple arrays that can remain as JSON columns
-  @JsonColumn({ default: getStorageType() === 'sqlite' ? '[]' : [] })
-  files!: string[];
-
-  @JsonColumn({ default: getStorageType() === 'sqlite' ? '[]' : [], name: 'related_devlogs' })
-  relatedDevlogs!: string[];
 }

packages/core/src/entities/devlog-note.entity.ts

@@ -39,6 +39,14 @@ export class DevlogNoteEntity {
   @Column({ type: 'text', nullable: true, name: 'code_changes' })
   codeChanges?: string;
 
+  // Metadata for special note types (e.g., acceptance-criteria changes)
+  @JsonColumn({ nullable: true, default: null })
+  metadata?: {
+    previousCriteria?: string[];
+    newCriteria?: string[];
+    changeType?: 'added' | 'removed' | 'modified' | 'reordered';
+  };
+
   // Foreign key relationship
   @ManyToOne(() => DevlogEntryEntity, { onDelete: 'CASCADE' })
   @JoinColumn({ name: 'devlog_id' })

packages/core/src/managers/devlog/workspace-devlog-manager.ts

@@ -6,6 +6,7 @@
 import { join } from 'path';
 import { homedir } from 'os';
 import * as crypto from 'crypto';
+import { createAcceptanceCriteriaNote } from '../../utils/acceptance-criteria.js';
 import type {
   CreateDevlogRequest,
   DevlogEntry,
@@ -370,8 +371,6 @@ export class WorkspaceDevlogManager {
       updatedAt: now,
       assignee: request.assignee,
       notes: [],
-      files: [],
-      relatedDevlogs: [],
       acceptanceCriteria: request.acceptanceCriteria || [],
       businessContext: request.businessContext || '',
       technicalContext: request.technicalContext || '',
@@ -443,10 +442,32 @@ export class WorkspaceDevlogManager {
       initialInsights !== undefined ||
       relatedPatterns !== undefined
     ) {
-      // Update flattened context fields directly
+      // Update other flattened context fields directly
       if (businessContext !== undefined) updated.businessContext = businessContext;
       if (technicalContext !== undefined) updated.technicalContext = technicalContext;
-      if (acceptanceCriteria !== undefined) updated.acceptanceCriteria = acceptanceCriteria;
+    }
+
+    // Handle acceptance criteria updates with automatic change tracking
+    if (acceptanceCriteria !== undefined) {
+      const previousCriteria = existing.acceptanceCriteria || [];
+      updated.acceptanceCriteria = acceptanceCriteria;
+
+      // Create automatic AC change note if criteria actually changed
+      if (JSON.stringify(previousCriteria) !== JSON.stringify(acceptanceCriteria)) {
+        const acNote = createAcceptanceCriteriaNote(
+          previousCriteria,
+          acceptanceCriteria,
+          data.acChangeReason, // Optional reason from the update request
+        );
+
+        // Add the note to the entry (will be saved with the entry)
+        if (!updated.notes) updated.notes = [];
+        updated.notes.push({
+          id: crypto.randomUUID(),
+          timestamp: now,
+          ...acNote,
+        });
+      }
     }
 
     // Ensure closedAt is set when status changes to 'done' or 'cancelled'

packages/core/src/storage/providers/typeorm-storage.ts

@@ -430,8 +430,6 @@ export class TypeORMStorageProvider implements StorageProvider {
       closedAt: entity.closedAt?.toISOString(),
       archived: entity.archived,
       assignee: entity.assignee,
-      files: this.parseJsonField(entity.files, []),
-      relatedDevlogs: this.parseJsonField(entity.relatedDevlogs, []),
       acceptanceCriteria: this.parseJsonField(entity.acceptanceCriteria, []),
       businessContext: entity.businessContext,
       technicalContext: entity.technicalContext,
@@ -456,8 +454,6 @@ export class TypeORMStorageProvider implements StorageProvider {
     if (entry.closedAt) entity.closedAt = new Date(entry.closedAt);
     entity.archived = entry.archived || false;
     entity.assignee = entry.assignee;
-    entity.files = this.stringifyJsonField(entry.files || []);
-    entity.relatedDevlogs = this.stringifyJsonField(entry.relatedDevlogs || []);
     entity.acceptanceCriteria = this.stringifyJsonField(entry.acceptanceCriteria || []);
     entity.businessContext = entry.businessContext;
     entity.technicalContext = entry.technicalContext;

packages/core/src/types/core.ts

@@ -158,6 +158,13 @@ export interface DevlogNote {
   content: string;
   files?: string[];
   codeChanges?: string;
+  // Metadata for special note types (e.g., acceptance-criteria changes)
+  metadata?: {
+    // For acceptance-criteria category
+    previousCriteria?: string[];
+    newCriteria?: string[];
+    changeType?: 'added' | 'removed' | 'modified' | 'reordered';
+  };
 }
 
 export interface DevlogEntry {
@@ -174,12 +181,8 @@ export interface DevlogEntry {
   assignee?: string;
   archived?: boolean; // For long-term management and performance
 
-  // Simple arrays that remain as JSON
-  files?: string[];
-  relatedDevlogs?: string[];
+  // Flattened context fields
   acceptanceCriteria?: string[];
-
-  // Flattened context fields (simple strings)
   businessContext?: string;
   technicalContext?: string;
 

packages/core/src/types/requests.ts

@@ -43,6 +43,7 @@ export interface UpdateDevlogRequest {
   businessContext?: string;
   technicalContext?: string;
   acceptanceCriteria?: string[];
+  acChangeReason?: string; // Optional reason for AC changes (creates better change notes)
   initialInsights?: string[];
   relatedPatterns?: string[];
 

packages/core/src/utils/acceptance-criteria.ts

@@ -0,0 +1,117 @@
+/**
+ * Utility functions for Acceptance Criteria change tracking
+ */
+
+import { DevlogNote } from '../types/index.js';
+
+/**
+ * Compare two arrays of acceptance criteria and determine what changed
+ */
+export function compareAcceptanceCriteria(
+  previous: string[],
+  current: string[],
+): {
+  changeType: 'added' | 'removed' | 'modified' | 'reordered';
+  addedItems: string[];
+  removedItems: string[];
+  modifiedItems: Array<{ old: string; new: string }>;
+} {
+  const prevSet = new Set(previous);
+  const currSet = new Set(current);
+
+  const addedItems = current.filter((item) => !prevSet.has(item));
+  const removedItems = previous.filter((item) => !currSet.has(item));
+
+  // For simplicity, we'll treat any differences as modifications
+  // More sophisticated diff logic could be added later
+  const modifiedItems: Array<{ old: string; new: string }> = [];
+
+  // Determine primary change type
+  let changeType: 'added' | 'removed' | 'modified' | 'reordered';
+  if (addedItems.length > 0 && removedItems.length === 0) {
+    changeType = 'added';
+  } else if (removedItems.length > 0 && addedItems.length === 0) {
+    changeType = 'removed';
+  } else if (addedItems.length > 0 || removedItems.length > 0) {
+    changeType = 'modified';
+  } else if (JSON.stringify(previous) !== JSON.stringify(current)) {
+    changeType = 'reordered';
+  } else {
+    changeType = 'modified'; // fallback
+  }
+
+  return {
+    changeType,
+    addedItems,
+    removedItems,
+    modifiedItems,
+  };
+}
+
+/**
+ * Create a formatted note content for acceptance criteria changes
+ */
+export function createAcceptanceCriteriaChangeNote(
+  previous: string[],
+  current: string[],
+  changeReason?: string,
+): { content: string; metadata: DevlogNote['metadata'] } {
+  const comparison = compareAcceptanceCriteria(previous, current);
+
+  let content = '**Acceptance Criteria Updated**\n\n';
+
+  if (changeReason) {
+    content += `**Reason:** ${changeReason}\n\n`;
+  }
+
+  if (comparison.addedItems.length > 0) {
+    content += '**Added:**\n';
+    comparison.addedItems.forEach((item) => {
+      content += `+ ${item}\n`;
+    });
+    content += '\n';
+  }
+
+  if (comparison.removedItems.length > 0) {
+    content += '**Removed:**\n';
+    comparison.removedItems.forEach((item) => {
+      content += `- ${item}\n`;
+    });
+    content += '\n';
+  }
+
+  if (comparison.changeType === 'reordered') {
+    content += '**Reordered acceptance criteria**\n\n';
+  }
+
+  content += '**Current Acceptance Criteria:**\n';
+  current.forEach((item, index) => {
+    content += `${index + 1}. ${item}\n`;
+  });
+
+  const metadata: DevlogNote['metadata'] = {
+    previousCriteria: previous,
+    newCriteria: current,
+    changeType: comparison.changeType,
+  };
+
+  return { content, metadata };
+}
+
+/**
+ * Helper to create a complete DevlogNote for AC changes
+ */
+export function createAcceptanceCriteriaNote(
+  previous: string[],
+  current: string[],
+  changeReason?: string,
+  changedBy?: string,
+): Omit<DevlogNote, 'id' | 'timestamp'> {
+  const { content, metadata } = createAcceptanceCriteriaChangeNote(previous, current, changeReason);
+
+  return {
+    category: 'acceptance-criteria',
+    content,
+    metadata,
+  };
+}

packages/core/src/utils/index.ts

@@ -6,3 +6,4 @@ export * from './filter-mapping.js';
 export * from './common.js';
 export * from './errors.js';
 export * from './env-loader.js';
+export * from './acceptance-criteria.js';