@cleocode/core 2026.3.45 → 2026.3.47

package/schemas/archive.schema.json

@@ -0,0 +1,450 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cleo-dev.com/schemas/v3.1/archive.schema.json",
+  "schemaVersion": "2.4.0",
+  "title": "CLEO Archive Schema",
+  "description": "Storage for completed and cancelled tasks. Archived tasks are IMMUTABLE - never modify after archival.",
+  "type": "object",
+  "required": [
+    "version",
+    "project",
+    "archivedTasks",
+    "_meta"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Legacy schema version field (deprecated, use _meta.schemaVersion)"
+    },
+    "project": {
+      "type": "string",
+      "description": "Project identifier. Must match todo.json project."
+    },
+    "_meta": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "totalArchived",
+        "lastArchived"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Schema version for this file (semver). Canonical source for schema version (replaces root version field)."
+        },
+        "totalArchived": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total count of archived tasks."
+        },
+        "lastArchived": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "Timestamp of most recent archival operation."
+        },
+        "oldestTask": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "Completion date of oldest archived task."
+        },
+        "newestTask": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "Completion date of newest archived task."
+        },
+        "lastUnarchived": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "Timestamp of most recent unarchive/restore operation."
+        },
+        "totalUnarchived": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Total count of tasks restored from archive."
+        }
+      }
+    },
+    "archivedTasks": {
+      "type": "array",
+      "description": "Completed tasks moved from todo.json. IMMUTABLE after archival.",
+      "items": {
+        "$ref": "#/definitions/archivedTask"
+      }
+    },
+    "phaseSummary": {
+      "type": "object",
+      "description": "Aggregated phase completion statistics from archived tasks.",
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "type": "object",
+          "properties": {
+            "totalTasks": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total tasks archived from this phase."
+            },
+            "firstCompleted": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "format": "date-time",
+              "description": "Earliest completion timestamp in this phase."
+            },
+            "lastCompleted": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "format": "date-time",
+              "description": "Latest completion timestamp in this phase."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "statistics": {
+      "type": "object",
+      "description": "Computed statistics. Regenerate on archive operations.",
+      "properties": {
+        "cancelled": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Total count of cancelled tasks archived."
+        },
+        "byPhase": {
+          "type": "object",
+          "description": "Task counts by phase.",
+          "patternProperties": {
+            "^[a-z][a-z0-9-]*$": {
+              "type": "integer"
+            }
+          }
+        },
+        "byPriority": {
+          "type": "object",
+          "description": "Task counts by priority.",
+          "properties": {
+            "critical": {
+              "type": "integer"
+            },
+            "high": {
+              "type": "integer"
+            },
+            "medium": {
+              "type": "integer"
+            },
+            "low": {
+              "type": "integer"
+            }
+          }
+        },
+        "byLabel": {
+          "type": "object",
+          "description": "Task counts by label.",
+          "patternProperties": {
+            "^[a-z][a-z0-9-]*$": {
+              "type": "integer"
+            }
+          }
+        },
+        "averageCycleTime": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "description": "Average days from creation to completion."
+        }
+      }
+    }
+  },
+  "definitions": {
+    "archivedTask": {
+      "type": "object",
+      "required": [
+        "id",
+        "title",
+        "status",
+        "priority",
+        "createdAt",
+        "completedAt",
+        "_archive"
+      ],
+      "additionalProperties": false,
+      "description": "Archived task with original data plus archive metadata.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^T\\d{3,}$"
+        },
+        "title": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "done",
+            "cancelled"
+          ]
+        },
+        "priority": {
+          "type": "string",
+          "enum": [
+            "critical",
+            "high",
+            "medium",
+            "low"
+          ]
+        },
+        "phase": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "acceptance": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "depends": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "notes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "labels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "completedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "cancelledAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "cancellationReason": {
+          "type": "string",
+          "minLength": 5,
+          "maxLength": 300,
+          "pattern": "^[^`$;|&<>]*$"
+        },
+        "_archive": {
+          "type": "object",
+          "required": [
+            "archivedAt",
+            "reason"
+          ],
+          "additionalProperties": false,
+          "description": "Archive metadata added during archival.",
+          "properties": {
+            "archivedAt": {
+              "type": "string",
+              "format": "date-time",
+              "description": "When this task was archived."
+            },
+            "reason": {
+              "type": "string",
+              "enum": [
+                "auto",
+                "manual",
+                "stale",
+                "force",
+                "cascade",
+                "phase-complete",
+                "label-policy",
+                "cancelled"
+              ],
+              "description": "Archival trigger: auto=config rules, manual=user request, stale=exceeded retention, force=forced archive, cascade=parent archived, phase-complete=phase finished, label-policy=label rule matched, cancelled=task was cancelled/soft-deleted."
+            },
+            "sessionId": {
+              "type": "string",
+              "description": "Session that performed the archival."
+            },
+            "cycleTimeDays": {
+              "type": "number",
+              "description": "Days from creation to completion."
+            },
+            "archiveSource": {
+              "type": "string",
+              "enum": [
+                "auto",
+                "manual",
+                "force",
+                "all",
+                "cascade",
+                "phase-trigger",
+                "unarchive-restore"
+              ],
+              "description": "How the archive operation was initiated: auto=automatic config rules, manual=user-initiated single task, force=forced regardless of state, all=bulk archive all eligible, cascade=triggered by parent archive, phase-trigger=phase completion triggered, unarchive-restore=metadata preserved from restore operation."
+            },
+            "triggerDetails": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Details about what triggered the archive operation.",
+              "properties": {
+                "phase": {
+                  "type": "string",
+                  "description": "Phase that triggered the archive (if phase-triggered)."
+                },
+                "parentId": {
+                  "type": "string",
+                  "pattern": "^T\\d{3,}$",
+                  "description": "Parent task ID that triggered cascade archive."
+                },
+                "configRule": {
+                  "type": "string",
+                  "description": "Name or identifier of the config rule that matched."
+                },
+                "labelPolicy": {
+                  "type": "string",
+                  "description": "Label policy name that triggered the archive."
+                }
+              }
+            },
+            "relationshipState": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "State of task relationships at archive time for restoration.",
+              "properties": {
+                "hadChildren": {
+                  "type": "boolean",
+                  "description": "Whether this task had child tasks at archive time."
+                },
+                "childIds": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^T\\d{3,}$"
+                  },
+                  "description": "IDs of child tasks that were archived with this task."
+                },
+                "hadDependents": {
+                  "type": "boolean",
+                  "description": "Whether other tasks depended on this task at archive time."
+                },
+                "dependentIds": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^T\\d{3,}$"
+                  },
+                  "description": "IDs of tasks that depended on this task."
+                },
+                "parentId": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "pattern": "^T\\d{3,}$",
+                  "description": "Parent task ID if this was a child task, null if root."
+                }
+              }
+            },
+            "restoreInfo": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Information for potential restoration of this task.",
+              "properties": {
+                "originalStatus": {
+                  "type": "string",
+                  "enum": [
+                    "pending",
+                    "active",
+                    "blocked",
+                    "done"
+                  ],
+                  "description": "Task status before it was completed (for restoration context)."
+                },
+                "canRestore": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Whether this task can be safely restored."
+                },
+                "restoreBlockers": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Reasons why restoration might fail or require manual intervention."
+                }
+              }
+            },
+            "cancellationDetails": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Details about task cancellation. Present when reason='cancelled'.",
+              "properties": {
+                "cancelledAt": {
+                  "type": "string",
+                  "format": "date-time",
+                  "description": "ISO 8601 timestamp when the task was cancelled."
+                },
+                "cancellationReason": {
+                  "type": "string",
+                  "minLength": 5,
+                  "maxLength": 300,
+                  "description": "User-provided reason for cancellation."
+                },
+                "cancelledBy": {
+                  "type": "string",
+                  "description": "Session ID or user that performed the cancellation."
+                },
+                "previousStatus": {
+                  "type": "string",
+                  "enum": [
+                    "pending",
+                    "active",
+                    "blocked"
+                  ],
+                  "description": "Task status before cancellation."
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/brain-decision.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cleo-dev.com/schemas/v1/brain-decision.schema.json",
+  "schemaVersion": "1.0.0",
+  "title": "CLEO BRAIN Decision Memory Schema",
+  "description": "Schema for decision memory entries. Runtime store is SQLite (brain_decisions table). JSONL format is used for export/import portability. See ADR-009 Section 3.2.",
+  "type": "object",
+  "required": ["id", "type", "decision", "rationale", "confidence", "createdAt"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^D\\d+$",
+      "description": "Decision identifier (e.g., 'D001')."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["architecture", "technical", "process", "strategic", "tactical"],
+      "description": "Category of the decision."
+    },
+    "decision": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The decision statement."
+    },
+    "rationale": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Why this decision was made."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["low", "medium", "high"],
+      "description": "Confidence level in the decision."
+    },
+    "outcome": {
+      "type": ["string", "null"],
+      "enum": ["success", "failure", "mixed", "pending", null],
+      "description": "Observed outcome of the decision. Null if not yet evaluated."
+    },
+    "alternatives": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Alternative approaches that were considered."
+    },
+    "contextEpicId": {
+      "type": ["string", "null"],
+      "description": "Epic ID this decision relates to."
+    },
+    "contextTaskId": {
+      "type": ["string", "null"],
+      "description": "Task ID this decision relates to."
+    },
+    "contextPhase": {
+      "type": ["string", "null"],
+      "description": "Lifecycle phase when the decision was made."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the decision was recorded."
+    },
+    "updatedAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last update."
+    }
+  }
+}

package/schemas/brain-learning.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cleo-dev.com/schemas/v1/brain-learning.schema.json",
+  "schemaVersion": "1.0.0",
+  "title": "CLEO BRAIN Learning Memory Schema",
+  "description": "Schema for learning memory entries. Runtime store is SQLite (brain_learnings table). JSONL format is used for export/import portability. See ADR-009 Section 3.2.",
+  "type": "object",
+  "required": ["id", "insight", "source", "confidence", "createdAt"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^L\\d+$",
+      "description": "Learning identifier (e.g., 'L001')."
+    },
+    "insight": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The learned insight."
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Source of the insight (e.g., task completion analysis, blocker patterns)."
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0,
+      "description": "Confidence score (0.0-1.0) in the insight."
+    },
+    "actionable": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether this insight has a concrete actionable recommendation."
+    },
+    "application": {
+      "type": ["string", "null"],
+      "description": "How to apply this insight in future work."
+    },
+    "applicableTypes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Task types this insight applies to."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the learning was recorded."
+    },
+    "updatedAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last update."
+    }
+  }
+}

package/schemas/brain-pattern.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cleo-dev.com/schemas/v1/brain-pattern.schema.json",
+  "schemaVersion": "1.0.0",
+  "title": "CLEO BRAIN Pattern Memory Schema",
+  "description": "Schema for pattern memory entries. Runtime store is SQLite (brain_patterns table). JSONL format is used for export/import portability. See ADR-009 Section 3.2.",
+  "type": "object",
+  "required": ["id", "type", "pattern", "context", "extractedAt"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^P\\d+$",
+      "description": "Pattern identifier (e.g., 'P001')."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["workflow", "blocker", "success", "failure", "optimization"],
+      "description": "Category of the pattern."
+    },
+    "pattern": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Description of the observed pattern."
+    },
+    "context": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Context in which the pattern was observed."
+    },
+    "frequency": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1,
+      "description": "Number of times this pattern has been observed."
+    },
+    "successRate": {
+      "type": ["number", "null"],
+      "minimum": 0.0,
+      "maximum": 1.0,
+      "description": "Success rate for workflow patterns (0.0-1.0)."
+    },
+    "impact": {
+      "type": ["string", "null"],
+      "enum": ["low", "medium", "high", null],
+      "description": "Impact level of the pattern."
+    },
+    "antiPattern": {
+      "type": ["string", "null"],
+      "description": "The anti-pattern to avoid, if applicable."
+    },
+    "mitigation": {
+      "type": ["string", "null"],
+      "description": "Recommended mitigation for blocker/failure patterns."
+    },
+    "examples": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Task IDs that exemplify this pattern."
+    },
+    "extractedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the pattern was first extracted."
+    },
+    "updatedAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last update."
+    }
+  }
+}