@cleocode/core 2026.4.44 → 2026.4.46

package/dist/store/db-helpers.d.ts

@@ -22,10 +22,15 @@ export interface ArchiveFields {
  * Upsert a single task row into the tasks table.
  * Handles both active task upsert and archived task upsert via optional archiveFields.
  *
- * Defensively nulls out parentId if it references a non-existent task,
- * preventing orphaned FK violations from blocking bulk operations (T5034).
+ * When `allowOrphanParent` is true (bulk/migration mode, T5034): silently nulls out
+ * parentId if the referenced parent does not exist, preventing FK violations.
+ * When false (normal single-task writes, default): logs a warning but still proceeds
+ * so that FK enforcement at the DB level provides the final safety net.
+ *
+ * Callers that perform bulk imports or archive restoration should pass
+ * `allowOrphanParent: true` to enable the lenient behavior.
  */
-export declare function upsertTask(db: DrizzleDb, row: NewTaskRow, archiveFields?: ArchiveFields): Promise<void>;
+export declare function upsertTask(db: DrizzleDb, row: NewTaskRow, archiveFields?: ArchiveFields, allowOrphanParent?: boolean): Promise<void>;
 /**
  * Upsert a single session row into the sessions table.
  */

package/dist/store/db-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db-helpers.d.ts","sourceRoot":"","sources":["../../src/store/db-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C,sCAAsC;AACtC,KAAK,SAAS,GAAG,kBAAkB,CAAC,OAAO,MAAM,CAAC,CAAC;AAEnD,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,UAAU,EACf,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,IAAI,CAAC,CAwDf;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAkClF;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,SAAS,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,SAAS,EACb,KAAK,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,EAChD,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,SAAS,EACb,KAAK,EAAE,IAAI,EAAE,EACb,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvF"}
+{"version":3,"file":"db-helpers.d.ts","sourceRoot":"","sources":["../../src/store/db-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAI5C,sCAAsC;AACtC,KAAK,SAAS,GAAG,kBAAkB,CAAC,OAAO,MAAM,CAAC,CAAC;AAEnD,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,UAAU,EACf,aAAa,CAAC,EAAE,aAAa,EAC7B,iBAAiB,UAAQ,GACxB,OAAO,CAAC,IAAI,CAAC,CAoEf;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAkClF;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,SAAS,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,SAAS,EACb,KAAK,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,EAChD,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,SAAS,EACb,KAAK,EAAE,IAAI,EAAE,EACb,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvF"}

package/dist/store/migration-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration-manager.d.ts","sourceRoot":"","sources":["../../src/store/migration-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAIlE,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;CACb;AAOD;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAK9E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIlD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CASvD;AAiCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,GACnB,IAAI,CAkIN;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAG5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAE9B,EAAE,EAAE,kBAAkB,CAAC,GAAG,CAAC,EAC3B,gBAAgB,EAAE,MAAM,EACxB,QAAQ,CAAC,EAAE,YAAY,EACvB,cAAc,CAAC,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAkCN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,cAAc,EAAE,EACjC,YAAY,EAAE,MAAM,GACnB,IAAI,CAmBN"}
+{"version":3,"file":"migration-manager.d.ts","sourceRoot":"","sources":["../../src/store/migration-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAIlE,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;CACb;AAOD;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAK9E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIlD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CASvD;AAiCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,GACnB,IAAI,CAkKN;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAG5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAE9B,EAAE,EAAE,kBAAkB,CAAC,GAAG,CAAC,EAC3B,gBAAgB,EAAE,MAAM,EACxB,QAAQ,CAAC,EAAE,YAAY,EACvB,cAAc,CAAC,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAkCN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,cAAc,EAAE,EACjC,YAAY,EAAE,MAAM,GACnB,IAAI,CAmBN"}

package/dist/store/sqlite-data-accessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-data-accessor.d.ts","sourceRoot":"","sources":["../../src/store/sqlite-data-accessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAEV,YAAY,EAKb,MAAM,oBAAoB,CAAC;AA0C5B,yDAAyD;AACzD,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC,CAWf;AAID;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAw1BlF"}
+{"version":3,"file":"sqlite-data-accessor.d.ts","sourceRoot":"","sources":["../../src/store/sqlite-data-accessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAEV,YAAY,EAKb,MAAM,oBAAoB,CAAC;AA0C5B,yDAAyD;AACzD,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC,CAWf;AAID;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAy1BlF"}

package/dist/tasks/complete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"complete.d.ts","sourceRoot":"","sources":["../../src/tasks/complete.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAoB,MAAM,qBAAqB,CAAC;AAM3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;CACvD;AAiED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAmQ7B"}
+{"version":3,"file":"complete.d.ts","sourceRoot":"","sources":["../../src/tasks/complete.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAoB,MAAM,qBAAqB,CAAC;AAM3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;CACvD;AAiED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAsQ7B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.4.44",
+  "version": "2026.4.46",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,13 +53,13 @@
     "write-file-atomic": "^7.0.1",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@cleocode/adapters": "2026.4.44",
-    "@cleocode/agents": "2026.4.44",
-    "@cleocode/caamp": "2026.4.44",
-    "@cleocode/contracts": "2026.4.44",
-    "@cleocode/lafs": "2026.4.44",
-    "@cleocode/nexus": "2026.4.44",
-    "@cleocode/skills": "2026.4.44"
+    "@cleocode/adapters": "2026.4.46",
+    "@cleocode/caamp": "2026.4.46",
+    "@cleocode/agents": "2026.4.46",
+    "@cleocode/lafs": "2026.4.46",
+    "@cleocode/contracts": "2026.4.46",
+    "@cleocode/nexus": "2026.4.46",
+    "@cleocode/skills": "2026.4.46"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/store/__tests__/db-helpers.test.ts

@@ -1,7 +1,8 @@
 /**
- * Tests for db-helpers.ts — defensive orphan parent handling (T5034).
+ * Tests for db-helpers.ts — defensive orphan parent handling (T5034, T585).
  *
  * @task T5034
+ * @task T585
  */
 
 import { mkdtemp, rm } from 'node:fs/promises';
@@ -30,13 +31,47 @@ describe('upsertTask — orphan parent handling', () => {
     await rm(tempDir, { recursive: true, force: true });
   });
 
-  it('nulls out parentId when parent task does not exist', async () => {
+  it('nulls out parentId when allowOrphanParent=true and parent does not exist', async () => {
     const { getDb } = await import('../sqlite.js');
     const { upsertTask } = await import('../db-helpers.js');
     const schema = await import('../tasks-schema.js');
     const db = await getDb();
 
-    // Insert a child task with a non-existent parent
+    // Insert a child task with a non-existent parent using allowOrphanParent=true (bulk mode)
+    await upsertTask(
+      db,
+      {
+        id: 'T100',
+        title: 'Child task',
+        description: 'Has orphan parent ref',
+        status: 'pending',
+        priority: 'medium',
+        parentId: 'T999', // does NOT exist in DB
+        createdAt: new Date().toISOString(),
+      },
+      undefined,
+      true, // allowOrphanParent: silently null out for bulk/archive operations (T5034)
+    );
+
+    // Verify the task was inserted with parentId = null
+    const rows = await db.select().from(schema.tasks).where(eq(schema.tasks.id, 'T100')).all();
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!.parentId).toBeNull();
+  });
+
+  it('preserves parentId (with warning) when allowOrphanParent=false and parent does not exist', async () => {
+    // In normal single-task write mode (default), upsertTask logs a warning but does NOT
+    // silently null out the parentId. This prevents data corruption for normal task creation
+    // while still surfacing the integrity issue. The FK constraint (disabled in tests) would
+    // reject the write in production if the parent truly does not exist.
+    const { getDb } = await import('../sqlite.js');
+    const { upsertTask } = await import('../db-helpers.js');
+    const schema = await import('../tasks-schema.js');
+    const db = await getDb();
+
+    // Insert a child task with a non-existent parent using default allowOrphanParent=false
+    // In VITEST, FK enforcement is OFF, so this will succeed without null-out.
     await upsertTask(db, {
       id: 'T100',
       title: 'Child task',
@@ -47,11 +82,13 @@ describe('upsertTask — orphan parent handling', () => {
       createdAt: new Date().toISOString(),
     });
 
-    // Verify the task was inserted with parentId = null
+    // With allowOrphanParent=false, the parentId is NOT nulled out — warning is logged.
+    // In test env FK is off, so T100 gets stored with parentId='T999' (not null).
     const rows = await db.select().from(schema.tasks).where(eq(schema.tasks.id, 'T100')).all();
 
     expect(rows).toHaveLength(1);
-    expect(rows[0]!.parentId).toBeNull();
+    // parentId is preserved (not silently nulled), indicating the warning-only behavior
+    expect(rows[0]!.parentId).toBe('T999');
   });
 
   it('preserves parentId when parent task exists', async () => {
@@ -88,7 +125,9 @@ describe('upsertTask — orphan parent handling', () => {
     expect(rows[0]!.parentId).toBe('T001');
   });
 
-  it('handles archived task with orphan parent (T5034 regression)', async () => {
+  it('handles archived task with orphan parent using allowOrphanParent=true (T5034 regression)', async () => {
+    // Bulk archive operations pass allowOrphanParent=true to tolerate missing parents.
+    // This prevents FK violations when archiving tasks whose parents were deleted.
     const { getDb } = await import('../sqlite.js');
     const { upsertTask } = await import('../db-helpers.js');
     const schema = await import('../tasks-schema.js');
@@ -110,6 +149,7 @@ describe('upsertTask — orphan parent handling', () => {
         archivedAt: '2025-06-01T00:00:00Z',
         archiveReason: 'completed',
       },
+      true, // allowOrphanParent: bulk/archive mode silently nulls (T5034)
     );
 
     // Should succeed (not throw) and null out the parentId

package/src/store/db-helpers.ts

@@ -10,9 +10,12 @@
 import type { Session, Task } from '@cleocode/contracts';
 import { eq, inArray } from 'drizzle-orm';
 import type { NodeSQLiteDatabase } from 'drizzle-orm/node-sqlite';
+import { getLogger } from '../logger.js';
 import type { NewTaskRow } from './tasks-schema.js';
 import * as schema from './tasks-schema.js';
 
+const log = getLogger('db-helpers');
+
 /** Drizzle database instance type. */
 type DrizzleDb = NodeSQLiteDatabase<typeof schema>;
 
@@ -27,15 +30,24 @@ export interface ArchiveFields {
  * Upsert a single task row into the tasks table.
  * Handles both active task upsert and archived task upsert via optional archiveFields.
  *
- * Defensively nulls out parentId if it references a non-existent task,
- * preventing orphaned FK violations from blocking bulk operations (T5034).
+ * When `allowOrphanParent` is true (bulk/migration mode, T5034): silently nulls out
+ * parentId if the referenced parent does not exist, preventing FK violations.
+ * When false (normal single-task writes, default): logs a warning but still proceeds
+ * so that FK enforcement at the DB level provides the final safety net.
+ *
+ * Callers that perform bulk imports or archive restoration should pass
+ * `allowOrphanParent: true` to enable the lenient behavior.
  */
 export async function upsertTask(
   db: DrizzleDb,
   row: NewTaskRow,
   archiveFields?: ArchiveFields,
+  allowOrphanParent = false,
 ): Promise<void> {
-  // Defensive: null out parentId if it references a non-existent task (T5034)
+  // Validate parentId exists before writing (T5034, T585).
+  // In bulk/archive mode (allowOrphanParent=true) we silently null it out to
+  // avoid FK violations during migrations. In normal mode we log a warning so
+  // the data integrity issue surfaces without breaking the write.
   if (row.parentId) {
     const parent = await db
       .select({ id: schema.tasks.id })
@@ -44,7 +56,16 @@ export async function upsertTask(
       .limit(1)
       .all();
     if (parent.length === 0) {
-      row = { ...row, parentId: null };
+      if (allowOrphanParent) {
+        row = { ...row, parentId: null };
+      } else {
+        // Log a warning — the FK constraint will reject the write if enabled,
+        // or the task will be stored without a parent if FKs are off (test mode).
+        log.warn(
+          { taskId: row.id, parentId: row.parentId },
+          'upsertTask: parentId references a non-existent task — parent relationship may be lost',
+        );
+      }
     }
   }
 

package/src/store/migration-manager.ts

@@ -144,23 +144,55 @@ export function reconcileJournal(
   }
 
   // Scenario 2: Journal has orphaned entries from a previous CLEO version
+  //
+  // Two distinct sub-cases require different handling:
+  //
+  // A) DB is AHEAD of this install (forward-compatibility): all local hashes
+  //    are present in the DB, but the DB also has additional entries for
+  //    migrations this install does not know about. This happens when a user
+  //    runs a globally-installed (older) cleo binary against a DB that was
+  //    last written by a newer cleo version. Deleting those entries would
+  //    cause an infinite reconciliation cycle: Drizzle re-runs the "missing"
+  //    migrations, hits duplicate-column errors (Scenario 3 recovers), writes
+  //    them back — only for this install to delete them again on the next run.
+  //    ACTION: skip reconciliation, log at debug only.
+  //
+  // B) DB has stale hashes from a genuinely old CLEO version whose checksum
+  //    algorithm produced different hashes for the same migration files (i.e.,
+  //    at least one local hash is MISSING from the DB while other DB entries
+  //    are unrecognised). ACTION: delete and re-seed as before, log at warn.
   if (tableExists(nativeDb, '__drizzle_migrations') && tableExists(nativeDb, existenceTable)) {
     const localMigrations = readMigrationFiles({ migrationsFolder });
     const localHashes = new Set(localMigrations.map((m) => m.hash));
     const dbEntries = nativeDb.prepare('SELECT hash FROM "__drizzle_migrations"').all() as Array<{
       hash: string;
     }>;
-    const hasOrphanedEntries = dbEntries.some((e) => !localHashes.has(e.hash));
+    const orphanedEntries = dbEntries.filter((e) => !localHashes.has(e.hash));
+    const hasOrphanedEntries = orphanedEntries.length > 0;
 
     if (hasOrphanedEntries) {
-      const log = getLogger(logSubsystem);
-      log.warn(
-        { orphaned: dbEntries.filter((e) => !localHashes.has(e.hash)).length },
-        `Detected stale migration journal entries from a previous CLEO version. Reconciling.`,
-      );
-      nativeDb.exec('DELETE FROM "__drizzle_migrations"');
-      for (const m of localMigrations) {
-        insertJournalEntry(nativeDb, m.hash, m.folderMillis, m.name ?? '');
+      const dbHashes = new Set(dbEntries.map((e) => e.hash));
+      const allLocalHashesPresentInDb = localMigrations.every((m) => dbHashes.has(m.hash));
+
+      if (allLocalHashesPresentInDb) {
+        // Sub-case A: DB is ahead — this install is older than the DB.
+        // Do NOT modify the journal; log at debug so we can trace if needed.
+        const log = getLogger(logSubsystem);
+        log.debug(
+          { extra: orphanedEntries.length },
+          `Migration journal has ${orphanedEntries.length} entries for migrations not known to this install (DB is ahead). Skipping reconciliation.`,
+        );
+      } else {
+        // Sub-case B: Genuine stale hashes from an older CLEO version.
+        const log = getLogger(logSubsystem);
+        log.warn(
+          { orphaned: orphanedEntries.length },
+          `Detected stale migration journal entries from a previous CLEO version. Reconciling.`,
+        );
+        nativeDb.exec('DELETE FROM "__drizzle_migrations"');
+        for (const m of localMigrations) {
+          insertJournalEntry(nativeDb, m.hash, m.folderMillis, m.name ?? '');
+        }
       }
     }
   }

package/src/store/sqlite-data-accessor.ts

@@ -198,7 +198,8 @@ export async function createSqliteDataAccessor(cwd?: string): Promise<DataAccess
             cycleTimeDays: taskAny.cycleTimeDays ?? null,
           };
 
-          await upsertTask(db, row, archiveFields);
+          // allowOrphanParent=true: bulk archive writes tolerate missing parents (T5034)
+          await upsertTask(db, row, archiveFields, true);
           depBatch.push({ taskId: task.id, deps: task.depends ?? [] });
         }
 

package/src/tasks/__tests__/epic-auto-complete.test.ts

@@ -0,0 +1,331 @@
+/**
+ * Tests for epic auto-complete behavior (T585).
+ *
+ * Verifies that an epic only auto-completes when ALL its direct subtasks
+ * are in terminal states (done or cancelled), not when only some are done.
+ *
+ * @task T585
+ */
+
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createTestDb, seedTasks, type TestDbEnv } from '../../store/__tests__/test-db-helper.js';
+import type { DataAccessor } from '../../store/data-accessor.js';
+import { resetDbState } from '../../store/sqlite.js';
+import { completeTask } from '../complete.js';
+
+describe('epic auto-complete', () => {
+  let env: TestDbEnv;
+  let accessor: DataAccessor;
+
+  const writeConfig = async (config: Record<string, unknown>): Promise<void> => {
+    await writeFile(join(env.cleoDir, 'config.json'), JSON.stringify(config));
+  };
+
+  beforeEach(async () => {
+    env = await createTestDb();
+    accessor = env.accessor;
+    process.env['CLEO_DIR'] = env.cleoDir;
+    await writeConfig({
+      enforcement: {
+        session: { requiredForMutate: false },
+        acceptance: { mode: 'off' },
+      },
+      lifecycle: { mode: 'off' },
+      verification: { enabled: false },
+    });
+  });
+
+  afterEach(async () => {
+    delete process.env['CLEO_DIR'];
+    resetDbState();
+    await env.cleanup();
+  });
+
+  it('does NOT auto-complete epic when only one of two subtasks is completed (bug T585)', async () => {
+    await seedTasks(accessor, [
+      {
+        id: 'T001',
+        title: 'Test Epic',
+        type: 'epic',
+        status: 'active',
+        priority: 'medium',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T002',
+        title: 'Sub 1',
+        type: 'task',
+        status: 'active',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T003',
+        title: 'Sub 2',
+        type: 'task',
+        status: 'pending',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+    ]);
+
+    const result = await completeTask({ taskId: 'T002' }, env.tempDir, accessor);
+
+    expect(result.task.status).toBe('done');
+    expect(result.autoCompleted).toBeUndefined();
+
+    // Verify the epic is still not done
+    const epic = await accessor.loadSingleTask('T001');
+    expect(epic?.status).not.toBe('done');
+
+    // Verify T003 is still pending
+    const sub2 = await accessor.loadSingleTask('T003');
+    expect(sub2?.status).toBe('pending');
+  });
+
+  it('auto-completes epic when the LAST pending subtask is completed', async () => {
+    await seedTasks(accessor, [
+      {
+        id: 'T001',
+        title: 'Test Epic',
+        type: 'epic',
+        status: 'active',
+        priority: 'medium',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T002',
+        title: 'Sub 1',
+        type: 'task',
+        status: 'done',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+        completedAt: new Date().toISOString(),
+      },
+      {
+        id: 'T003',
+        title: 'Sub 2',
+        type: 'task',
+        status: 'active',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+    ]);
+
+    const result = await completeTask({ taskId: 'T003' }, env.tempDir, accessor);
+
+    expect(result.task.status).toBe('done');
+    expect(result.autoCompleted).toContain('T001');
+
+    const epic = await accessor.loadSingleTask('T001');
+    expect(epic?.status).toBe('done');
+  });
+
+  it('does NOT auto-complete epic when remaining subtask is blocked (not terminal)', async () => {
+    await seedTasks(accessor, [
+      {
+        id: 'T001',
+        title: 'Test Epic',
+        type: 'epic',
+        status: 'active',
+        priority: 'medium',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T002',
+        title: 'Sub 1',
+        type: 'task',
+        status: 'active',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T003',
+        title: 'Sub 2',
+        type: 'task',
+        status: 'blocked',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+    ]);
+
+    const result = await completeTask({ taskId: 'T002' }, env.tempDir, accessor);
+
+    expect(result.task.status).toBe('done');
+    expect(result.autoCompleted).toBeUndefined();
+
+    const epic = await accessor.loadSingleTask('T001');
+    expect(epic?.status).not.toBe('done');
+  });
+
+  it('auto-completes epic when all remaining subtasks are cancelled', async () => {
+    await seedTasks(accessor, [
+      {
+        id: 'T001',
+        title: 'Test Epic',
+        type: 'epic',
+        status: 'active',
+        priority: 'medium',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T002',
+        title: 'Sub 1',
+        type: 'task',
+        status: 'active',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T003',
+        title: 'Sub 2',
+        type: 'task',
+        status: 'cancelled',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+        cancelledAt: new Date().toISOString(),
+      },
+    ]);
+
+    const result = await completeTask({ taskId: 'T002' }, env.tempDir, accessor);
+
+    expect(result.task.status).toBe('done');
+    expect(result.autoCompleted).toContain('T001');
+
+    const epic = await accessor.loadSingleTask('T001');
+    expect(epic?.status).toBe('done');
+  });
+
+  it('does NOT auto-complete epic when getChildren returns an empty list (vacuous truth guard, T585)', async () => {
+    // Defensive guard against [].every() === true (vacuous truth).
+    // If getChildren(epic) returns [] — e.g. because all children have
+    // parent_id=null due to a data-integrity issue — completing any task
+    // with task.parentId set to that epic must NOT auto-complete it.
+    //
+    // We simulate this by: seeding T001 (epic) and T002 (task with parentId=T001),
+    // then manually clearing T002's parent_id in the DB so getChildren(T001) returns [].
+    // But loadSingleTask(T002) still returns parentId:'T001' ... wait, no. If parent_id
+    // is NULL in DB then rowToTask returns parentId: undefined. So task.parentId is falsy
+    // and the auto-complete block is skipped entirely.
+    //
+    // The vacuous truth guard `siblings.length > 0` is still correct defensive code for
+    // the scenario where getChildren returns [] for any reason (e.g., future filter changes).
+    // The primary bug fix (partial completion doesn't close epic) is proven by test 1 above.
+    //
+    // This test creates a mock accessor that returns [] for getChildren to verify the guard.
+    await seedTasks(accessor, [
+      {
+        id: 'T001',
+        title: 'Test Epic',
+        type: 'epic',
+        status: 'active',
+        priority: 'medium',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T002',
+        title: 'Sub 1',
+        type: 'task',
+        status: 'active',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+    ]);
+
+    // Create a wrapper accessor that overrides getChildren to return []
+    // to simulate the vacuous truth scenario.
+    const wrappedAccessor = {
+      ...accessor,
+      getChildren: async (parentId: string) => {
+        if (parentId === 'T001') return []; // Simulate no registered children
+        return accessor.getChildren(parentId);
+      },
+    } as typeof accessor;
+
+    const result = await completeTask({ taskId: 'T002' }, env.tempDir, wrappedAccessor);
+
+    expect(result.task.status).toBe('done');
+    // With vacuous truth guard: empty siblings → allDone = false → epic does NOT auto-complete
+    expect(result.autoCompleted).toBeUndefined();
+
+    const epic = await accessor.loadSingleTask('T001');
+    expect(epic?.status).not.toBe('done');
+  });
+
+  it('does NOT auto-complete epic when it has 5 subtasks and only 1 is being completed', async () => {
+    await seedTasks(accessor, [
+      {
+        id: 'T001',
+        title: 'Big Epic',
+        type: 'epic',
+        status: 'active',
+        priority: 'medium',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T002',
+        title: 'Sub 1',
+        type: 'task',
+        status: 'active',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T003',
+        title: 'Sub 2',
+        type: 'task',
+        status: 'pending',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T004',
+        title: 'Sub 3',
+        type: 'task',
+        status: 'pending',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T005',
+        title: 'Sub 4',
+        type: 'task',
+        status: 'pending',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+      {
+        id: 'T006',
+        title: 'Sub 5',
+        type: 'task',
+        status: 'pending',
+        priority: 'medium',
+        parentId: 'T001',
+        acceptance: ['AC1'],
+      },
+    ]);
+
+    const result = await completeTask({ taskId: 'T002' }, env.tempDir, accessor);
+
+    expect(result.task.status).toBe('done');
+    expect(result.autoCompleted).toBeUndefined();
+
+    const epic = await accessor.loadSingleTask('T001');
+    expect(epic?.status).not.toBe('done');
+  });
+});

package/src/tasks/complete.ts

@@ -235,10 +235,13 @@ export async function completeTask(
     const parent = await acc.loadSingleTask(task.parentId);
     if (parent && parent.type === 'epic' && !parent.noAutoComplete) {
       const siblings = await acc.getChildren(parent.id);
-      // The current task is not yet 'done' in DB, so check by ID
-      const allDone = siblings.every(
-        (c) => c.id === task.id || c.status === 'done' || c.status === 'cancelled',
-      );
+      // Guard: only auto-complete if the epic has at least one registered child.
+      // An empty siblings list means no children are recorded in the DB, which
+      // would vacuously satisfy .every() and incorrectly auto-complete the epic.
+      // The current task is not yet 'done' in DB, so match it by ID.
+      const allDone =
+        siblings.length > 0 &&
+        siblings.every((c) => c.id === task.id || c.status === 'done' || c.status === 'cancelled');
       if (allDone) {
         parent.status = 'done';
         parent.completedAt = now;