@cleocode/core 2026.4.45 → 2026.4.47

package/src/memory/brain-lifecycle.ts

@@ -381,14 +381,21 @@ export interface PromotionResult {
 /**
  * Run tier promotion for all memory tables.
  *
- * Promotion rules (per spec §1.1–§1.3):
- * - short → medium: citationCount >= 3 AND age > 24h AND verified = true
- *   OR qualityScore >= 0.7 AND verified = true (fast-track)
- * - medium → long:  citationCount >= 5 AND age > 7 days AND verified = true
+ * Promotion rules (per spec §1.1–§1.3, relaxed in T614):
+ * - short → medium:
+ *     A. (citationCount >= 3 AND age > 24h) — citation-based track
+ *     B. (qualityScore >= 0.7 AND age > 24h) — quality fast-track
+ *     C. (verified = true AND age > 24h) — owner-verified track
+ *   Note: `verified` is no longer a hard gate for routes A and B.
+ *   Requiring verified=true on all paths caused all 235 short-tier observations
+ *   to be permanently stuck (T614 bug).
+ * - medium → long:
+ *     (citationCount >= 5 AND age > 7 days) OR (verified = true AND age > 7 days)
+ *   Verified entries accelerate to long-tier without citation threshold.
  *
  * Eviction rules:
- * - short-term entries older than shortTermEvictionDays (default 7) with no
- *   promotion eligibility are soft-evicted (invalidAt = now).
+ * - short-term entries older than 7 days with no promotion eligibility are
+ *   soft-evicted (invalidAt = now).
  * - long-term entries are NEVER auto-evicted.
  *
  * @param projectRoot - Project root directory for brain.db resolution
@@ -431,25 +438,30 @@ export async function runTierPromotion(projectRoot: string): Promise<PromotionRe
 
   for (const { table, dateCol } of tables) {
     // --- short → medium promotion ---
-    // Two criteria (union):
-    //   A. citationCount >= 3 AND age > 24h AND verified = 1
-    //   B. quality_score >= 0.7 AND verified = 1 AND age > 24h (fast-track)
+    // Three criteria (union — verified is no longer a hard gate for A/B paths):
+    //   A. citationCount >= 3 AND age > 24h  (citation track — no verified requirement)
+    //   B. quality_score >= 0.7 AND age > 24h (quality fast-track — no verified requirement)
+    //   C. verified = 1 AND age > 24h         (owner-verified track)
     interface TierRow {
       id: string;
       citation_count: number;
       quality_score: number | null;
+      verified: number;
     }
     let shortToMedium: TierRow[] = [];
     try {
       shortToMedium = typedAll<TierRow>(
         nativeDb.prepare(`
-          SELECT id, citation_count, quality_score
+          SELECT id, citation_count, quality_score, verified
           FROM ${table}
           WHERE memory_tier = 'short'
             AND invalid_at IS NULL
             AND ${dateCol} < ?
-            AND verified = 1
-            AND (citation_count >= 3 OR quality_score >= 0.7)
+            AND (
+              citation_count >= 3
+              OR quality_score >= 0.7
+              OR verified = 1
+            )
         `),
         age24h,
       );
@@ -463,33 +475,34 @@ export async function runTierPromotion(projectRoot: string): Promise<PromotionRe
         nativeDb
           .prepare(`UPDATE ${table} SET memory_tier = 'medium', updated_at = ? WHERE id = ?`)
           .run(now, row.id);
-        promoted.push({
-          id: row.id,
-          table,
-          fromTier: 'short',
-          toTier: 'medium',
-          reason:
-            row.citation_count >= 3
-              ? `citationCount=${row.citation_count} >= 3, verified, age > 24h`
-              : `qualityScore=${row.quality_score?.toFixed(2)} >= 0.70, verified, age > 24h`,
-        });
+        let reason: string;
+        if (row.citation_count >= 3) {
+          reason = `citationCount=${row.citation_count} >= 3, age > 24h`;
+        } else if ((row.quality_score ?? 0) >= 0.7) {
+          reason = `qualityScore=${row.quality_score?.toFixed(2)} >= 0.70, age > 24h`;
+        } else {
+          reason = `verified=true, age > 24h`;
+        }
+        promoted.push({ id: row.id, table, fromTier: 'short', toTier: 'medium', reason });
       } catch {
         /* best-effort */
       }
     }
 
     // --- medium → long promotion ---
+    // Two criteria (union — verified accelerates to long without citation threshold):
+    //   A. citationCount >= 5 AND age > 7d
+    //   B. verified = 1 AND age > 7d (owner-verified accelerated track)
     let mediumToLong: TierRow[] = [];
     try {
       mediumToLong = typedAll<TierRow>(
         nativeDb.prepare(`
-          SELECT id, citation_count, quality_score
+          SELECT id, citation_count, quality_score, verified
           FROM ${table}
           WHERE memory_tier = 'medium'
             AND invalid_at IS NULL
             AND ${dateCol} < ?
-            AND verified = 1
-            AND citation_count >= 5
+            AND (citation_count >= 5 OR verified = 1)
         `),
         age7d,
       );
@@ -502,13 +515,11 @@ export async function runTierPromotion(projectRoot: string): Promise<PromotionRe
         nativeDb
           .prepare(`UPDATE ${table} SET memory_tier = 'long', updated_at = ? WHERE id = ?`)
           .run(now, row.id);
-        promoted.push({
-          id: row.id,
-          table,
-          fromTier: 'medium',
-          toTier: 'long',
-          reason: `citationCount=${row.citation_count} >= 5, verified, age > 7d`,
-        });
+        const reason =
+          row.citation_count >= 5
+            ? `citationCount=${row.citation_count} >= 5, age > 7d`
+            : `verified=true, age > 7d`;
+        promoted.push({ id: row.id, table, fromTier: 'medium', toTier: 'long', reason });
       } catch {
         /* best-effort */
       }

package/src/memory/brain-maintenance.ts

@@ -20,7 +20,7 @@
  */
 
 import { reconcileOrphanedRefs } from '../store/cross-db-cleanup.js';
-import { applyTemporalDecay, consolidateMemories } from './brain-lifecycle.js';
+import { applyTemporalDecay, consolidateMemories, runTierPromotion } from './brain-lifecycle.js';
 import { populateEmbeddings } from './brain-retrieval.js';
 
 // ============================================================================
@@ -61,6 +61,14 @@ export interface BrainMaintenanceEmbeddingsResult {
   errors: number;
 }
 
+/** Tier promotion step result. */
+export interface BrainMaintenanceTierPromotionResult {
+  /** Number of entries promoted (short→medium or medium→long). */
+  promoted: number;
+  /** Number of stale short-tier entries soft-evicted. */
+  evicted: number;
+}
+
 /**
  * Aggregated result from a full brain maintenance run.
  *
@@ -74,6 +82,8 @@ export interface BrainMaintenanceResult {
   consolidation: BrainMaintenanceConsolidationResult;
   /** Results from the cross-DB orphaned reference reconciliation step. */
   reconciliation: BrainMaintenanceReconciliationResult;
+  /** Results from the tier promotion step. */
+  tierPromotion: BrainMaintenanceTierPromotionResult;
   /** Results from the embedding backfill step. */
   embeddings: BrainMaintenanceEmbeddingsResult;
   /** Total wall-clock duration of the maintenance run in milliseconds. */
@@ -93,6 +103,8 @@ export interface BrainMaintenanceOptions {
   skipConsolidation?: boolean;
   /** Skip the cross-DB orphaned reference reconciliation step. Default: false. */
   skipReconciliation?: boolean;
+  /** Skip the tier promotion step (short→medium, medium→long). Default: false. */
+  skipTierPromotion?: boolean;
   /** Skip the embedding backfill step. Default: false. */
   skipEmbeddings?: boolean;
   /**
@@ -146,6 +158,7 @@ export async function runBrainMaintenance(
     skipDecay = false,
     skipConsolidation = false,
     skipReconciliation = false,
+    skipTierPromotion = false,
     skipEmbeddings = false,
     onProgress,
   } = options ?? {};
@@ -160,6 +173,7 @@ export async function runBrainMaintenance(
     observationsFixed: 0,
     linksRemoved: 0,
   };
+  const tierPromotionResult: BrainMaintenanceTierPromotionResult = { promoted: 0, evicted: 0 };
   const embeddingsResult: BrainMaintenanceEmbeddingsResult = {
     processed: 0,
     skipped: 0,
@@ -193,7 +207,17 @@ export async function runBrainMaintenance(
     onProgress?.('reconciliation', 1, 1);
   }
 
-  // Step 4: Embedding backfill (with per-item progress relay)
+  // Step 4: Tier promotion — promote short→medium and medium→long based on
+  // age, quality score, citation count, and verification status (T614).
+  if (!skipTierPromotion) {
+    onProgress?.('tier-promotion', 0, 1);
+    const raw = await runTierPromotion(projectRoot);
+    tierPromotionResult.promoted = raw.promoted.length;
+    tierPromotionResult.evicted = raw.evicted.length;
+    onProgress?.('tier-promotion', 1, 1);
+  }
+
+  // Step 5: Embedding backfill (with per-item progress relay)
   if (!skipEmbeddings) {
     const raw = await populateEmbeddings(projectRoot, {
       onProgress: (current, total) => {
@@ -209,6 +233,7 @@ export async function runBrainMaintenance(
     decay: decayResult,
     consolidation: consolidationResult,
     reconciliation: reconciliationResult,
+    tierPromotion: tierPromotionResult,
     embeddings: embeddingsResult,
     duration: Date.now() - startTime,
   };

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/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 ?? [] });
         }