@cleocode/cleo 2026.2.5

package/schemas/rcsd-hitl-resolution.schema.json

@@ -0,0 +1,216 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "schemaVersion": "1.0.0",
+  "$id": "https://cleo-dev.com/schemas/v1/rcsd-hitl-resolution.schema.json",
+  "title": "RCSD HITL Resolution",
+  "description": "Schema for RCSD human-in-the-loop resolution records. Captures the trigger, decision, reviewer, timestamps, and resulting pipeline actions.",
+  "type": "object",
+  "required": [
+    "$schema",
+    "hitlResolutionId",
+    "taskId",
+    "shortName",
+    "stage",
+    "trigger",
+    "decision",
+    "reviewer",
+    "timestamps",
+    "effects"
+  ],
+  "additionalProperties": false,
+
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://cleo-dev.com/schemas/v1/rcsd-hitl-resolution.schema.json",
+      "description": "Self-referencing schema URI for validation"
+    },
+    "hitlResolutionId": {
+      "type": "string",
+      "pattern": "^HR-\\d{3,}$",
+      "description": "Unique HITL resolution identifier (e.g., HR-001)"
+    },
+    "taskId": {
+      "type": "string",
+      "pattern": "^T\\d{3,}$",
+      "description": "Anchoring task ID (e.g., T500)"
+    },
+    "shortName": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]{3,25}$",
+      "description": "Kebab-case short name derived from task title"
+    },
+    "stage": {
+      "type": "string",
+      "enum": ["research", "consensus", "spec", "decompose"],
+      "description": "Pipeline stage where HITL intervention occurred"
+    },
+    "trigger": {
+      "type": "object",
+      "description": "Trigger details that required human review",
+      "required": ["reasonCode", "reasonText", "claimIds", "recommendations"],
+      "additionalProperties": false,
+      "properties": {
+        "reasonCode": {
+          "type": "string",
+          "minLength": 3,
+          "description": "Machine-readable reason code"
+        },
+        "reasonText": {
+          "type": "string",
+          "minLength": 10,
+          "description": "Human-readable explanation of the trigger"
+        },
+        "claimIds": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "description": "Claim IDs involved in the HITL request"
+        },
+        "recommendations": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/recommendation" },
+          "minItems": 1,
+          "description": "Recommended changes or actions"
+        }
+      }
+    },
+    "decision": {
+      "type": "object",
+      "description": "Decision taken by the human reviewer",
+      "required": ["selectedOptionId", "selectedOptionText", "requiresFollowupStage"],
+      "additionalProperties": false,
+      "properties": {
+        "selectedOptionId": {
+          "type": "string",
+          "minLength": 3,
+          "description": "Identifier for the selected option"
+        },
+        "selectedOptionText": {
+          "type": "string",
+          "minLength": 3,
+          "description": "Human-readable decision summary"
+        },
+        "justification": {
+          "type": "string",
+          "maxLength": 2000,
+          "description": "Optional justification for the decision"
+        },
+        "requiresFollowupStage": {
+          "type": "string",
+          "enum": ["research", "consensus", "spec", "decompose", "none"],
+          "description": "Stage that must be re-run as a result of the decision"
+        }
+      }
+    },
+    "reviewer": {
+      "type": "object",
+      "description": "Reviewer identity details",
+      "required": ["id", "displayName", "authProvider"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 3,
+          "description": "Reviewer ID (user or service)"
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Reviewer display name"
+        },
+        "authProvider": {
+          "type": "string",
+          "minLength": 2,
+          "description": "Authentication provider name"
+        }
+      }
+    },
+    "timestamps": {
+      "type": "object",
+      "description": "Creation and decision timestamps",
+      "required": ["createdAt", "decidedAt"],
+      "additionalProperties": false,
+      "properties": {
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "HITL request creation time (ISO 8601)"
+        },
+        "decidedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Decision time (ISO 8601)"
+        }
+      }
+    },
+    "effects": {
+      "type": "object",
+      "description": "Pipeline actions and artifacts produced by the decision",
+      "required": ["pipelineAction", "updates", "artifactLinks"],
+      "additionalProperties": false,
+      "properties": {
+        "pipelineAction": {
+          "type": "string",
+          "enum": ["resume", "pause", "rollback_to_stage"],
+          "description": "Pipeline action to take after decision"
+        },
+        "updates": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/updateOperation" },
+          "description": "Manifest or artifact updates applied as a result of the decision"
+        },
+        "artifactLinks": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative paths or filenames of artifacts affected"
+        }
+      }
+    }
+  },
+
+  "definitions": {
+    "recommendation": {
+      "type": "object",
+      "required": ["type", "priority", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "minLength": 3,
+          "description": "Recommendation type (e.g., spec-requirement)"
+        },
+        "priority": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"],
+          "description": "Recommendation priority"
+        },
+        "text": {
+          "type": "string",
+          "minLength": 3,
+          "description": "Recommendation text"
+        }
+      }
+    },
+    "updateOperation": {
+      "type": "object",
+      "required": ["target", "path", "value"],
+      "additionalProperties": false,
+      "properties": {
+        "target": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Target file or artifact to update"
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "JSON pointer or key path to update"
+        },
+        "value": {
+          "description": "Replacement value"
+        }
+      }
+    }
+  }
+}

package/schemas/rcsd-index.schema.json

@@ -0,0 +1,384 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "schemaVersion": "1.0.0",
+  "$id": "https://cleo-dev.com/schemas/v1/rcsd-index.schema.json",
+  "title": "RCSD Pipeline Master Index",
+  "description": "Master index for Research-Consensus-Spec-Decompose pipeline. Tracks all RCSD artifacts, task anchoring, authority mapping, and pipeline state. LLM-agent-first design.",
+  "type": "object",
+  "required": ["$schema", "_meta", "authorities", "taskAnchored", "specs", "reports"],
+  "additionalProperties": false,
+
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://cleo-dev.com/schemas/v1/rcsd-index.schema.json",
+      "description": "Self-referencing schema URI for validation"
+    },
+    "_meta": {
+      "type": "object",
+      "description": "Index metadata for version tracking, integrity, and summary statistics",
+      "required": ["version", "lastUpdated", "totals"],
+      "additionalProperties": false,
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Semantic version of the RCSD index format"
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of last index update"
+        },
+        "totals": {
+          "type": "object",
+          "description": "Aggregate counts for quick status queries",
+          "required": ["tasks", "specs", "reports", "activeResearch", "pendingConsensus"],
+          "additionalProperties": false,
+          "properties": {
+            "tasks": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total task-anchored RCSD directories"
+            },
+            "specs": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total generated specifications"
+            },
+            "reports": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total implementation reports"
+            },
+            "activeResearch": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Research operations currently in progress"
+            },
+            "pendingConsensus": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Research outputs awaiting consensus validation"
+            }
+          }
+        },
+        "checksum": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{16,64}$",
+          "description": "SHA-256 (truncated or full) for integrity verification"
+        }
+      }
+    },
+    "authorities": {
+      "type": "object",
+      "description": "Domain to authoritative specification mapping. Query: 'What is the authoritative source for domain X?'",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "type": "string",
+          "pattern": "^[A-Z0-9-]+\\.md$",
+          "description": "Filename of authoritative spec for this domain"
+        }
+      }
+    },
+    "taskAnchored": {
+      "type": "object",
+      "description": "Task ID to RCSD artifact mapping. Primary lookup for task-driven workflows.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^T\\d{3,}$": {
+          "$ref": "#/definitions/taskAnchor"
+        }
+      }
+    },
+    "specs": {
+      "type": "array",
+      "description": "All generated specification documents with metadata",
+      "items": {
+        "$ref": "#/definitions/specEntry"
+      }
+    },
+    "reports": {
+      "type": "array",
+      "description": "All implementation reports tracking spec progress",
+      "items": {
+        "$ref": "#/definitions/reportEntry"
+      }
+    },
+    "pipeline": {
+      "type": "object",
+      "description": "Active pipeline status tracking for in-flight operations",
+      "additionalProperties": false,
+      "properties": {
+        "activeOperations": {
+          "type": "array",
+          "description": "Currently running RCSD pipeline operations",
+          "items": {
+            "$ref": "#/definitions/pipelineOperation"
+          }
+        },
+        "queuedTasks": {
+          "type": "array",
+          "description": "Tasks queued for RCSD processing",
+          "items": {
+            "type": "string",
+            "pattern": "^T\\d{3,}$"
+          }
+        },
+        "lastCompleted": {
+          "type": "object",
+          "description": "Most recently completed pipeline run",
+          "additionalProperties": false,
+          "properties": {
+            "taskId": {
+              "type": "string",
+              "pattern": "^T\\d{3,}$"
+            },
+            "stage": {
+              "$ref": "#/definitions/pipelineStage"
+            },
+            "completedAt": {
+              "type": "string",
+              "format": "date-time"
+            }
+          }
+        }
+      }
+    },
+    "recentChanges": {
+      "type": "array",
+      "description": "Last 20 changes for audit trail and change tracking",
+      "maxItems": 20,
+      "items": {
+        "$ref": "#/definitions/changeEntry"
+      }
+    }
+  },
+
+  "definitions": {
+    "pipelineStage": {
+      "type": "string",
+      "enum": ["initialized", "research", "consensus", "spec", "decompose", "complete"],
+      "description": "RCSD pipeline stages: initialized (directory created), research (gathering sources), consensus (validating findings), spec (generating specification), decompose (creating subtasks), complete (pipeline finished)"
+    },
+    "taskAnchor": {
+      "type": "object",
+      "description": "Task-anchored RCSD artifact reference",
+      "required": ["shortName", "directory", "pipelineStage"],
+      "additionalProperties": false,
+      "properties": {
+        "shortName": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]{3,25}$",
+          "description": "Kebab-case identifier derived from task title"
+        },
+        "directory": {
+          "type": "string",
+          "pattern": "^T\\d{3,}_[a-z0-9-]+$",
+          "description": "Directory name: TXXX_short-name"
+        },
+        "spec": {
+          "type": "string",
+          "pattern": "^[A-Z0-9-]+-SPEC\\.md$",
+          "description": "Generated specification filename (if exists)"
+        },
+        "report": {
+          "type": "string",
+          "pattern": "^[A-Z0-9-]+-IMPLEMENTATION-REPORT\\.md$",
+          "description": "Implementation report filename (if exists)"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "paused", "completed", "failed", "archived"],
+          "description": "Current status of this RCSD artifact set"
+        },
+        "pipelineStage": {
+          "$ref": "#/definitions/pipelineStage"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When this task anchor was created"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Last modification timestamp"
+        }
+      }
+    },
+    "specEntry": {
+      "type": "object",
+      "description": "Specification document metadata",
+      "required": ["file", "version", "status", "domain", "taskId", "lastUpdated"],
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string",
+          "pattern": "^[A-Z0-9-]+-SPEC\\.md$",
+          "description": "Specification filename"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Semantic version of the specification"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["DRAFT", "APPROVED", "ACTIVE", "IMMUTABLE", "DEPRECATED"],
+          "description": "Document lifecycle status"
+        },
+        "domain": {
+          "type": "string",
+          "description": "Primary domain this spec covers"
+        },
+        "category": {
+          "type": "string",
+          "enum": ["core-system", "feature", "integration", "process", "enhancement"],
+          "description": "Organizational category"
+        },
+        "taskId": {
+          "type": "string",
+          "pattern": "^T\\d{3,}$",
+          "description": "Originating task ID"
+        },
+        "shortName": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]{3,25}$",
+          "description": "Short identifier for the spec"
+        },
+        "synopsis": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "One-sentence purpose summary"
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Last modification timestamp"
+        },
+        "consensusVerdict": {
+          "type": "string",
+          "enum": ["HIGH_CONFIDENCE", "MEDIUM_CONFIDENCE", "LOW_CONFIDENCE", "CONTESTED"],
+          "description": "Consensus validation outcome that generated this spec"
+        },
+        "implementationReport": {
+          "type": "string",
+          "pattern": "^[A-Z0-9-]+-IMPLEMENTATION-REPORT\\.md$",
+          "description": "Associated implementation report filename"
+        }
+      }
+    },
+    "reportEntry": {
+      "type": "object",
+      "description": "Implementation report metadata",
+      "required": ["file", "relatedSpec", "taskId", "progress", "lastUpdated"],
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string",
+          "pattern": "^[A-Z0-9-]+-IMPLEMENTATION-REPORT\\.md$",
+          "description": "Report filename"
+        },
+        "relatedSpec": {
+          "type": "string",
+          "pattern": "^[A-Z0-9-]+-SPEC\\.md$",
+          "description": "Specification this report tracks"
+        },
+        "taskId": {
+          "type": "string",
+          "pattern": "^T\\d{3,}$",
+          "description": "Originating task ID"
+        },
+        "progress": {
+          "type": "string",
+          "pattern": "^(\\d{1,3}%|\\d+/\\d+|Varies|N/A)$",
+          "description": "Progress indicator (percentage, fraction, or status)"
+        },
+        "phase": {
+          "type": "string",
+          "description": "Current implementation phase"
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Last modification timestamp"
+        },
+        "notes": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Brief status note"
+        }
+      }
+    },
+    "pipelineOperation": {
+      "type": "object",
+      "description": "Active pipeline operation tracking",
+      "required": ["operationId", "taskId", "stage", "startedAt"],
+      "additionalProperties": false,
+      "properties": {
+        "operationId": {
+          "type": "string",
+          "pattern": "^op_[a-f0-9]{8}$",
+          "description": "Unique operation identifier"
+        },
+        "taskId": {
+          "type": "string",
+          "pattern": "^T\\d{3,}$",
+          "description": "Task being processed"
+        },
+        "stage": {
+          "$ref": "#/definitions/pipelineStage"
+        },
+        "startedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When operation started"
+        },
+        "progress": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Completion percentage"
+        },
+        "message": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Current status message"
+        }
+      }
+    },
+    "changeEntry": {
+      "type": "object",
+      "description": "Audit trail entry for index changes",
+      "required": ["timestamp", "taskId", "changeType", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When change occurred"
+        },
+        "taskId": {
+          "type": "string",
+          "pattern": "^T\\d{3,}$",
+          "description": "Affected task ID"
+        },
+        "changeType": {
+          "type": "string",
+          "enum": ["Initialized", "ResearchComplete", "ConsensusComplete", "SpecGenerated", "ReportCreated", "StageAdvanced", "StatusChange", "Archived"],
+          "description": "Type of change"
+        },
+        "stage": {
+          "$ref": "#/definitions/pipelineStage"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Human-readable change description"
+        }
+      }
+    }
+  }
+}