joycraft 1.4.1 → 1.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -12
- package/dist/cli.js +24 -1
- package/dist/cli.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +9 -8
- package/payload/.agents/skills/joycraft-implement/SKILL.md +14 -11
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +6 -3
- package/payload/.agents/skills/joycraft-testing/SKILL.md +3 -3
- package/payload/.agents/skills/joycraft-verify/SKILL.md +15 -13
- package/payload/.claude/agents/joycraft-implementer.md +5 -5
- package/payload/.claude/agents/joycraft-reviewer.md +3 -6
- package/payload/.joycraft/contracts/types.d.ts +18 -0
- package/payload/.joycraft/references/completion.md +16 -21
- package/payload/.joycraft/references/gates.md +17 -17
- package/payload/.joycraft/references/testing.md +23 -23
- package/payload/.joycraft/runtime/completion.mjs +92 -6
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +1 -1
- package/payload/.joycraft/runtime/evidence.mjs +136 -0
- package/payload/.joycraft/runtime/gate.mjs +51 -13
- package/payload/.joycraft/runtime/identity.mjs +5 -1
- package/payload/.joycraft/runtime/queue-check.mjs +355 -0
- package/payload/.joycraft/runtime/status.mjs +45 -4
- package/payload/PIN +20 -19
|
@@ -0,0 +1,355 @@
|
|
|
1
|
+
import { existsSync, realpathSync } from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { pathToFileURL } from 'node:url';
|
|
4
|
+
import { briefDecisionRecords, isObject, localPath, parseJson, readLocal, relativePath, validateQueue } from './identity.mjs';
|
|
5
|
+
|
|
6
|
+
// Before the first dispatch, find the queue gaps a program can decide, so each
|
|
7
|
+
// goes back to the brief as a question while the user is present. It reports;
|
|
8
|
+
// it never blocks dispatch by itself. Checks that need judgment stay with the
|
|
9
|
+
// decompose skill. Dependencies are checked for the whole queue. A done spec
|
|
10
|
+
// is checked only for missing inputs, and only while the queue has a spec that
|
|
11
|
+
// is not done: an archived queue cites paths that have since moved.
|
|
12
|
+
|
|
13
|
+
const nextStep = 'Add it to the brief as an open decision and ask the user now.';
|
|
14
|
+
|
|
15
|
+
function legacySchema(queue) {
|
|
16
|
+
if (!isObject(queue)) return false;
|
|
17
|
+
const version = queue.schemaVersion;
|
|
18
|
+
if (version === undefined || version === null) return true;
|
|
19
|
+
if (typeof version === 'number') return version < 1;
|
|
20
|
+
return typeof version === 'string' && version.trim() !== '' && Number(version) < 1;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
// The heading id rule of identity.mjs: an explicit {#id}, else the slug of the title.
|
|
24
|
+
function heading(line) {
|
|
25
|
+
const match = /^ {0,3}(#{1,6})[ \t]+(.+?)[ \t]*$/.exec(line);
|
|
26
|
+
if (!match) return null;
|
|
27
|
+
const explicit = /\s+\{#([^}\s]+)\}\s*$/.exec(match[2]);
|
|
28
|
+
const title = (explicit ? match[2].slice(0, explicit.index) : match[2]).trim();
|
|
29
|
+
const slug = title.toLowerCase().replace(/[`*_~]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
|
|
30
|
+
return { level: match[1].length, id: explicit?.[1] ?? slug };
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const indentOf = line => line.replace(/\t/g, ' ').search(/\S/);
|
|
34
|
+
// A line with its first `column` columns of indentation removed.
|
|
35
|
+
const strip = (line, column) => line.replace(/\t/g, ' ').slice(Math.min(column, Math.max(indentOf(line), 0)));
|
|
36
|
+
// The opening run of a fence, as CommonMark reads it: up to three spaces of
|
|
37
|
+
// indentation, and no backtick after a backtick run (that is inline code).
|
|
38
|
+
function fenceMarker(line) {
|
|
39
|
+
const match = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
|
|
40
|
+
return match && !(match[1][0] === '`' && match[2].includes('`')) ? match[1] : null;
|
|
41
|
+
}
|
|
42
|
+
const listItem = line => /^( {0,3})([-*+]|\d{1,9}[.)])([ \t]+|$)/.exec(line.replace(/\t/g, ' '));
|
|
43
|
+
const contentColumn = item => item[1].length + item[2].length + (item[3].length > 4 || item[3].length === 0 ? 1 : item[3].length);
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Whether `Check:` appears in a bullet's plain text: not in a hidden line
|
|
47
|
+
* (fenced or indented code, a comment block), an inline code span or an HTML
|
|
48
|
+
* comment.
|
|
49
|
+
* Code spans follow CommonMark: a run of n backticks closes only at the next
|
|
50
|
+
* run of exactly n backticks in the same paragraph, and an unclosed run is
|
|
51
|
+
* plain text. A comment runs from `<!--` to `-->` across lines of one
|
|
52
|
+
* paragraph; an unclosed `<!--` is plain text. Whichever of the two opens
|
|
53
|
+
* first wins. Removed parts become a space.
|
|
54
|
+
*/
|
|
55
|
+
function plainCheck(lines) {
|
|
56
|
+
const text = lines.map(item => (item.hidden ? '\0' : item.line)).join('\n');
|
|
57
|
+
// A code span or an inline comment ends at a blank line or a hidden line.
|
|
58
|
+
const paragraphEnd = from => {
|
|
59
|
+
const blank = /\n[ \t]*\n/.exec(text.slice(from));
|
|
60
|
+
const ends = [text.indexOf('\0', from), blank ? from + blank.index : -1].filter(end => end >= 0);
|
|
61
|
+
return ends.length ? Math.min(...ends) : text.length;
|
|
62
|
+
};
|
|
63
|
+
let plain = '';
|
|
64
|
+
let at = 0;
|
|
65
|
+
while (at < text.length) {
|
|
66
|
+
// A backslash escape keeps the next character plain text.
|
|
67
|
+
if (text[at] === '\\' && /[!-\/:-@\[-`{-~]/.test(text[at + 1] ?? '')) { plain += text.slice(at, at + 2); at += 2; continue; }
|
|
68
|
+
if (text.startsWith('<!--', at)) {
|
|
69
|
+
const close = text.indexOf('-->', at + 2);
|
|
70
|
+
if (close >= 0 && close < paragraphEnd(at)) { at = close + 3; plain += ' '; continue; }
|
|
71
|
+
plain += '<!--';
|
|
72
|
+
at += 4;
|
|
73
|
+
continue;
|
|
74
|
+
}
|
|
75
|
+
if (text[at] === '`') {
|
|
76
|
+
const run = /^`+/.exec(text.slice(at))[0];
|
|
77
|
+
const limit = paragraphEnd(at);
|
|
78
|
+
const closer = new RegExp(`(?<!\`)${run}(?!\`)`, 'g');
|
|
79
|
+
closer.lastIndex = at + run.length;
|
|
80
|
+
const close = closer.exec(text);
|
|
81
|
+
if (close && close.index < limit) { at = close.index + run.length; plain += ' '; continue; }
|
|
82
|
+
plain += run;
|
|
83
|
+
at += run.length;
|
|
84
|
+
continue;
|
|
85
|
+
}
|
|
86
|
+
plain += text[at];
|
|
87
|
+
at += 1;
|
|
88
|
+
}
|
|
89
|
+
return /\bCheck:/.test(plain);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* The bullets of a spec's acceptance section, each with its first line,
|
|
94
|
+
* whether `Check:` appears anywhere in it (`hasCheck`) and whether it appears
|
|
95
|
+
* in plain text (`plainCheck`), which is what the queue check counts. The
|
|
96
|
+
* section is the first ATX heading outside fenced code whose id is
|
|
97
|
+
* `acceptance` (any level), up to the next heading of the same or a higher
|
|
98
|
+
* level; sub-headings inside it are part of it. A bullet is a top-level `-`,
|
|
99
|
+
* `*`, `+` or `1.` list item in that section. It holds the lines indented to
|
|
100
|
+
* its content column (nested bullets and code included), blank lines, and
|
|
101
|
+
* unindented text lines that directly follow one of its lines (lazy
|
|
102
|
+
* continuation). It ends at a sibling item, a heading, an unindented fence or
|
|
103
|
+
* comment block, or an unindented line after a blank line. A plain `Check:`
|
|
104
|
+
* anywhere in the bullet, nested items included, counts for it; a nested item
|
|
105
|
+
* needs no `Check:` of its own.
|
|
106
|
+
*
|
|
107
|
+
* Fenced code, comment blocks (a line that starts with `<!--` and has no
|
|
108
|
+
* `-->`) and indented code (four columns past the content column of the item
|
|
109
|
+
* it is in, after a blank line or a block) are hidden: no heading or bullet
|
|
110
|
+
* starts there, and a `Check:` there does not count. As in CommonMark, a block
|
|
111
|
+
* opened inside a bullet ends with the item it is in, closed or not, so it
|
|
112
|
+
* never hides a later bullet or heading. A block opened outside a bullet runs
|
|
113
|
+
* to its closing line or to the end of the file; when it is not closed, its
|
|
114
|
+
* line is returned as `unclosed`, because it hides the rest of the section.
|
|
115
|
+
*/
|
|
116
|
+
export function acceptanceBullets(text) {
|
|
117
|
+
const lines = String(text).replace(/^\uFEFF/, '').split(/\r?\n/);
|
|
118
|
+
let start = 0;
|
|
119
|
+
if (lines[0] === '---') {
|
|
120
|
+
const end = lines.indexOf('---', 1);
|
|
121
|
+
if (end > 0) start = end + 1;
|
|
122
|
+
}
|
|
123
|
+
// Each takes a line stripped to its container's content column.
|
|
124
|
+
const opener = line => fenceMarker(line) ?? (/^ {0,3}<!--/.test(line) && line.indexOf('-->', line.indexOf('<!--') + 2) < 0 ? '<!--' : null);
|
|
125
|
+
const closes = (marker, line) => {
|
|
126
|
+
if (marker === '<!--') return line.includes('-->');
|
|
127
|
+
const found = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line)?.[1];
|
|
128
|
+
return Boolean(found) && found[0] === marker[0] && found.length >= marker.length;
|
|
129
|
+
};
|
|
130
|
+
let section = null;
|
|
131
|
+
let current = null; // a bullet; `nest` holds the content columns of its open items
|
|
132
|
+
let block = null; // { marker, line, column }: column is the item's, or null outside a bullet
|
|
133
|
+
let previousBlank = false;
|
|
134
|
+
let afterBlock = false;
|
|
135
|
+
let indented = false;
|
|
136
|
+
const bullets = [];
|
|
137
|
+
const hide = line => current.lines.push({ line, hidden: true });
|
|
138
|
+
// A fence or comment block can open on an item's own line.
|
|
139
|
+
const openOnItem = (content, column) => {
|
|
140
|
+
const marker = opener(content);
|
|
141
|
+
if (marker) block = { marker, column };
|
|
142
|
+
return Boolean(marker);
|
|
143
|
+
};
|
|
144
|
+
for (let index = start; index < lines.length; index += 1) {
|
|
145
|
+
const line = lines[index];
|
|
146
|
+
const blank = line.trim() === '';
|
|
147
|
+
const indent = indentOf(line);
|
|
148
|
+
if (block && !(block.column !== null && !blank && indent < block.column)) {
|
|
149
|
+
if (closes(block.marker, strip(line, block.column ?? 0))) { block = null; afterBlock = true; }
|
|
150
|
+
if (current) hide(line);
|
|
151
|
+
continue;
|
|
152
|
+
}
|
|
153
|
+
// A less indented line ends the item, and the block opened inside it.
|
|
154
|
+
if (block) { block = null; if (current && indent < current.column) current = null; }
|
|
155
|
+
if (blank) { if (current) current.lines.push({ line, hidden: indented }); previousBlank = true; continue; }
|
|
156
|
+
const inside = current && indent >= current.column;
|
|
157
|
+
if (inside) while (current.nest.length > 1 && indent < current.nest.at(-1)) current.nest.pop();
|
|
158
|
+
const base = inside ? current.nest.at(-1) : 0;
|
|
159
|
+
indented = Boolean(inside && indent >= base + 4 && (previousBlank || afterBlock || indented));
|
|
160
|
+
afterBlock = false;
|
|
161
|
+
if (indented) { hide(line); previousBlank = false; continue; }
|
|
162
|
+
const stripped = strip(line, base);
|
|
163
|
+
const marker = opener(stripped);
|
|
164
|
+
if (marker) {
|
|
165
|
+
block = { marker, line: index + 1, column: inside ? base : null };
|
|
166
|
+
if (inside) hide(line); else current = null;
|
|
167
|
+
previousBlank = false;
|
|
168
|
+
continue;
|
|
169
|
+
}
|
|
170
|
+
const found = heading(line);
|
|
171
|
+
if (found) {
|
|
172
|
+
if (section && found.level <= section.level) break;
|
|
173
|
+
if (!section && found.id === 'acceptance') section = found;
|
|
174
|
+
current = null;
|
|
175
|
+
previousBlank = false;
|
|
176
|
+
continue;
|
|
177
|
+
}
|
|
178
|
+
const item = listItem(line);
|
|
179
|
+
if (item && !inside) {
|
|
180
|
+
const column = contentColumn(item);
|
|
181
|
+
const content = line.slice(item[0].length);
|
|
182
|
+
current = { line: index + 1, column, nest: [column], lines: [] };
|
|
183
|
+
current.lines.push({ line: content, hidden: openOnItem(content, column) });
|
|
184
|
+
if (section) bullets.push(current);
|
|
185
|
+
} else if (inside) {
|
|
186
|
+
const nested = listItem(stripped);
|
|
187
|
+
if (nested) current.nest.push(base + contentColumn(nested));
|
|
188
|
+
current.lines.push({ line, hidden: Boolean(nested) && openOnItem(stripped.slice(nested[0].length), current.nest.at(-1)) });
|
|
189
|
+
} else if (current && !previousBlank && !item) current.lines.push({ line, hidden: false });
|
|
190
|
+
else current = null;
|
|
191
|
+
previousBlank = false;
|
|
192
|
+
}
|
|
193
|
+
if (!section) return { section: false, bullets: [] };
|
|
194
|
+
return {
|
|
195
|
+
section: true,
|
|
196
|
+
unclosed: block && block.column === null ? block.line : null,
|
|
197
|
+
bullets: bullets.map(bullet => {
|
|
198
|
+
const joined = bullet.lines.map(item => item.line).join(' ').replace(/\s+/g, ' ').trim();
|
|
199
|
+
return { line: bullet.line, text: joined, hasCheck: /\bCheck:/.test(joined), plainCheck: plainCheck(bullet.lines) };
|
|
200
|
+
}),
|
|
201
|
+
};
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
function label(text) {
|
|
205
|
+
const sentence = /^.*?[.!?](?=\s|$)/.exec(text)?.[0] ?? text;
|
|
206
|
+
return sentence.length > 80 ? `${sentence.slice(0, 79)}…` : sentence;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
// Strongly connected groups of two or more specs, or one spec that names itself.
|
|
210
|
+
function dependencyCycles(edges) {
|
|
211
|
+
const order = new Map();
|
|
212
|
+
const low = new Map();
|
|
213
|
+
const stack = [];
|
|
214
|
+
const onStack = new Set();
|
|
215
|
+
const cycles = [];
|
|
216
|
+
let counter = 0;
|
|
217
|
+
const visit = id => {
|
|
218
|
+
order.set(id, counter); low.set(id, counter); counter += 1;
|
|
219
|
+
stack.push(id); onStack.add(id);
|
|
220
|
+
for (const next of edges.get(id)) {
|
|
221
|
+
if (!order.has(next)) { visit(next); low.set(id, Math.min(low.get(id), low.get(next))); }
|
|
222
|
+
else if (onStack.has(next)) low.set(id, Math.min(low.get(id), order.get(next)));
|
|
223
|
+
}
|
|
224
|
+
if (low.get(id) !== order.get(id)) return;
|
|
225
|
+
const group = [];
|
|
226
|
+
let member;
|
|
227
|
+
do { member = stack.pop(); onStack.delete(member); group.push(member); } while (member !== id);
|
|
228
|
+
if (group.length > 1 || edges.get(id).includes(id)) cycles.push(group.sort((a, b) => a - b));
|
|
229
|
+
};
|
|
230
|
+
for (const id of [...edges.keys()].sort((a, b) => a - b)) if (!order.has(id)) visit(id);
|
|
231
|
+
return cycles.sort((a, b) => a[0] - b[0]);
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
// One path around a cycle, from its lowest spec id, for the message.
|
|
235
|
+
function cyclePath(group, edges) {
|
|
236
|
+
const members = new Set(group);
|
|
237
|
+
const walk = [group[0]];
|
|
238
|
+
for (;;) {
|
|
239
|
+
const next = edges.get(walk.at(-1)).filter(id => members.has(id)).sort((a, b) => a - b)[0];
|
|
240
|
+
const seen = walk.indexOf(next);
|
|
241
|
+
if (seen >= 0) return [...walk.slice(seen), next];
|
|
242
|
+
walk.push(next);
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
const list = ids => ids.length === 1 ? `${ids[0]}` : `${ids.slice(0, -1).join(', ')} and ${ids.at(-1)}`;
|
|
247
|
+
|
|
248
|
+
/** The gaps in one queue that a program can decide; `skipped` when the queue predates schemaVersion 1. */
|
|
249
|
+
export function checkQueue({ root = process.cwd(), queuePath }) {
|
|
250
|
+
queuePath = relativePath(queuePath);
|
|
251
|
+
const queue = parseJson(readLocal(root, queuePath), queuePath);
|
|
252
|
+
if (legacySchema(queue)) {
|
|
253
|
+
return { queuePath, skipped: true, gaps: [],
|
|
254
|
+
message: `Joycraft queue check: skipped ${queuePath}; ${queue.schemaVersion == null ? 'it has no schemaVersion' : `its schemaVersion ${JSON.stringify(queue.schemaVersion)} predates 1`}.` };
|
|
255
|
+
}
|
|
256
|
+
const gaps = [];
|
|
257
|
+
const gap = (kind, specId, item, text) => gaps.push({ kind, specId, item, message: `Joycraft queue check: ${queuePath} ${text} ${nextStep}` });
|
|
258
|
+
|
|
259
|
+
// Unknown and circular dependencies are gaps, not a broken queue: report them
|
|
260
|
+
// and validate the rest of the queue without them.
|
|
261
|
+
const specs = Array.isArray(queue?.specs) ? queue.specs : [];
|
|
262
|
+
const ids = new Set(specs.filter(isObject).map(spec => spec.id));
|
|
263
|
+
const edges = new Map();
|
|
264
|
+
const checked = { ...queue, specs: specs.map(spec => {
|
|
265
|
+
if (!isObject(spec) || !Array.isArray(spec.depends_on)) return spec;
|
|
266
|
+
for (const id of spec.depends_on) {
|
|
267
|
+
if (Number.isSafeInteger(id) && !ids.has(id)) gap('unknown-dependency', spec.id, id, `spec ${spec.id} depends on spec ${id}, which is not in the queue.`);
|
|
268
|
+
}
|
|
269
|
+
edges.set(spec.id, spec.depends_on.filter(id => ids.has(id)));
|
|
270
|
+
return { ...spec, depends_on: spec.depends_on.filter(id => !Number.isSafeInteger(id) || (ids.has(id) && id !== spec.id)) };
|
|
271
|
+
}) };
|
|
272
|
+
validateQueue(checked, { select: spec => spec.status !== 'done' });
|
|
273
|
+
for (const group of dependencyCycles(edges)) {
|
|
274
|
+
gap('dependency-cycle', group[0], group, group.length === 1 ? `spec ${group[0]} depends on itself.`
|
|
275
|
+
: `specs ${list(group)} depend on each other in a cycle (${cyclePath(group, edges).join(' -> ')}).`);
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
const folder = path.posix.dirname(queuePath);
|
|
279
|
+
const briefPath = path.posix.join(path.posix.dirname(folder), 'brief.md');
|
|
280
|
+
const decisions = existsSync(localPath(root, briefPath, true)) ? briefDecisionRecords(readLocal(root, briefPath), briefPath) : [];
|
|
281
|
+
const open = decisions.filter(record => isObject(record) && record.status === 'open' && typeof record.id === 'string');
|
|
282
|
+
|
|
283
|
+
const unfinished = queue.specs.some(spec => spec.status !== 'done');
|
|
284
|
+
for (const spec of queue.specs) {
|
|
285
|
+
if (spec.status === 'done' && !unfinished) continue;
|
|
286
|
+
for (const input of spec.verification.inputs) {
|
|
287
|
+
const inputPath = relativePath(input.path);
|
|
288
|
+
// A declared check folder is a valid input, so this tests existence only.
|
|
289
|
+
if (input.state === 'absent' || existsSync(path.join(root, inputPath))) continue;
|
|
290
|
+
// As in implementer dispatch, a todo spec's missing code, check or
|
|
291
|
+
// fixture input is planned work, not a gap. A requirement must exist.
|
|
292
|
+
if (spec.status === 'todo' && input.kind !== 'requirement') continue;
|
|
293
|
+
gap('missing-input', spec.id, inputPath, `spec ${spec.id}: verification input ${inputPath} does not exist and is not declared state: 'absent'.`);
|
|
294
|
+
}
|
|
295
|
+
if (spec.status === 'done') continue;
|
|
296
|
+
const file = path.posix.join(folder, spec.file);
|
|
297
|
+
const at = `spec ${spec.id} (${file}`;
|
|
298
|
+
if (existsSync(localPath(root, file, true))) {
|
|
299
|
+
const { section, bullets, unclosed } = acceptanceBullets(readLocal(root, file).toString('utf8'));
|
|
300
|
+
if (!section || bullets.length === 0) gap('missing-check', spec.id, null, `${at}) has no acceptance bullet under an acceptance heading.`);
|
|
301
|
+
if (unclosed) gap('missing-check', spec.id, unclosed, `${at}:${unclosed}): a code fence or HTML comment opened here is never closed, so it hides the rest of the acceptance section.`);
|
|
302
|
+
for (const bullet of bullets) {
|
|
303
|
+
if (!bullet.hasCheck) gap('missing-check', spec.id, bullet.line, `${at}:${bullet.line}): the acceptance bullet "${label(bullet.text)}" has no \`Check:\`.`);
|
|
304
|
+
else if (!bullet.plainCheck) gap('missing-check', spec.id, bullet.line, `${at}:${bullet.line}): the acceptance bullet "${label(bullet.text)}" has a \`Check:\` only in code or a comment.`);
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
// The brief headings and decisions this spec cites: criterion anchors on
|
|
308
|
+
// the brief, and the anchors and decision ids of its scoped brief inputs.
|
|
309
|
+
// A brief input with no scope cites the whole brief.
|
|
310
|
+
const anchors = new Set();
|
|
311
|
+
const decisionIds = new Set();
|
|
312
|
+
let wholeBrief = false;
|
|
313
|
+
for (const criterion of spec.verification.criteria) {
|
|
314
|
+
if (relativePath(criterion.requirement.path) !== briefPath) continue;
|
|
315
|
+
const decision = /^frontmatter\.decisions\.([^.\s]+)$/.exec(criterion.requirement.anchor);
|
|
316
|
+
if (decision) decisionIds.add(decision[1]); else anchors.add(criterion.requirement.anchor);
|
|
317
|
+
}
|
|
318
|
+
for (const input of spec.verification.inputs) {
|
|
319
|
+
if (input.kind !== 'requirement' || relativePath(input.path) !== briefPath) continue;
|
|
320
|
+
if (input.scope === undefined) wholeBrief = true;
|
|
321
|
+
for (const anchor of input.scope?.anchors ?? []) anchors.add(anchor);
|
|
322
|
+
for (const id of input.scope?.decisionIds ?? []) decisionIds.add(id);
|
|
323
|
+
}
|
|
324
|
+
for (const decision of open) {
|
|
325
|
+
const affected = (Array.isArray(decision.affected) ? decision.affected : []).filter(anchor => anchors.has(anchor));
|
|
326
|
+
if (affected.length) gap('open-decision', spec.id, decision.id, `spec ${spec.id} cites heading ${list(affected.map(anchor => `"${anchor}"`))} of ${briefPath}, which open decision ${decision.id} affects.`);
|
|
327
|
+
else if (decisionIds.has(decision.id)) gap('open-decision', spec.id, decision.id, `spec ${spec.id} cites open decision ${decision.id} of ${briefPath}.`);
|
|
328
|
+
else if (wholeBrief) gap('open-decision', spec.id, decision.id, `spec ${spec.id} cites all of ${briefPath} (a brief input with no scope), which has open decision ${decision.id}.`);
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
return { queuePath, skipped: false, gaps };
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
export function main(argv = process.argv.slice(2)) {
|
|
335
|
+
const usage = 'Usage: queue-check.mjs --queue <queue> [--root <project>]';
|
|
336
|
+
const flags = {};
|
|
337
|
+
for (let index = 0; index < argv.length; index += 2) {
|
|
338
|
+
const name = argv[index];
|
|
339
|
+
const value = argv[index + 1];
|
|
340
|
+
if (!['--queue', '--root'].includes(name) || flags[name] !== undefined || typeof value !== 'string' || value.startsWith('--')) throw new Error(usage);
|
|
341
|
+
flags[name] = value;
|
|
342
|
+
}
|
|
343
|
+
if (flags['--queue'] === undefined) throw new Error(usage);
|
|
344
|
+
const result = checkQueue({ root: path.resolve(flags['--root'] ?? '.'), queuePath: flags['--queue'] });
|
|
345
|
+
const lines = result.skipped ? [result.message] : result.gaps.map(item => item.message);
|
|
346
|
+
if (lines.length) process.stderr.write(`${lines.join('\n')}\n`);
|
|
347
|
+
process.exitCode = result.gaps.length ? 2 : 0;
|
|
348
|
+
return result;
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
// Node runs the main module from its real path; compare with the real path of argv[1].
|
|
352
|
+
const invoked = (() => { try { return realpathSync(process.argv[1]); } catch { return null; } })();
|
|
353
|
+
if (invoked && import.meta.url === pathToFileURL(invoked).href) {
|
|
354
|
+
try { main(); } catch (error) { process.stderr.write(`Queue check stopped: ${error.message}\n`); process.exitCode = 1; }
|
|
355
|
+
}
|
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
import { existsSync, readdirSync, writeFileSync } from 'node:fs';
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import { pathToFileURL } from 'node:url';
|
|
4
|
-
import { journalPath } from './completion.mjs';
|
|
4
|
+
import { journalPath, visibleReports } from './completion.mjs';
|
|
5
5
|
import { workPaths } from './config.mjs';
|
|
6
|
-
import {
|
|
6
|
+
import { reviewRoundKey } from './dispatch-start.mjs';
|
|
7
|
+
import { briefDecisionRecords, isObject, localPath, nonempty, parseJson, readLocal, sha256, snapshot, specStatus, validateQueue } from './identity.mjs';
|
|
7
8
|
import { decide, listWorktrees } from './worktrees.mjs';
|
|
8
9
|
|
|
9
10
|
// The queue is the status authority; spec frontmatter mirrors it. This report
|
|
@@ -29,6 +30,41 @@ function openDecisions(root, folder) {
|
|
|
29
30
|
catch { return []; }
|
|
30
31
|
}
|
|
31
32
|
|
|
33
|
+
const findingsOf = (report, cls) => (Array.isArray(report?.findings) ? report.findings : []).filter(finding => isObject(finding) && finding.class === cls);
|
|
34
|
+
|
|
35
|
+
function question(feature, spec, finding, report) {
|
|
36
|
+
const optional = ['criterion', 'at', ...(finding.class === 'follow-up' ? ['assumption'] : [])].filter(key => nonempty(finding[key]));
|
|
37
|
+
return { feature, specId: spec.id, class: finding.class, id: finding.id, summary: finding.summary, ...Object.fromEntries(optional.map(key => [key, finding[key]])), report };
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** The follow-ups of a done spec's accepted report, from the queue's acceptedReport receipt. */
|
|
41
|
+
function followUps(root, feature, spec, unread) {
|
|
42
|
+
const receipt = spec.acceptedReport;
|
|
43
|
+
try {
|
|
44
|
+
const bytes = readLocal(root, receipt.path);
|
|
45
|
+
if (sha256(bytes) !== receipt.sha256) throw new Error('changed');
|
|
46
|
+
return findingsOf(parseJson(bytes, receipt.path), 'follow-up').map(finding => question(feature, spec, finding, receipt.path));
|
|
47
|
+
} catch {
|
|
48
|
+
unread.push({ feature, specId: spec.id, path: receipt.path, reason: 'The accepted report is missing or changed here, so its follow-ups cannot be listed.' });
|
|
49
|
+
return [];
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The decision-needed findings of an in-review spec's current report: the latest
|
|
54
|
+
* visible report whose reviewed inputs (reviewRoundKey) match the current ones. */
|
|
55
|
+
function heldDecisions(root, feature, queuePath, spec) {
|
|
56
|
+
const reports = visibleReports({ root, queuePath, specId: spec.id });
|
|
57
|
+
if (!reports.some(item => findingsOf(item.report, 'decision-needed').length)) return [];
|
|
58
|
+
let current;
|
|
59
|
+
try {
|
|
60
|
+
const receipts = reports.flatMap(item => (item.report.flows ?? []).flatMap(flow => (flow?.observations ?? []).flatMap(observation => (observation?.receipts ?? []).map(receipt => receipt?.path))));
|
|
61
|
+
current = reviewRoundKey(snapshot({ root, queuePath, specId: spec.id, artifactPaths: [journalPath(queuePath), ...reports.map(item => item.path), ...receipts.filter(nonempty)] }));
|
|
62
|
+
} catch { return []; }
|
|
63
|
+
const time = item => Date.parse(item.report.createdAt) || 0;
|
|
64
|
+
const latest = reports.filter(item => reviewRoundKey(item.report.subject) === current).sort((left, right) => time(left) - time(right)).at(-1);
|
|
65
|
+
return latest ? findingsOf(latest.report, 'decision-needed').map(finding => question(feature, spec, finding, latest.path)) : [];
|
|
66
|
+
}
|
|
67
|
+
|
|
32
68
|
function worktreeCounts(root) {
|
|
33
69
|
try {
|
|
34
70
|
const { trees } = listWorktrees({ root, sizes: false });
|
|
@@ -40,13 +76,16 @@ function worktreeCounts(root) {
|
|
|
40
76
|
} catch { return null; }
|
|
41
77
|
}
|
|
42
78
|
|
|
43
|
-
/** Report every queue's specs (in paths.features), drift between queue and frontmatter,
|
|
79
|
+
/** Report every queue's specs (in paths.features), drift between queue and frontmatter, features ready to archive,
|
|
80
|
+
* and the questions for the user: follow-ups of accepted reports and decision-needed findings of current reports. */
|
|
44
81
|
export function projectStatus({ root = process.cwd(), fix = false } = {}) {
|
|
45
82
|
const features = [];
|
|
46
83
|
const drift = [];
|
|
47
84
|
const fixed = [];
|
|
48
85
|
const readyToArchive = [];
|
|
49
86
|
const problems = [];
|
|
87
|
+
const questions = [];
|
|
88
|
+
const unreadReports = [];
|
|
50
89
|
for (const queuePath of queuePaths(root)) {
|
|
51
90
|
const folder = path.posix.dirname(path.posix.dirname(queuePath));
|
|
52
91
|
let queue;
|
|
@@ -71,12 +110,14 @@ export function projectStatus({ root = process.cwd(), fix = false } = {}) {
|
|
|
71
110
|
row.frontmatter = spec.status;
|
|
72
111
|
} else drift.push({ feature: queue.feature, specId: spec.id, file: specPath, queue: spec.status, frontmatter, fixable, reason });
|
|
73
112
|
}
|
|
113
|
+
if (spec.status === 'done' && isObject(spec.acceptedReport)) questions.push(...followUps(root, queue.feature, spec, unreadReports));
|
|
114
|
+
if (spec.status === 'in-review') questions.push(...heldDecisions(root, queue.feature, queuePath, spec));
|
|
74
115
|
return row;
|
|
75
116
|
});
|
|
76
117
|
features.push({ feature: queue.feature, queuePath, pendingJournal, specs });
|
|
77
118
|
if (queue.specs.every(spec => spec.status === 'done')) readyToArchive.push({ feature: queue.feature, folder, openDecisions: openDecisions(root, folder) });
|
|
78
119
|
}
|
|
79
|
-
return { features, drift, fixed, readyToArchive, worktrees: worktreeCounts(root), problems };
|
|
120
|
+
return { features, drift, fixed, readyToArchive, worktrees: worktreeCounts(root), problems, questions, unreadReports };
|
|
80
121
|
}
|
|
81
122
|
|
|
82
123
|
export async function main(argv = process.argv.slice(2)) {
|
package/payload/PIN
CHANGED
|
@@ -1,43 +1,43 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"source": "joycraft-prototype",
|
|
4
|
-
"tag": "field-
|
|
5
|
-
"commit": "
|
|
4
|
+
"tag": "field-22",
|
|
5
|
+
"commit": "96c591fe5dfe7c8c039182ba1ae1647f5dd62e88",
|
|
6
6
|
"files": {
|
|
7
7
|
".agents/skills/joycraft-cleanup/SKILL.md": "99ce785e551be33412ac7a99ce44585a9b2be4440617caac273680383b4f7057",
|
|
8
8
|
".agents/skills/joycraft-context/SKILL.md": "8eb9374846b8f0d99280217b3fc73cfddac97d72f3ff6f3aca4a86af58dd8b85",
|
|
9
|
-
".agents/skills/joycraft-decompose/SKILL.md": "
|
|
9
|
+
".agents/skills/joycraft-decompose/SKILL.md": "53519b5fc73c4b668256fc21d044df16544a4ff46eeb63d21c83c53df4bb8061",
|
|
10
10
|
".agents/skills/joycraft-entry/SKILL.md": "2d9c665416715fb9adb389f57c9d2da97d3d59f577ca4caae9539c6b98cff83b",
|
|
11
|
-
".agents/skills/joycraft-implement/SKILL.md": "
|
|
11
|
+
".agents/skills/joycraft-implement/SKILL.md": "368b882691c7c92af3f97be4c5c5e1b2fc6d88605a60a26080b1d72ba5492770",
|
|
12
12
|
".agents/skills/joycraft-retro/SKILL.md": "156f36cb047604c734bf273bd02822d964b6af86619ed6c2a30fa6d79eb9a986",
|
|
13
13
|
".agents/skills/joycraft-retro/agents/openai.yaml": "f0eb4732261635f41e08f0bbe9a931d62fd8ac645149d3406e6fc7e16a81750b",
|
|
14
|
-
".agents/skills/joycraft-session-end/SKILL.md": "
|
|
15
|
-
".agents/skills/joycraft-testing/SKILL.md": "
|
|
14
|
+
".agents/skills/joycraft-session-end/SKILL.md": "6380eee962648cfda8fdd9335576ce2e55b66cdebec944952b89f73cecefe144",
|
|
15
|
+
".agents/skills/joycraft-testing/SKILL.md": "3cb0a338b41e4d55ee8f097c0e06429e9e97679393695facaf36890ea30c43ba",
|
|
16
16
|
".agents/skills/joycraft-ui-slice/SKILL.md": "baf394edc4a31e582cb936c525d8ad28bea42a713ec3114f5921fa7e2bff833f",
|
|
17
17
|
".agents/skills/joycraft-ui-slice/scripts/serve.mjs": "c16858800b6fbe6f7a3a21b21e785ad70c9a89a3fe970bc08701fefeac5042fa",
|
|
18
|
-
".agents/skills/joycraft-verify/SKILL.md": "
|
|
19
|
-
".claude/agents/joycraft-implementer.md": "
|
|
20
|
-
".claude/agents/joycraft-reviewer.md": "
|
|
18
|
+
".agents/skills/joycraft-verify/SKILL.md": "7c2bda71d24bfe19ef4366873f55ffe14509db288081d89381db5dca93e7da0a",
|
|
19
|
+
".claude/agents/joycraft-implementer.md": "4b19bb2a12a1028e5d30376e917b8d1264d239c66af47a324b30ae5080b6391b",
|
|
20
|
+
".claude/agents/joycraft-reviewer.md": "7ac0f6835a59f09bb71d6d22773ba6df27e70fe267bac5bad95ead55d10c7da3",
|
|
21
21
|
".joycraft/assets/artifacts/kit.css": "9c19cc52f16eb1d1beb6222ec4e206c567daf9952ff1f5597ea4d6050b72125a",
|
|
22
22
|
".joycraft/assets/artifacts/kit.js": "c60ae4441fb20146677313b27f949598889f40e8b90167b70db04f997854966d",
|
|
23
23
|
".joycraft/assets/artifacts/transports.js": "318e97895468b47f07febc913d3a6e100b0ad19b78b3a4fc51bebc488e67c25d",
|
|
24
|
-
".joycraft/contracts/types.d.ts": "
|
|
24
|
+
".joycraft/contracts/types.d.ts": "61b26f3f0e0a68b867daff1f6be2a0ad236367c5b2652ad55c5ca7252052f939",
|
|
25
25
|
".joycraft/references/architecture.md": "4e225ba23ed72d3d7b1af9bfceeb708583eede79978c294724b917ad94674be9",
|
|
26
26
|
".joycraft/references/archive.md": "e9e662096f9e95d132c29e07d1a2624ca0826b5e9c1042f411e4ea2bf3805b67",
|
|
27
27
|
".joycraft/references/artifacts.md": "7fab219f6d6d8b23ef3b44a509f637b085b551b34f28622d6dc1167a7f484c6a",
|
|
28
28
|
".joycraft/references/cleanup.md": "aa784c63442a289c67de359d82c78abca3aa8cab5b5e2d91fcd731b45c209003",
|
|
29
|
-
".joycraft/references/completion.md": "
|
|
29
|
+
".joycraft/references/completion.md": "8b4f2873ec56581042ad160d3da26414c4dbabfd777e8b315fee4ab1204c8b7c",
|
|
30
30
|
".joycraft/references/context.md": "b94dd48a427aaafe826116bac100375cbae565b1ba3239fd7812c56eac724577",
|
|
31
31
|
".joycraft/references/delivery.md": "1afc417ee3922ebf5e84c0ae87796d6cb6305679c0257ed38a35f396949de5e8",
|
|
32
32
|
".joycraft/references/dispatch.md": "62e8ad3abf4700f63963fb21a17d03569b78b5100538c10bc37d559679db39b8",
|
|
33
33
|
".joycraft/references/doc-cleanup-LICENSE.md": "a9e210590e2d0ebf719fe3801f1c0fda8f940af28656ff36e908c4315d94f886",
|
|
34
|
-
".joycraft/references/gates.md": "
|
|
34
|
+
".joycraft/references/gates.md": "121a8b7deffb913cebf28f7cd042707a65e45aac7d99f1f2196f4113f1dbf10d",
|
|
35
35
|
".joycraft/references/knowledge.md": "a08a117a5d0ae65a45dfd8ab3f3da92dd3c7aeedaa09ae1d71ddf3d6528c7f95",
|
|
36
36
|
".joycraft/references/recurring-failures.md": "7080f6c55492bc19c2897f4f0b128a830a71cdb516678c79ff6e97ffa1dc6b86",
|
|
37
37
|
".joycraft/references/retro.md": "5f24b942f1faf308308caf5d0c543320fedbb69c59c2c240ef979cab50bae211",
|
|
38
38
|
".joycraft/references/settings.md": "efaa8ea977d7dab9ec011dc0f83f652eb0e7f0098994a89d2d0ee07027b137d6",
|
|
39
39
|
".joycraft/references/setup.md": "993ae51a753f5d55e13452787fc3f4bfd3df930e0c29730331639007e2ac4812",
|
|
40
|
-
".joycraft/references/testing.md": "
|
|
40
|
+
".joycraft/references/testing.md": "670727cc155e03e07c0b3734f25865b88d15b8d601f940a8b6b4e8b642004888",
|
|
41
41
|
".joycraft/references/update.md": "36af36ab3d47b5ea46a8f71090333771e5e1deaa6ca19739a75c9fd4aea14eba",
|
|
42
42
|
".joycraft/references/workflow.md": "5b330debc6759b8f7975b159632f51074802067291fe4f4bebfb344f5b60cc52",
|
|
43
43
|
".joycraft/references/worktrees.md": "ad5645d2811e59da682c03f1cbdd1fb15abcc094fba74542c848548033890dba",
|
|
@@ -49,25 +49,26 @@
|
|
|
49
49
|
".joycraft/runtime/artifacts/render.mjs": "488673cab94fa6bfde223c2c41650f8e183f7ac0be3840d371ee057d95ea0fa5",
|
|
50
50
|
".joycraft/runtime/artifacts/server.mjs": "0c787812ffbea22c3edb7cb7281e95f54e44da4361f57ac9906487e7b5e6f8e9",
|
|
51
51
|
".joycraft/runtime/cleanup.mjs": "9a10dfd27c12f807c71f407352f1526fdb9b4632c523a965952f65d1b7af158c",
|
|
52
|
-
".joycraft/runtime/completion.mjs": "
|
|
52
|
+
".joycraft/runtime/completion.mjs": "9f54cec1bfe64a6101a72cd88f51d682fb2359333e63a6c272f3469214094d21",
|
|
53
53
|
".joycraft/runtime/config.mjs": "72a536f3453dd73f65fdc243e2a13b562eee5a7ba59528adca4bde684307036a",
|
|
54
54
|
".joycraft/runtime/context/cli.mjs": "40adc206c8c3b7f4f5bedffb097d9ae1b0718f0586a055796e4987e9c3088eee",
|
|
55
55
|
".joycraft/runtime/context/index.mjs": "5a69d33d9a1a66ef23301e952ecb1ec427ff4b0baf408ede67a2600d3f2a173c",
|
|
56
56
|
".joycraft/runtime/context/search.mjs": "e32a42ba9b168ca7c68fed46d47a79250c27aa4c07c0835feae084b5d1e0d0ca",
|
|
57
57
|
".joycraft/runtime/coordinator.mjs": "9252a40ee3a82808a780158427b02129d8075679ed329bce2dd74168c7eb42ab",
|
|
58
58
|
".joycraft/runtime/delivery.mjs": "4fe897714eec33b24003f0d69abe1522a5199193ab7333fa6421776ee048df1c",
|
|
59
|
-
".joycraft/runtime/dispatch-preflight.mjs": "
|
|
59
|
+
".joycraft/runtime/dispatch-preflight.mjs": "75c895e4deb789f3bfe87a1be585f5537cea024b866e86a72949685e4860e228",
|
|
60
60
|
".joycraft/runtime/dispatch-start.mjs": "fd3654e78cd5db9ada013ed95ea9259d53725e41bcee399ce2cb1a7d9e54a579",
|
|
61
|
-
".joycraft/runtime/evidence.mjs": "
|
|
62
|
-
".joycraft/runtime/gate.mjs": "
|
|
63
|
-
".joycraft/runtime/identity.mjs": "
|
|
61
|
+
".joycraft/runtime/evidence.mjs": "73ac553964f3a57866412217f5c999fc788e8675a9d60322ae4977362931e46c",
|
|
62
|
+
".joycraft/runtime/gate.mjs": "9b8c34b8f229f89896c0a645a19e8470a1e69b1bcf95e9ce61414dc35f6bbc03",
|
|
63
|
+
".joycraft/runtime/identity.mjs": "88c571e82dbf003754a8b621f49ec333a31e90c82be41cf6469af5aaae5432fe",
|
|
64
64
|
".joycraft/runtime/kickoff.mjs": "9d96998bff94662863182b9a922f26732c649b7a0b0130b6da7d63ec73eb3590",
|
|
65
|
+
".joycraft/runtime/queue-check.mjs": "1b93157d1c64d6b90a15baeff1b652fb9ec273d873402390d1c8c8c3ac8a0dbd",
|
|
65
66
|
".joycraft/runtime/redact.mjs": "cc8c0fe5e8d8fe78116ef126f6eee757a247739084e19c342bcf09a2b06524bc",
|
|
66
67
|
".joycraft/runtime/retro.mjs": "6f3664b0d50c12d4f2d8eef4b4d0d62897939d03e45860d4dcf35c0f5f92677c",
|
|
67
68
|
".joycraft/runtime/review-tools.json": "e0b0f5625654bba5f02d49710356aa1740fd42dd282eef6a29af361396915763",
|
|
68
69
|
".joycraft/runtime/review-tools.mjs": "15d426558a3884628147debb29136a20f746c3f184c52d6474ad59c222e5d8d5",
|
|
69
70
|
".joycraft/runtime/scope.mjs": "e2cdd929596246bf24e18850698db440119badc7068a3c5beab03ded45abbd65",
|
|
70
|
-
".joycraft/runtime/status.mjs": "
|
|
71
|
+
".joycraft/runtime/status.mjs": "404b85422275c23ec0c706128370f51b5b4a89b33e815e7e6156efe4f5ded73f",
|
|
71
72
|
".joycraft/runtime/trace.mjs": "b7924f759b07991f4135698df9c32654631a325957f0f8de5c2ca1262c0a836a",
|
|
72
73
|
".joycraft/runtime/update-check.mjs": "987b65605a26ea71b6417fda7b48753980e0d8afa20eadbd527143850a93319e",
|
|
73
74
|
".joycraft/runtime/wiring.mjs": "e08bcc604d40560f260edbc3499a4481a1efa7c7d2fa80545caa858827404667",
|