joycraft 1.3.0 → 1.5.0

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.
Files changed (33) hide show
  1. package/README.md +154 -4
  2. package/dist/joycraft-release.json +1 -1
  3. package/package.json +3 -3
  4. package/payload/.agents/skills/joycraft-context/SKILL.md +5 -6
  5. package/payload/.agents/skills/joycraft-decompose/SKILL.md +9 -8
  6. package/payload/.agents/skills/joycraft-entry/SKILL.md +8 -19
  7. package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -17
  8. package/payload/.agents/skills/joycraft-session-end/SKILL.md +10 -15
  9. package/payload/.agents/skills/joycraft-testing/SKILL.md +3 -9
  10. package/payload/.agents/skills/joycraft-verify/SKILL.md +20 -21
  11. package/payload/.claude/agents/joycraft-implementer.md +5 -5
  12. package/payload/.claude/agents/joycraft-reviewer.md +3 -6
  13. package/payload/.joycraft/contracts/types.d.ts +18 -0
  14. package/payload/.joycraft/references/architecture.md +2 -4
  15. package/payload/.joycraft/references/completion.md +16 -21
  16. package/payload/.joycraft/references/context.md +11 -34
  17. package/payload/.joycraft/references/dispatch.md +7 -40
  18. package/payload/.joycraft/references/gates.md +60 -0
  19. package/payload/.joycraft/references/retro.md +6 -15
  20. package/payload/.joycraft/references/settings.md +6 -3
  21. package/payload/.joycraft/references/setup.md +4 -4
  22. package/payload/.joycraft/references/testing.md +21 -21
  23. package/payload/.joycraft/references/worktrees.md +1 -1
  24. package/payload/.joycraft/runtime/completion.mjs +92 -6
  25. package/payload/.joycraft/runtime/dispatch-preflight.mjs +1 -1
  26. package/payload/.joycraft/runtime/dispatch-start.mjs +61 -4
  27. package/payload/.joycraft/runtime/evidence.mjs +134 -0
  28. package/payload/.joycraft/runtime/gate.mjs +308 -0
  29. package/payload/.joycraft/runtime/identity.mjs +5 -1
  30. package/payload/.joycraft/runtime/queue-check.mjs +355 -0
  31. package/payload/.joycraft/runtime/status.mjs +46 -5
  32. package/payload/PIN +31 -28
  33. package/payload/scripts/export.mjs +5 -2
@@ -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 { briefDecisionRecords, isObject, localPath, parseJson, readLocal, specStatus, validateQueue } from './identity.mjs';
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
@@ -20,7 +21,7 @@ function queuePaths(root) {
20
21
  .map(entry => `${featuresHome}/${entry.name}/${queueName}`).sort();
21
22
  }
22
23
 
23
- const accepted = spec => spec.status === 'done' && (isObject(spec.acceptedReport) || isObject(spec.ownerAcceptance) || isObject(spec.waiver));
24
+ export const accepted = spec => spec.status === 'done' && (isObject(spec.acceptedReport) || isObject(spec.ownerAcceptance) || isObject(spec.waiver));
24
25
 
25
26
  function openDecisions(root, folder) {
26
27
  const brief = `${folder}/brief.md`;
@@ -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, and features ready to archive. */
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,45 +1,46 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "source": "joycraft-prototype",
4
- "tag": "field-18",
5
- "commit": "880583a33d5c4562b4da02c5897f9ff81cb1edb6",
4
+ "tag": "field-21",
5
+ "commit": "905489efbd89190321d9b50abfd0551854f79159",
6
6
  "files": {
7
7
  ".agents/skills/joycraft-cleanup/SKILL.md": "99ce785e551be33412ac7a99ce44585a9b2be4440617caac273680383b4f7057",
8
- ".agents/skills/joycraft-context/SKILL.md": "e2f85baa47058fd61811fdb60d0cb41fb3f505f3957812d929db95bb99124f1b",
9
- ".agents/skills/joycraft-decompose/SKILL.md": "71b518d4fa8aeda5d1c0e72f34b3f7f846b3bba055adf509344b40bea35f070e",
10
- ".agents/skills/joycraft-entry/SKILL.md": "390b0a0b3d4fcbc8c962259abfc490764871266028e49be3479224c8768b9904",
11
- ".agents/skills/joycraft-implement/SKILL.md": "65909a6e3a320d8c0591e10ea1fc26469facadc27dafd3060dd0eabaf06890d9",
8
+ ".agents/skills/joycraft-context/SKILL.md": "8eb9374846b8f0d99280217b3fc73cfddac97d72f3ff6f3aca4a86af58dd8b85",
9
+ ".agents/skills/joycraft-decompose/SKILL.md": "53519b5fc73c4b668256fc21d044df16544a4ff46eeb63d21c83c53df4bb8061",
10
+ ".agents/skills/joycraft-entry/SKILL.md": "2d9c665416715fb9adb389f57c9d2da97d3d59f577ca4caae9539c6b98cff83b",
11
+ ".agents/skills/joycraft-implement/SKILL.md": "bbea314db25657bfd0249f0e821dfba12c05720b6d4c51e64024224c15cbe4bb",
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": "e2661af991a72d51036d266b3ebeabcee44d5e602f7b35ea0e40c9c95c171a66",
15
- ".agents/skills/joycraft-testing/SKILL.md": "8c89f3aa996e7de0a0c05d00081a8f24077311c180638abff7aaac9b87f6f89e",
14
+ ".agents/skills/joycraft-session-end/SKILL.md": "c957353095b2582766151baad2069dfde3cde4cdf2da071c3e3afd68a9da176f",
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": "219f08d5f66d6c63338c7d4cc75e81fe7d2d993723728876136ab8ca5ed6f8c5",
19
- ".claude/agents/joycraft-implementer.md": "30b26779bd49d2d66758bcb26442e78755b018a3830ac52ff634ebf057ce1cc5",
20
- ".claude/agents/joycraft-reviewer.md": "d671eb39827d5139d9d458d4cb7f5ce624bd40ec8cc5479f9d285bb787b5e5c6",
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": "e91f6a4199c0219cda3630a27ee0281ef94d4284221910840961061ee3b30d4f",
25
- ".joycraft/references/architecture.md": "52eaaa4b88053481c9f8cad2418ea0f1db880184c3a50c95901f30f24be75852",
24
+ ".joycraft/contracts/types.d.ts": "61b26f3f0e0a68b867daff1f6be2a0ad236367c5b2652ad55c5ca7252052f939",
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": "7e6b1fe95aab6d97e514995a35f0f6cc67bdea18e4570565e2eef4900e0da01b",
30
- ".joycraft/references/context.md": "df72d3b59d55f0d9741234d4a3d7b56532f560d787c88d5d8630d954472bc430",
29
+ ".joycraft/references/completion.md": "8b4f2873ec56581042ad160d3da26414c4dbabfd777e8b315fee4ab1204c8b7c",
30
+ ".joycraft/references/context.md": "b94dd48a427aaafe826116bac100375cbae565b1ba3239fd7812c56eac724577",
31
31
  ".joycraft/references/delivery.md": "1afc417ee3922ebf5e84c0ae87796d6cb6305679c0257ed38a35f396949de5e8",
32
- ".joycraft/references/dispatch.md": "a1c03473f98b44e88de0d60829b5abc2a11537f53abd1d9c7f84a5a50a140a21",
32
+ ".joycraft/references/dispatch.md": "62e8ad3abf4700f63963fb21a17d03569b78b5100538c10bc37d559679db39b8",
33
33
  ".joycraft/references/doc-cleanup-LICENSE.md": "a9e210590e2d0ebf719fe3801f1c0fda8f940af28656ff36e908c4315d94f886",
34
+ ".joycraft/references/gates.md": "8061e2ecc74b494e21ab77c734d2ae591964af3211c76147bea9f915969c5932",
34
35
  ".joycraft/references/knowledge.md": "a08a117a5d0ae65a45dfd8ab3f3da92dd3c7aeedaa09ae1d71ddf3d6528c7f95",
35
36
  ".joycraft/references/recurring-failures.md": "7080f6c55492bc19c2897f4f0b128a830a71cdb516678c79ff6e97ffa1dc6b86",
36
- ".joycraft/references/retro.md": "f359eae19747777fb4687c1bc7eb280f0319ae629ee62913346e60fc56551562",
37
- ".joycraft/references/settings.md": "7c3e383634ff68522c45460056fd5ef120a5565a62c01f14aac7b060a41804cf",
38
- ".joycraft/references/setup.md": "a9bd9072adc9f021b46287ff0422281ddb2285ac34738b6e29ad11cc60e8a6e5",
39
- ".joycraft/references/testing.md": "ddbc0e69212f4bf29f32f65e139c016b12eb40c29f621a99510129bedf292950",
37
+ ".joycraft/references/retro.md": "5f24b942f1faf308308caf5d0c543320fedbb69c59c2c240ef979cab50bae211",
38
+ ".joycraft/references/settings.md": "efaa8ea977d7dab9ec011dc0f83f652eb0e7f0098994a89d2d0ee07027b137d6",
39
+ ".joycraft/references/setup.md": "993ae51a753f5d55e13452787fc3f4bfd3df930e0c29730331639007e2ac4812",
40
+ ".joycraft/references/testing.md": "1d6bd005724032b3b4e52237dda563395d2621ce2103dff22090a93fce0316dc",
40
41
  ".joycraft/references/update.md": "36af36ab3d47b5ea46a8f71090333771e5e1deaa6ca19739a75c9fd4aea14eba",
41
42
  ".joycraft/references/workflow.md": "5b330debc6759b8f7975b159632f51074802067291fe4f4bebfb344f5b60cc52",
42
- ".joycraft/references/worktrees.md": "fb18af0cd76d4e3c5d5b892a7ae10946f21f189e642243235c188b571635f735",
43
+ ".joycraft/references/worktrees.md": "ad5645d2811e59da682c03f1cbdd1fb15abcc094fba74542c848548033890dba",
43
44
  ".joycraft/runtime/archive.mjs": "82b4d9567942a4abd21594ea299c4d323a8306ec7545cb0030431c87bd37f8b2",
44
45
  ".joycraft/runtime/artifacts/cli.mjs": "b3472857b6f8f680dc0d8a7be6495c502a430f5d0c47c88d44b42217e541b528",
45
46
  ".joycraft/runtime/artifacts/decisions.mjs": "e54fe173ca9050d495fd20b05aaedee8c918f3074553b6b7292cb40f500cbcb2",
@@ -48,24 +49,26 @@
48
49
  ".joycraft/runtime/artifacts/render.mjs": "488673cab94fa6bfde223c2c41650f8e183f7ac0be3840d371ee057d95ea0fa5",
49
50
  ".joycraft/runtime/artifacts/server.mjs": "0c787812ffbea22c3edb7cb7281e95f54e44da4361f57ac9906487e7b5e6f8e9",
50
51
  ".joycraft/runtime/cleanup.mjs": "9a10dfd27c12f807c71f407352f1526fdb9b4632c523a965952f65d1b7af158c",
51
- ".joycraft/runtime/completion.mjs": "422dd4de74a23b8e078e613a6567b5ead3fb7be2f7ecdac2a1b9f2a7fc8110c6",
52
+ ".joycraft/runtime/completion.mjs": "9f54cec1bfe64a6101a72cd88f51d682fb2359333e63a6c272f3469214094d21",
52
53
  ".joycraft/runtime/config.mjs": "72a536f3453dd73f65fdc243e2a13b562eee5a7ba59528adca4bde684307036a",
53
54
  ".joycraft/runtime/context/cli.mjs": "40adc206c8c3b7f4f5bedffb097d9ae1b0718f0586a055796e4987e9c3088eee",
54
55
  ".joycraft/runtime/context/index.mjs": "5a69d33d9a1a66ef23301e952ecb1ec427ff4b0baf408ede67a2600d3f2a173c",
55
56
  ".joycraft/runtime/context/search.mjs": "e32a42ba9b168ca7c68fed46d47a79250c27aa4c07c0835feae084b5d1e0d0ca",
56
57
  ".joycraft/runtime/coordinator.mjs": "9252a40ee3a82808a780158427b02129d8075679ed329bce2dd74168c7eb42ab",
57
58
  ".joycraft/runtime/delivery.mjs": "4fe897714eec33b24003f0d69abe1522a5199193ab7333fa6421776ee048df1c",
58
- ".joycraft/runtime/dispatch-preflight.mjs": "a86736e013dcca9f1f8a2ab1abd42cb81e614373b2140b272ca6ac91a0525d34",
59
- ".joycraft/runtime/dispatch-start.mjs": "b8d27b53566062c79cb95bf3f89bcb3e4abc9dd9dc15612cfced8685cf3a1c41",
60
- ".joycraft/runtime/evidence.mjs": "ee5bec5c9e5f1372a994a899b8161ff88d96a1d0ccf552d75de87a61c1c04bd3",
61
- ".joycraft/runtime/identity.mjs": "9854974dfb24f4469668e4db0dd6d2279bb2298157ff6262bb7864ef8e9ad174",
59
+ ".joycraft/runtime/dispatch-preflight.mjs": "75c895e4deb789f3bfe87a1be585f5537cea024b866e86a72949685e4860e228",
60
+ ".joycraft/runtime/dispatch-start.mjs": "fd3654e78cd5db9ada013ed95ea9259d53725e41bcee399ce2cb1a7d9e54a579",
61
+ ".joycraft/runtime/evidence.mjs": "62a4222a0931aac75b5a4f6d746da549f21febc8411e17ec7805ac5fed2bf7c1",
62
+ ".joycraft/runtime/gate.mjs": "c714f50f9c228cf45455976ac1e8a1d91fe3f478f4f9743b9e24d87ced232da2",
63
+ ".joycraft/runtime/identity.mjs": "88c571e82dbf003754a8b621f49ec333a31e90c82be41cf6469af5aaae5432fe",
62
64
  ".joycraft/runtime/kickoff.mjs": "9d96998bff94662863182b9a922f26732c649b7a0b0130b6da7d63ec73eb3590",
65
+ ".joycraft/runtime/queue-check.mjs": "1b93157d1c64d6b90a15baeff1b652fb9ec273d873402390d1c8c8c3ac8a0dbd",
63
66
  ".joycraft/runtime/redact.mjs": "cc8c0fe5e8d8fe78116ef126f6eee757a247739084e19c342bcf09a2b06524bc",
64
67
  ".joycraft/runtime/retro.mjs": "6f3664b0d50c12d4f2d8eef4b4d0d62897939d03e45860d4dcf35c0f5f92677c",
65
68
  ".joycraft/runtime/review-tools.json": "e0b0f5625654bba5f02d49710356aa1740fd42dd282eef6a29af361396915763",
66
69
  ".joycraft/runtime/review-tools.mjs": "15d426558a3884628147debb29136a20f746c3f184c52d6474ad59c222e5d8d5",
67
70
  ".joycraft/runtime/scope.mjs": "e2cdd929596246bf24e18850698db440119badc7068a3c5beab03ded45abbd65",
68
- ".joycraft/runtime/status.mjs": "3c5bc62c2c0b440da37af950c28f9278c1f743ff4566d3b6c5685465075239af",
71
+ ".joycraft/runtime/status.mjs": "404b85422275c23ec0c706128370f51b5b4a89b33e815e7e6156efe4f5ded73f",
69
72
  ".joycraft/runtime/trace.mjs": "b7924f759b07991f4135698df9c32654631a325957f0f8de5c2ca1262c0a836a",
70
73
  ".joycraft/runtime/update-check.mjs": "987b65605a26ea71b6417fda7b48753980e0d8afa20eadbd527143850a93319e",
71
74
  ".joycraft/runtime/wiring.mjs": "e08bcc604d40560f260edbc3499a4481a1efa7c7d2fa80545caa858827404667",
@@ -79,7 +82,7 @@
79
82
  ".joycraft/templates/queue.json": "88f922b6cc47b80befc27df86a143d6bae0b30869c46d712958b64291e5ebcc2",
80
83
  ".joycraft/templates/spec.md": "5f4b1490c2ba2e47ced1ef5b369fe3e41386eb61386c42c7a561b1e8af02ea5e",
81
84
  ".joycraft/templates/ui-slice.html": "0c3cf45709ff37815f8f0550b4b9431cb935589b282d40e8688b310a91de2274",
82
- "scripts/export.mjs": "016d675b19ba3122468ce34817b8a9c444be919aa4ec583842cd9bc16d299243",
85
+ "scripts/export.mjs": "085433a46d9bba37685d52611c881a1c4891c38d607453c6cbd47acb629054f8",
83
86
  "scripts/hook-paths.mjs": "fed8a147a9bf6501bfda1e4c7f015b41947277920dc2bf49c23ad826cfb0c724",
84
87
  "scripts/legacy-hooks.mjs": "d44f841e28d10b0a6aacf999bdd3e8bcec0feb742fa18c7459d6265d1d4776ba",
85
88
  "scripts/legacy-inventory.json": "92455cceac13cc8bd27a0cbd5c16df71a44a82bf7a18280f5ba05b5dde2908ba"
@@ -191,8 +191,11 @@ export async function exportBundle({ sourceRoot, targetRoot, check = false, hook
191
191
  const bytes = await readFile(join(source, path));
192
192
  return harness === 'claude' && path.endsWith('.md') ? Buffer.from(bytes.toString('utf8').replaceAll('.agents/skills/', '.claude/skills/')) : bytes;
193
193
  };
194
- // Native hooks are optional; their installer loads only when hooks are requested.
195
- const hookInstaller = hooks ? await import('./install-hooks.mjs') : null;
194
+ // Native hooks are optional and not part of every bundle. Their installer
195
+ // loads only when hooks are requested and it is present beside this script.
196
+ const hookInstallerUrl = new URL('./install-hooks.mjs', import.meta.url);
197
+ if (hooks && !(await statOrNull(fileURLToPath(hookInstallerUrl)))) throw new Error('Native hooks are not part of this bundle; export with --without-hooks');
198
+ const hookInstaller = hooks ? await import(hookInstallerUrl) : null;
196
199
  if (hooks && !files.includes(hookInstaller.hookRuntimePath)) throw new Error('The source bundle has no hook runtime');
197
200
  const installed = await readInstallationManifest(target);
198
201
  const legacy = upgrade ? await legacyPlan(target, installed, new Set(files.map(destinationPath))) : { archive: [], conflicts: [] };