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.
@@ -47,6 +47,7 @@ export function validateReview({ root = process.cwd(), report, state, reportPath
47
47
  validateIndependentReview(report);
48
48
  requireValue(['PASS', 'FAIL', 'UNVERIFIED'].includes(report.verdict), 'Report verdict must be PASS, FAIL or UNVERIFIED');
49
49
  requireValue(Array.isArray(report.unresolved) && report.unresolved.every(nonempty), 'Report unresolved findings must be an array of nonempty strings');
50
+ validateFindings(report, state.spec.verification.criteria);
50
51
  requireValue(nonempty(report.createdAt) && Number.isFinite(Date.parse(report.createdAt)), 'Report needs a valid createdAt timestamp');
51
52
  requireValue(Array.isArray(report.flows) && report.flows.length > 0, 'Report needs flow evidence');
52
53
  const subject = report.subject;
@@ -71,8 +72,53 @@ export function validateReview({ root = process.cwd(), report, state, reportPath
71
72
  }
72
73
  }
73
74
 
75
+ const refused = error => Object.assign(error, { exitCode: 2 });
76
+ const findingClasses = ['blocking', 'decision-needed', 'follow-up'];
77
+ const findingOrigins = ['new', 'pre-existing', 'unknown'];
78
+ const findingFields = ['id', 'class', 'origin', 'criterion', 'at', 'summary', 'assumption'];
79
+
80
+ /**
81
+ * The optional `findings` list keeps the report at schemaVersion 1; a report
82
+ * without it is read as before. A malformed finding is refused with exit 2 and
83
+ * the field named, so the reviewer can correct the report.
84
+ */
85
+ function validateFindings(report, criteria) {
86
+ if (report.findings === undefined) return;
87
+ const check = (condition, field, message) => { if (!condition) throw refused(new Error(`Report ${field} ${message}; correct the report and run check-report again`)); };
88
+ check(Array.isArray(report.findings), 'findings', 'must be an array');
89
+ const ids = new Set();
90
+ report.findings.forEach((finding, index) => {
91
+ const at = `findings[${index}]`;
92
+ check(isObject(finding), at, 'must be an object');
93
+ for (const key of Object.keys(finding)) check(findingFields.includes(key), `${at}.${key}`, `is not a finding field (${findingFields.join(', ')})`);
94
+ check(nonempty(finding.id) && !ids.has(finding.id), `${at}.id`, 'must be a nonempty id, unique in the report');
95
+ ids.add(finding.id);
96
+ check(findingClasses.includes(finding.class), `${at}.class`, `must be ${findingClasses.join(', ')}`);
97
+ check(findingOrigins.includes(finding.origin), `${at}.origin`, `must be ${findingOrigins.join(', ')}`);
98
+ check(nonempty(finding.summary), `${at}.summary`, 'must be a nonempty string');
99
+ for (const key of ['criterion', 'at', 'assumption']) check(finding[key] === undefined || nonempty(finding[key]), `${at}.${key}`, 'must be a nonempty string when given');
100
+ check(finding.criterion === undefined || criteria.some(item => item.id === finding.criterion), `${at}.criterion`, `names no criterion of this spec: ${finding.criterion}`);
101
+ check(finding.class === 'follow-up' || finding.criterion !== undefined || finding.at !== undefined, `${at}.criterion`, `or .at is required for a ${finding.class} finding`);
102
+ });
103
+ }
104
+
105
+ const findingPlace = finding => [finding.criterion && `criterion ${finding.criterion}`, finding.at].filter(Boolean).join(', ');
106
+
107
+ /** A blocking or decision-needed finding refuses completion with exit 2; a follow-up never does. */
108
+ function refuseHeldFindings(report, specId) {
109
+ const named = cls => (report.findings ?? []).filter(finding => finding.class === cls).map(finding => `${finding.id} (${findingPlace(finding)})`);
110
+ const blocking = named('blocking');
111
+ const decisions = named('decision-needed');
112
+ const reasons = [
113
+ ...(blocking.length ? [`blocking finding ${blocking.join(', ')}: fix it and get a fresh review`] : []),
114
+ ...(decisions.length ? [`decision-needed finding ${decisions.join(', ')}: spec ${specId} stays in-review and only its dependents wait; continue independent specs, ask the user, then get a fresh review`] : []),
115
+ ];
116
+ if (reasons.length) throw refused(new Error(`Report has ${reasons.join('; ')}`));
117
+ }
118
+
74
119
  function validatePassingReport(root, report, state, reportPath) {
75
120
  validateReview({ root, report, state, reportPath });
121
+ refuseHeldFindings(report, state.spec.id);
76
122
  requireValue(report.verdict === 'PASS', 'Report verdict must be PASS; FAIL or UNVERIFIED cannot complete a spec');
77
123
  requireValue(report.unresolved.length === 0, 'Report has unresolved review findings');
78
124
  }
@@ -130,13 +176,13 @@ export function recover({ root = process.cwd(), queuePath }) {
130
176
  return { status: 'restored', queuePath, specId: journal.specId };
131
177
  }
132
178
 
133
- async function writeCompletion({ root, queuePath, specId, state, metadataKey, metadata, validate, stableFiles }) {
179
+ async function writeCompletion({ root, queuePath, specId, state, status = 'done', metadataKey, metadata, validate, stableFiles }) {
134
180
  const updatedQueue = structuredClone(state.queue);
135
- Object.assign(updatedQueue.specs.find(spec => spec.id === specId), { status: 'done', [metadataKey]: metadata });
181
+ Object.assign(updatedQueue.specs.find(spec => spec.id === specId), { status, [metadataKey]: metadata });
136
182
  const journal = {
137
183
  schemaVersion: 1, queuePath, specId,
138
184
  files: [
139
- { path: state.specPath, before: state.specBytes, after: Buffer.from(state.status.replace('done')) },
185
+ { path: state.specPath, before: state.specBytes, after: Buffer.from(state.status.replace(status)) },
140
186
  { path: queuePath, before: state.queueBytes, after: Buffer.from(`${JSON.stringify(updatedQueue, null, 2)}\n`) },
141
187
  ].map(file => ({ path: file.path, before: { sha256: sha256(file.before), base64: file.before.toString('base64') }, after: { sha256: sha256(file.after), base64: file.after.toString('base64') } })),
142
188
  };
@@ -144,12 +190,14 @@ async function writeCompletion({ root, queuePath, specId, state, metadataKey, me
144
190
  try { saveExclusive(pendingFile, `${JSON.stringify(journal, null, 2)}\n`); } catch (error) {
145
191
  throw new Error(`${error.message}. ${recoveryHint(queuePath)}`);
146
192
  }
193
+ let written = 0;
147
194
  try {
148
195
  for (const stable of stableFiles) requireValue(sha256(readLocal(root, stable.path)) === stable.sha256, `${stable.label} changed during completion`);
149
196
  for (const file of journal.files) requireValue(sha256(readLocal(root, file.path)) === file.before.sha256, `Completion conflict: ${file.path} changed during validation`);
150
197
  validate(state);
151
198
  for (const file of journal.files) {
152
199
  requireValue(sha256(readLocal(root, file.path)) === file.before.sha256, `Completion conflict: ${file.path} changed before write`);
200
+ written += 1;
153
201
  replaceFile(root, file.path, Buffer.from(file.after.base64, 'base64'));
154
202
  }
155
203
  // Catch overlapping worker edits during the two writes before accepting them.
@@ -158,6 +206,12 @@ async function writeCompletion({ root, queuePath, specId, state, metadataKey, me
158
206
  validate(readQueue({ root, queuePath, specId }));
159
207
  unlinkSync(pendingFile);
160
208
  } catch (error) {
209
+ // Before the first write there is nothing to restore; a kept journal would
210
+ // only block the queue, or fail recovery over another writer's edit.
211
+ if (written === 0) {
212
+ unlinkSync(pendingFile);
213
+ throw new Error(`${error.message}. Neither status file was written.`);
214
+ }
161
215
  let restoration = 'The original statuses were restored.';
162
216
  try { restore(root, journal); } catch (restoreError) { restoration = restoreError.message; }
163
217
  throw new Error(`${error.message}. ${restoration} ${recoveryHint(queuePath)}`);
@@ -186,6 +240,35 @@ export async function complete({ root = process.cwd(), queuePath, specId, report
186
240
  return { status: 'done', unchanged: false, acceptedReport, implementationRevision: report.subject.implementationRevision };
187
241
  }
188
242
 
243
+ /**
244
+ * Move a todo spec whose dependencies are done to in-review: both status
245
+ * surfaces in one journaled write, plus a `submitted` record that subject
246
+ * bindings leave out, like status. An in-review spec is left unchanged. A
247
+ * criterion with no [AC:id] test is returned as a warning, never a refusal.
248
+ * Every refusal carries exitCode 2.
249
+ */
250
+ export async function submit({ root = process.cwd(), queuePath, specId }) {
251
+ try {
252
+ queuePath = relativePath(queuePath);
253
+ assertNoJournal(root, queuePath);
254
+ const state = readQueue({ root, queuePath, specId });
255
+ if (state.spec.status === 'in-review') return { status: 'in-review', unchanged: true, untraced: [] };
256
+ requireValue(state.spec.status === 'todo', `Spec ${specId} is done; submit moves only a todo spec to in-review`);
257
+ const requireDependencies = current => {
258
+ const unmet = current.spec.depends_on.filter(id => current.queue.specs.find(spec => spec.id === id).status !== 'done');
259
+ requireValue(unmet.length === 0, `Spec ${specId} depends on spec ${unmet.join(', spec ')}, which is not done`);
260
+ };
261
+ requireDependencies(state);
262
+ const { traceSpec } = await import('./trace.mjs');
263
+ const { untraced } = traceSpec({ root, queuePath, specId });
264
+ await writeCompletion({
265
+ root, queuePath, specId, state, status: 'in-review', metadataKey: 'submitted', metadata: { at: new Date().toISOString() },
266
+ stableFiles: [], validate: requireDependencies,
267
+ });
268
+ return { status: 'in-review', unchanged: false, untraced };
269
+ } catch (error) { throw refused(error); }
270
+ }
271
+
189
272
  /**
190
273
  * The native host attests the instruction text before this helper runs. Local
191
274
  * JSON cannot authenticate that a human said it, so this validates only the
@@ -457,13 +540,13 @@ export async function acceptWaiver({ root = process.cwd(), queuePath, specId, wa
457
540
 
458
541
  function argumentsFor(argv) {
459
542
  const [command, ...args] = argv;
460
- requireValue(['snapshot', 'scope', 'complete', 'finalize-review', 'accept-owner', 'accept-waiver', 'recover'].includes(command), 'Usage: completion.mjs scope --queue <path> --spec <id> | snapshot --queue <path> --spec <id> --out <subject.json> | complete|finalize-review --queue <path> --spec <id> --report <report.json> | accept-owner --queue <path> --spec <id> --decision <decision.json> | accept-waiver --queue <path> --spec <id> --waiver <waiver.json> [--report <report.json>] | recover --queue <path>');
543
+ requireValue(['snapshot', 'scope', 'submit', 'complete', 'finalize-review', 'accept-owner', 'accept-waiver', 'recover'].includes(command), 'Usage: completion.mjs scope|submit --queue <path> --spec <id> | snapshot --queue <path> --spec <id> --out <subject.json> | complete|finalize-review --queue <path> --spec <id> --report <report.json> | accept-owner --queue <path> --spec <id> --decision <decision.json> | accept-waiver --queue <path> --spec <id> --waiver <waiver.json> [--report <report.json>] | recover --queue <path>');
461
544
  const flags = {};
462
545
  for (let i = 0; i < args.length; i += 2) {
463
546
  requireValue(['--queue', '--spec', '--out', '--report', '--decision', '--waiver'].includes(args[i]) && nonempty(args[i + 1]) && flags[args[i]] === undefined, `Invalid or duplicate argument: ${args[i]}`);
464
547
  flags[args[i]] = args[i + 1];
465
548
  }
466
- const expected = command === 'recover' ? ['--queue'] : command === 'scope' ? ['--queue', '--spec'] : ['--queue', '--spec', command === 'snapshot' ? '--out' : command === 'accept-owner' ? '--decision' : command === 'accept-waiver' ? '--waiver' : '--report'];
549
+ const expected = command === 'recover' ? ['--queue'] : command === 'scope' || command === 'submit' ? ['--queue', '--spec'] : ['--queue', '--spec', command === 'snapshot' ? '--out' : command === 'accept-owner' ? '--decision' : command === 'accept-waiver' ? '--waiver' : '--report'];
467
550
  const optional = command === 'accept-waiver' ? ['--report'] : [];
468
551
  requireValue(expected.every(flag => flags[flag] !== undefined) && Object.keys(flags).every(flag => expected.includes(flag) || optional.includes(flag)), `Missing or unexpected arguments for ${command}`);
469
552
  if (command !== 'recover') requireValue(/^(?:0|[1-9]\d*)$/.test(flags['--spec']) && Number.isSafeInteger(Number(flags['--spec'])), 'Spec ID must be a nonnegative integer');
@@ -487,6 +570,9 @@ export async function main(argv = process.argv.slice(2)) {
487
570
  assertNoJournal(root, queuePath);
488
571
  const current = snapshot({ root, queuePath, specId: Number(flags['--spec']) });
489
572
  result = { queuePath: current.queuePath, specId: current.specId, changeScope: current.binding?.changeScope ?? null };
573
+ } else if (command === 'submit') {
574
+ result = await submit({ root, queuePath, specId: Number(flags['--spec']) });
575
+ for (const id of result.untraced) process.stderr.write(`Warning: criterion ${id} has no [AC:${id}] test in the spec's check inputs\n`);
490
576
  } else if (command === 'recover') result = recover({ root, queuePath });
491
577
  else if (command === 'accept-waiver') result = await acceptWaiver({ root, queuePath, specId: Number(flags['--spec']), waiverPath: flags['--waiver'], reportPath: flags['--report'] });
492
578
  else if (command === 'accept-owner') result = await acceptOwner({ root, queuePath, specId: Number(flags['--spec']), decisionPath: flags['--decision'] });
@@ -496,5 +582,5 @@ export async function main(argv = process.argv.slice(2)) {
496
582
  }
497
583
 
498
584
  if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
499
- main().catch(error => { process.stderr.write(`Completion stopped: ${error.message}\n`); process.exitCode = 1; });
585
+ main().catch(error => { process.stderr.write(`Completion stopped: ${error.message}\n`); process.exitCode = error.exitCode ?? 1; });
500
586
  }
@@ -544,5 +544,5 @@ export async function main(argv = process.argv.slice(2)) {
544
544
  }
545
545
 
546
546
  if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
547
- main().catch(error => { process.stderr.write(`Dispatch stopped: ${error.message}\n`); process.exitCode = 1; });
547
+ main().catch(error => { process.stderr.write(`Dispatch stopped: ${error.message}\n`); process.exitCode = error.exitCode ?? 1; });
548
548
  }
@@ -1,3 +1,10 @@
1
+ import { execFileSync, spawn } from 'node:child_process';
2
+ import { createHash } from 'node:crypto';
3
+ import { closeSync, createReadStream, existsSync, fsyncSync, mkdirSync, openSync, realpathSync, unlinkSync } from 'node:fs';
4
+ import os from 'node:os';
5
+ import path from 'node:path';
6
+ import { pathToFileURL } from 'node:url';
7
+
1
8
  const kinds = new Set(['runtime', 'visual', 'structural']);
2
9
  const methods = new Set(['test', 'command', 'browser', 'manual', 'source']);
3
10
  const results = new Set(['PASS', 'FAIL', 'UNVERIFIED']);
@@ -139,3 +146,132 @@ export function validateEvidence(report, criteria) {
139
146
  }
140
147
  return { ok: errors.length === 0, errors };
141
148
  }
149
+
150
+ export const defaultTimeoutMs = 300000;
151
+ const graceMs = 2000;
152
+ const usage = 'Usage: evidence.mjs run --receipt <path> [--timeout-ms <n>] -- <command> [args...]';
153
+
154
+ const refusal = message => Object.assign(new Error(message), { exitCode: 2 });
155
+ const refuse = (condition, message) => { if (!condition) throw refusal(message); };
156
+
157
+ function gitIgnored(root, relative) {
158
+ try {
159
+ execFileSync('git', ['check-ignore', '-q', '--', relative], { cwd: root, stdio: 'ignore' });
160
+ return true;
161
+ } catch { return false; } // 1: not ignored; anything else: git cannot say, so not ignored.
162
+ }
163
+
164
+ /** Signal the process group led by pid; false once the group is gone. */
165
+ function signalGroup(pid, signal) {
166
+ try { process.kill(-pid, signal); return true; } catch (error) {
167
+ if (error.code === 'ESRCH' || error.code === 'EPERM') return false;
168
+ throw error;
169
+ }
170
+ }
171
+
172
+ /** SIGTERM the group, then SIGKILL whatever is left after the grace period. */
173
+ async function endGroup(pid) {
174
+ if (!signalGroup(pid, 'SIGTERM')) return;
175
+ for (const deadline = Date.now() + graceMs; Date.now() < deadline;) {
176
+ await new Promise(resolve => setTimeout(resolve, 50));
177
+ if (!signalGroup(pid, 0)) return;
178
+ }
179
+ signalGroup(pid, 'SIGKILL');
180
+ }
181
+
182
+ /** A new receipt path inside the project that git ignores or that sits in a
183
+ * feature folder under the configured features home. Refuses with exit 2. */
184
+ async function receiptFile(root, receipt) {
185
+ const { localPath, relativePath } = await import('./identity.mjs');
186
+ let relative, file;
187
+ try { relative = relativePath(receipt); file = localPath(root, relative, true); }
188
+ catch (error) { throw refusal(`Receipt must be a new project-relative path inside the project: ${error.message}`); }
189
+ refuse(!existsSync(file), `Receipt already exists: ${relative}; use a fresh receipt path`);
190
+ const { workPaths } = await import('./config.mjs');
191
+ let features;
192
+ try { features = workPaths(root).features.split('/'); } catch (error) { throw refusal(error.message); }
193
+ const parts = relative.split('/');
194
+ const featureFolder = parts.length > features.length + 1 && features.every((part, index) => parts[index] === part)
195
+ && existsSync(path.join(root, ...parts.slice(0, features.length + 1)));
196
+ refuse(featureFolder || gitIgnored(root, relative),
197
+ `Receipt must be git-ignored or inside a feature folder under ${features.join('/')}/: ${relative}`);
198
+ mkdirSync(path.dirname(file), { recursive: true });
199
+ const inside = path.relative(realpathSync(root), realpathSync(path.dirname(file)));
200
+ refuse(inside === '' || (inside !== '..' && !inside.startsWith(`..${path.sep}`) && !path.isAbsolute(inside)), `Receipt must stay inside the project: ${relative}`);
201
+ return { relative, file };
202
+ }
203
+
204
+ /**
205
+ * Run the project's own command once, without a shell, with CI=1 and a time
206
+ * limit. The child's stdout and stderr both go straight to one new receipt
207
+ * file, in the order the child wrote them, as `cmd > receipt 2>&1` would.
208
+ * Returns the observation's `command` and `receipts`, plus `timedOut`,
209
+ * `timeoutMs` and the ending `signal` when there was one. A timeout ends the
210
+ * child's process group (POSIX) or the child (Windows) and gives exitCode null.
211
+ * Every refusal happens before the child starts and carries exitCode 2.
212
+ */
213
+ export async function runEvidence({ root = process.cwd(), receipt, timeoutMs = defaultTimeoutMs, argv }) {
214
+ refuse(Array.isArray(argv) && argv.length > 0 && argv.every(value => typeof value === 'string') && argv[0] !== '', `A command is needed after --. ${usage}`);
215
+ refuse(Number.isSafeInteger(timeoutMs) && timeoutMs > 0 && timeoutMs <= 2 ** 31 - 1, `--timeout-ms must be a whole number of milliseconds from 1 to ${2 ** 31 - 1}`);
216
+ const { relative, file } = await receiptFile(root, receipt);
217
+ let fd;
218
+ try { fd = openSync(file, 'wx', 0o644); }
219
+ catch (error) { throw refusal(error.code === 'EEXIST' ? `Receipt already exists: ${relative}; use a fresh receipt path` : `Cannot create receipt ${relative}: ${error.message}`); }
220
+ const posix = process.platform !== 'win32';
221
+ let child;
222
+ try {
223
+ child = spawn(argv[0], argv.slice(1), { cwd: root, env: { ...process.env, CI: '1' }, stdio: ['ignore', fd, fd], detached: posix, windowsHide: true });
224
+ await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
225
+ } catch (error) {
226
+ closeSync(fd);
227
+ unlinkSync(file);
228
+ throw refusal(`Could not start ${argv[0]}: ${error.message}`);
229
+ }
230
+ // The child runs in its own group, so pass on a stop that reaches only this process.
231
+ const stop = signal => { if (posix) signalGroup(child.pid, 'SIGKILL'); else child.kill('SIGKILL'); process.exit(128 + (os.constants.signals[signal] ?? 1)); };
232
+ const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
233
+ for (const signal of signals) process.on(signal, stop);
234
+ let timedOut = false;
235
+ const exited = new Promise(resolve => child.once('exit', (code, signal) => resolve({ code, signal })));
236
+ const timer = setTimeout(() => { timedOut = true; if (posix) endGroup(child.pid); else child.kill('SIGKILL'); }, timeoutMs);
237
+ const { code, signal } = await exited;
238
+ clearTimeout(timer);
239
+ // Leftover processes in the group would keep writing to the receipt after it is hashed.
240
+ if (posix) await endGroup(child.pid);
241
+ for (const each of signals) process.off(each, stop);
242
+ try { fsyncSync(fd); } finally { closeSync(fd); }
243
+ const digest = createHash('sha256');
244
+ for await (const chunk of createReadStream(file)) digest.update(chunk);
245
+ return {
246
+ command: { argv: [...argv], exitCode: timedOut ? null : code },
247
+ receipts: [{ path: relative, sha256: digest.digest('hex') }],
248
+ timedOut, timeoutMs, ...(signal ? { signal } : {}),
249
+ };
250
+ }
251
+
252
+ export async function main(args = process.argv.slice(2)) {
253
+ const [command, ...rest] = args;
254
+ refuse(command === 'run', usage);
255
+ const end = rest.indexOf('--');
256
+ refuse(end !== -1, `A command is needed after --. ${usage}`);
257
+ const flags = {};
258
+ for (let index = 0; index < end; index += 2) {
259
+ const key = rest[index]; const value = rest[index + 1];
260
+ refuse(['--receipt', '--timeout-ms'].includes(key) && index + 1 < end && typeof value === 'string' && value !== '' && flags[key] === undefined, `Invalid or duplicate argument: ${key}. ${usage}`);
261
+ flags[key] = value;
262
+ }
263
+ refuse(flags['--receipt'] !== undefined, `--receipt is required. ${usage}`);
264
+ refuse(flags['--timeout-ms'] === undefined || /^[1-9]\d*$/.test(flags['--timeout-ms']), '--timeout-ms must be a whole number of milliseconds');
265
+ const result = await runEvidence({ receipt: flags['--receipt'], argv: rest.slice(end + 1),
266
+ timeoutMs: flags['--timeout-ms'] === undefined ? defaultTimeoutMs : Number(flags['--timeout-ms']) });
267
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
268
+ // The receipt is written either way; a failed, killed or timed-out command exits 1. Exit 2 is only for a refusal.
269
+ if (result.command.exitCode !== 0) process.exitCode = 1;
270
+ return result;
271
+ }
272
+
273
+ // Node runs the main module from its real path; resolve symlinks before comparing.
274
+ const invoked = (() => { try { return realpathSync(process.argv[1]); } catch { return null; } })();
275
+ if (invoked && import.meta.url === pathToFileURL(invoked).href) {
276
+ main().catch(error => { process.stderr.write(`Evidence run stopped: ${error.message}\n`); process.exitCode = error.exitCode ?? 1; });
277
+ }
@@ -61,8 +61,9 @@ export function checkGates(root = process.cwd()) {
61
61
  const file = path.posix.join(path.posix.dirname(feature.queuePath), spec.file);
62
62
  failures.push({ kind: 'unaccepted-done', feature: feature.feature, specId: spec.id, file, queuePath: feature.queuePath,
63
63
  message: `Joycraft gate: ${feature.feature} spec ${spec.id} (${file}) is done with no accepted report, owner acceptance or waiver. `
64
- + 'Set it back to in-review in the queue and the spec, get an independent review, then complete it with '
65
- + `node .joycraft/runtime/completion.mjs finalize-review --queue ${feature.queuePath} --spec ${spec.id} --report <report.json>` });
64
+ + 'Set it back to in-review in the queue and spec. Do not ask the user: it restores the true status. '
65
+ + 'With no current PASS report, get an independent review, then complete it with '
66
+ + `node .joycraft/runtime/completion.mjs finalize-review --queue ${feature.queuePath} --spec ${spec.id} --report <file>` });
66
67
  }
67
68
  }
68
69
  const owner = new Map(status.features.flatMap(feature => feature.specs.map(row => [row.file, feature])));
@@ -78,8 +79,8 @@ export function checkGates(root = process.cwd()) {
78
79
  // hook subcommand edits its text in place, so every byte it does not own keeps
79
80
  // its value. Joycraft's hook is the one whose command is exactly hookCommand.
80
81
  // Claude Code sends the agent back only when a Stop hook exits 2, with the
81
- // reason on stderr; `check` does that and reads nothing from stdin, so the
82
- // result is the same when the event says stop_hook_active.
82
+ // reason on stderr; `check` does that. The exit code is the same when the
83
+ // event says stop_hook_active; only one line is added to the reason.
83
84
  export const settingsFile = '.claude/settings.json';
84
85
  export const hookCommand = 'node "$CLAUDE_PROJECT_DIR"/.joycraft/runtime/gate.mjs check --root "$CLAUDE_PROJECT_DIR"';
85
86
  const hookGroup = { hooks: [{ type: 'command', command: hookCommand }] };
@@ -225,13 +226,14 @@ function readState(root) {
225
226
  try { return JSON.parse(readFileSync(localPath(root, stateFile), 'utf8')); } catch { return null; }
226
227
  }
227
228
 
228
- const byHand = 'Run the check by hand: node .joycraft/runtime/gate.mjs check';
229
+ // A hook added over an open problem would refuse every stop until the problem is cleared.
230
+ const clearFirst = 'Joycraft gate: nothing was written. Clear each problem above, then turn the gates on again.';
229
231
 
230
232
  /** `hook --plan|--on|--off`: show, add or remove Joycraft's Stop hook in `.claude/settings.json`. */
231
233
  export function hook(root, action) {
232
234
  if (action !== 'off' && !claudeHost(root)) {
233
235
  return { change: 'none', claude: false,
234
- message: `The gate hook is for Claude Code only for now, and .joycraft/installation.json lists no claude host. Nothing was written. ${byHand}` };
236
+ message: 'The gate hook is for Claude Code only for now. Nothing was written. On this host, session end runs the same check.' };
235
237
  }
236
238
  if (action === 'off') {
237
239
  const { file, before, data } = readSettings(root);
@@ -241,8 +243,12 @@ export function hook(root, action) {
241
243
  return { file: settingsFile, change: 'none', message: `Joycraft's Stop hook is not in ${settingsFile}. Nothing was changed.` };
242
244
  }
243
245
  if (state?.after === before) {
244
- if (state.before === null) rmSync(file); else writeFileSync(file, state.before);
245
246
  rmSync(localPath(root, stateFile));
247
+ if (state.before === null) {
248
+ rmSync(file);
249
+ return { file: settingsFile, change: 'removed', message: `Removed ${settingsFile}: hook --on created it, and it held only Joycraft's Stop hook.` };
250
+ }
251
+ writeFileSync(file, state.before);
246
252
  return { file: settingsFile, change: 'removed', message: `Removed Joycraft's Stop hook from ${settingsFile}. Every other line is as it was.` };
247
253
  }
248
254
  // No usable record: say what was cut, and claim nothing about the bytes before --on.
@@ -254,15 +260,19 @@ export function hook(root, action) {
254
260
  }
255
261
  const plan = planHook(root);
256
262
  if (plan.change === 'none') return { file: settingsFile, change: 'none', message: `Joycraft's Stop hook is already in ${settingsFile}. Nothing was changed.` };
263
+ const problems = checkGates(root).failures.map(item => item.message);
257
264
  if (action === 'plan') {
258
- return { file: settingsFile, change: 'add', command: hookCommand, before: plan.before, after: plan.after,
259
- message: `Plan only; nothing was written. Show this change to the user and run gate.mjs hook --on on their yes.` };
265
+ return { file: settingsFile, change: 'add', command: hookCommand, ...(problems.length ? { problems } : {}), before: plan.before, after: plan.after,
266
+ message: problems.length
267
+ ? 'Plan only; nothing was written. hook --on refuses until the gate check finds none. Clear each problem you can by its next step, tell the user what you changed, then plan again.'
268
+ : `Plan only; nothing was written. Show this change to the user and run gate.mjs hook --on on their yes.` };
260
269
  }
270
+ if (problems.length) return { file: settingsFile, change: 'none', problems, message: clearFirst };
261
271
  mkdirSync(path.dirname(plan.file), { recursive: true });
262
272
  writeFileSync(localPath(root, settingsFile, true), plan.after);
263
273
  writeState(root, { file: settingsFile, before: plan.before, after: plan.after });
264
274
  return { file: settingsFile, change: 'added',
265
- message: `Added Joycraft's Stop hook to ${settingsFile}. Claude Code now runs the gate check each time it ends a reply. Turn it off with: node .joycraft/runtime/gate.mjs hook --off` };
275
+ message: `Added Joycraft's Stop hook to ${settingsFile}. Claude Code now runs the gate check each time it ends a reply. To turn it off, the user says "Turn off Joycraft's gates".` };
266
276
  }
267
277
 
268
278
  export function main(argv = process.argv.slice(2)) {
@@ -280,6 +290,12 @@ export function main(argv = process.argv.slice(2)) {
280
290
  }
281
291
  if (action === undefined) throw new Error(usage);
282
292
  const result = hook(path.resolve(root ?? '.'), action);
293
+ // --on over open problems: the same exit 2 and stderr lines as the check, then what to do.
294
+ if (action === 'on' && result.problems) {
295
+ process.stderr.write(`${[...result.problems, result.message].join('\n')}\n`);
296
+ process.exitCode = 2;
297
+ return result;
298
+ }
283
299
  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
284
300
  process.exitCode = 0;
285
301
  return result;
@@ -295,14 +311,36 @@ export function main(argv = process.argv.slice(2)) {
295
311
  }
296
312
  const result = checkGates(path.resolve(flags.root ?? '.'));
297
313
  const lines = [...(flags.verbose ? result.skipped.map(item => item.message) : []), ...result.failures.map(item => item.message)];
298
- if (lines.length) process.stderr.write(`${lines.join('\n')}\n`);
299
314
  process.exitCode = result.failures.length ? 2 : 0;
300
- return result;
315
+ // Every stop is checked, also a repeated one; a repeated one only gets one more line.
316
+ const write = () => { if (lines.length) process.stderr.write(`${lines.join('\n')}\n`); return result; };
317
+ if (!result.failures.length) return write();
318
+ return stopEvent().then(event => {
319
+ if (event?.stop_hook_active === true) lines.push(blockedAgain);
320
+ return write();
321
+ });
322
+ }
323
+
324
+ const blockedAgain = 'Joycraft gate: this stop was blocked before for the same reason. Do the step now; do not ask the user again.';
325
+
326
+ /** The Stop event Claude Code writes on stdin, or null: no event within a short wait, a terminal, or not JSON. */
327
+ function stopEvent(waitMs = 1000) {
328
+ if (process.stdin.isTTY) return Promise.resolve(null);
329
+ return new Promise(resolve => {
330
+ let text = '';
331
+ const done = value => { clearTimeout(timer); process.stdin.removeAllListeners(); process.stdin.destroy(); resolve(value); };
332
+ const timer = setTimeout(() => done(null), waitMs);
333
+ process.stdin.setEncoding('utf8');
334
+ process.stdin.on('data', chunk => { text += chunk; });
335
+ process.stdin.on('end', () => { try { done(JSON.parse(text)); } catch { done(null); } });
336
+ process.stdin.on('error', () => done(null));
337
+ });
301
338
  }
302
339
 
303
340
  // Node runs the main module from its real path; a hook may name it through a symlinked project path.
304
341
  const invoked = (() => { try { return realpathSync(process.argv[1]); } catch { return null; } })();
305
342
  if (invoked && import.meta.url === pathToFileURL(invoked).href) {
306
343
  const prefix = process.argv[2] === 'hook' ? 'Gate hook stopped' : 'Gate check stopped';
307
- try { main(); } catch (error) { process.stderr.write(`${prefix}: ${error.message}\n`); process.exitCode = 1; }
344
+ const stopped = error => { process.stderr.write(`${prefix}: ${error.message}\n`); process.exitCode = 1; };
345
+ try { Promise.resolve(main()).catch(stopped); } catch (error) { stopped(error); }
308
346
  }
@@ -184,6 +184,9 @@ export function validateQueue(queue, { select } = {}) {
184
184
  if (input.state !== undefined) requireValue(input.state === 'absent' && input.kind !== 'requirement', `Verification input ${inputPath} at index ${inputIndex} may use state: absent only for code, check or fixture inputs`);
185
185
  }
186
186
  if (spec.verification.changeScope !== undefined) validateChangeScope(spec.verification.changeScope, relativePath);
187
+ if (spec.submitted !== undefined) {
188
+ requireValue(isObject(spec.submitted) && Object.keys(spec.submitted).every(key => key === 'at') && nonempty(spec.submitted.at) && Number.isFinite(Date.parse(spec.submitted.at)), `Invalid submit record for spec ${spec.id}`);
189
+ }
187
190
  if (spec.acceptedReport !== undefined) {
188
191
  requireValue(isObject(spec.acceptedReport) && isSha256(spec.acceptedReport.sha256), `Invalid accepted report for spec ${spec.id}`);
189
192
  relativePath(spec.acceptedReport.path);
@@ -240,10 +243,11 @@ export function subjectIdentity(subject) {
240
243
  return sha256(canonical(fields));
241
244
  }
242
245
 
243
- /** Queue status and completion receipt metadata do not change reviewed requirements. */
246
+ /** Queue status, the submit record and completion receipt metadata do not change reviewed requirements. */
244
247
  function queueSpecRequirements(spec) {
245
248
  const requirements = { ...spec };
246
249
  delete requirements.status;
250
+ delete requirements.submitted;
247
251
  delete requirements.acceptedReport;
248
252
  delete requirements.ownerAcceptance;
249
253
  delete requirements.waiver;