qctl 0.0.2

Control in-repo YAML work queues
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"$id": "https://github.com/victor-software-house/qctl/blob/main/schema/tasks.schema.json",
	"title": "qctl work queue",
	"type": "object",
	"additionalProperties": false,
	"required": ["schema_version", "prefix", "active", "queue", "archive"],
	"properties": {
		"schema_version": {
			"const": 1,
			"description": "Ledger schema version. Increment only with a coordinated schema and ledger migration."
		},
		"prefix": {
			"type": "string",
			"pattern": "^[A-Z][A-Z0-9]{1,7}$",
			"description": "Stable ID prefix for this repository, such as PST, KAI, or OMX. Never encodes priority."
		},
		"active": {
			"description": "The one task currently being executed, or null when work is intentionally paused.",
			"oneOf": [{ "$ref": "#/$defs/taskId" }, { "type": "null" }]
		},
		"queue": {
			"type": "array",
			"description": "Pending work in priority order. Array order is the priority.",
			"items": { "$ref": "#/$defs/task" }
		},
		"archive": {
			"type": "array",
			"description": "Completed or deliberately dropped work, newest first. Archived IDs are never reused.",
			"items": { "$ref": "#/$defs/archiveTask" }
		},
		"horizon": {
			"type": "array",
			"description": "Mapped work that is not on the short-term queue: research, evaluations, or deferred items without a start condition. File order is not priority. active must never name a horizon id.",
			"items": { "$ref": "#/$defs/horizonTask" }
		}
	},
	"$defs": {
		"taskId": {
			"type": "string",
			"pattern": "^[A-Z][A-Z0-9]{1,7}-[0-9]{3,}$"
		},
		"nonEmptyString": {
			"type": "string",
			"minLength": 1
		},
		"nonEmptyStringList": {
			"type": "array",
			"items": { "$ref": "#/$defs/nonEmptyString" },
			"minItems": 1,
			"uniqueItems": true
		},
		"repoPath": {
			"type": "string",
			"pattern": "^(?!/)(?!.*\\.\\.).+\\.md$"
		},
		"task": {
			"type": "object",
			"additionalProperties": false,
			"required": ["id", "title", "scope", "outcome", "blocked_by", "acceptance"],
			"properties": {
				"id": { "$ref": "#/$defs/taskId" },
				"title": { "$ref": "#/$defs/nonEmptyString" },
				"scope": { "$ref": "#/$defs/nonEmptyString" },
				"outcome": { "$ref": "#/$defs/nonEmptyString" },
				"blocked_by": {
					"type": "array",
					"items": { "$ref": "#/$defs/taskId" },
					"uniqueItems": true
				},
				"acceptance": { "$ref": "#/$defs/nonEmptyStringList" },
				"patch": {
					"type": "string",
					"pattern": "^[a-z][a-z0-9-]*$"
				},
				"plan": { "$ref": "#/$defs/repoPath" },
				"links": {
					"type": "array",
					"items": { "type": "string", "format": "uri" },
					"uniqueItems": true
				},
				"notes": { "$ref": "#/$defs/nonEmptyString" }
			}
		},
		"archiveTask": {
			"type": "object",
			"additionalProperties": false,
			"required": ["id", "title", "scope", "completed", "outcome", "evidence"],
			"properties": {
				"id": { "$ref": "#/$defs/taskId" },
				"title": { "$ref": "#/$defs/nonEmptyString" },
				"scope": { "$ref": "#/$defs/nonEmptyString" },
				"completed": { "type": "string", "format": "date" },
				"outcome": { "$ref": "#/$defs/nonEmptyString" },
				"evidence": { "$ref": "#/$defs/nonEmptyStringList" },
				"patch": {
					"type": "string",
					"pattern": "^[a-z][a-z0-9-]*$"
				},
				"plan": { "$ref": "#/$defs/repoPath" },
				"links": {
					"type": "array",
					"items": { "type": "string", "format": "uri" },
					"uniqueItems": true
				},
				"notes": { "$ref": "#/$defs/nonEmptyString" },
				"disposition": {
					"type": "string",
					"enum": ["completed", "dropped"]
				}
			}
		},
		"horizonTask": {
			"type": "object",
			"additionalProperties": false,
			"required": ["id", "title", "scope", "outcome", "kind", "open"],
			"properties": {
				"id": { "$ref": "#/$defs/taskId" },
				"title": { "$ref": "#/$defs/nonEmptyString" },
				"scope": { "$ref": "#/$defs/nonEmptyString" },
				"outcome": { "$ref": "#/$defs/nonEmptyString" },
				"kind": {
					"type": "string",
					"enum": ["research", "evaluation", "deferred"],
					"description": "research = unknown facts; evaluation = known options, no start condition; deferred = start condition is explicit and not met."
				},
				"open": {
					"$ref": "#/$defs/nonEmptyString",
					"description": "The missing start condition or the question that keeps this off the queue."
				},
				"patch": {
					"type": "string",
					"pattern": "^[a-z][a-z0-9-]*$"
				},
				"plan": { "$ref": "#/$defs/repoPath" },
				"links": {
					"type": "array",
					"items": { "type": "string", "format": "uri" },
					"uniqueItems": true
				},
				"notes": { "$ref": "#/$defs/nonEmptyString" }
			}
		}
	}
}