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 CHANGED
@@ -113,6 +113,7 @@ consideration ([decision D6](docs/context/decision-log.md)).
113
113
  ```text
114
114
  We keep a wiki in <where>. Link it from the context map, and keep it up to date
115
115
  each time a feature is archived.
116
+ Do not commit, publish, or ask me for API keys.
116
117
  ```
117
118
 
118
119
  ### Settings
@@ -120,9 +121,11 @@ each time a feature is archived.
120
121
  Joycraft works with no settings. To change one, say what you want:
121
122
 
122
123
  ```text
123
- Keep Joycraft's briefs and specs in working/features.
124
- Whenever a feature is archived, run our wiki sync script.
125
- The page docs/context/auction-rules.md describes src/auction. Flag it when that code changes.
124
+ Change these Joycraft settings, and show me the change before you write it:
125
+ - Keep Joycraft's briefs and specs in working/features, and finished features in working/archive.
126
+ - Whenever a feature is archived, run our wiki sync script.
127
+ - The page docs/context/auction-rules.md describes src/auction. Flag it when that code changes.
128
+ Do not commit, publish, or ask me for API keys.
126
129
  ```
127
130
 
128
131
  The agent writes the change to `joycraft.yaml` at the project root, shows it to you
@@ -138,6 +141,8 @@ anything:
138
141
  - **Status.** It runs the gate check (below). The check finds specs marked done with
139
142
  no accepted review and specs whose text disagrees with the queue. It also finds
140
143
  features that are finished but not archived.
144
+ - **Questions.** It asks you each follow-up question that the reviews left. See
145
+ [Running a queue while you are away](#running-a-queue-while-you-are-away).
141
146
  - **Worktrees.** It removes its worker worktrees once their spec is done and merged.
142
147
  It keeps anything unfinished, unmerged or not made by Joycraft, and says why.
143
148
  - **One coordinator.** One session coordinates each queue, so a second session's
@@ -191,6 +196,84 @@ counts as evidence; your project keeps its own tools.
191
196
  After an update, the agent checks the review loop again and asks only about what
192
197
  changed.
193
198
 
199
+ ### Running a queue while you are away
200
+
201
+ You can start a queue and leave. The agent asks its questions before the queue
202
+ starts. Work stops only for an answer that must come from you or for a broken
203
+ project. A broken tool that the agent cannot repair holds its spec, not the queue.
204
+ Other open points wait for you as a list of follow-up questions at session end.
205
+ You do not run a command at any step.
206
+
207
+ **Before the queue starts.** The agent checks each spec for gaps that a program can
208
+ find:
209
+
210
+ - An acceptance criterion has no check.
211
+ - A spec names an input file that does not exist and is not planned work.
212
+ - A spec depends on a spec that is not in the queue, or two specs depend on each
213
+ other.
214
+ - A question in the brief is still open, and a queued spec needs its answer.
215
+
216
+ The agent adds each gap to the brief as a question and asks you while you are still
217
+ there.
218
+
219
+ **While you are away.** A question holds a spec only for a mandatory answer: a
220
+ case where two readings of the brief give opposite results for a stated criterion,
221
+ or where a wrong guess cannot be undone. The specs that depend on it wait too. All
222
+ other specs go on. Three other cases hold one spec and the specs that depend on
223
+ it: a broken tool, a refused fourth review, or a second FAIL on the same criterion.
224
+ The whole queue stops only for a broken project: it does not build or install, or
225
+ the repository is broken. It also stops before a step that touches data or systems
226
+ outside the project, such as a shared database or a deploy.
227
+
228
+ Some hosts cannot start a separate reviewer context. On such a host, each spec
229
+ stays `in-review`, and the specs that depend on it do not start while you are away.
230
+ Specs that do not depend on it go on.
231
+
232
+ **When you come back.** A case that the spec does not decide does not stop the
233
+ queue. The reviewer takes the reading closest to your brief and writes down that
234
+ assumption, and the spec can complete. At session end, the agent asks you each
235
+ follow-up question with its spec. For a case the spec did not decide, the question
236
+ gives the assumption the reviewer made. The agent also asks each mandatory question
237
+ that holds a spec. A spec that a broken tool, a refused fourth review or a second
238
+ FAIL holds is not in this list of questions. Session end reports it with its
239
+ status, `in-review`. For a refused review or a second FAIL, the spec has a note
240
+ under `## Decision needed`.
241
+
242
+ **Why you want it.** The questions come while you are there, so a queue does not
243
+ wait hours for a small answer. A guess is not hidden: each one comes back to you as
244
+ a question.
245
+
246
+ **Start a queue and leave.** Say:
247
+
248
+ ```text
249
+ Build <what you want> with Joycraft. I will be away while the queue runs.
250
+ Before you start the queue, check it for gaps and ask me every question now.
251
+ While I am away, stop only for an answer that must come from me or for a broken project.
252
+ At session end, ask me each follow-up question with the assumption the reviewer made.
253
+ Do not archive a feature until I have answered its follow-up questions.
254
+ Do not commit to the default branch, push, publish, or ask me for API keys.
255
+ ```
256
+
257
+ **Get the follow-up questions.** The questions stay available until the feature is
258
+ archived. Before then, you can ask for them again later, or in a new session:
259
+
260
+ ```text
261
+ Run Joycraft's session end. Before you archive a feature, ask me each follow-up
262
+ question from its reviews, with the spec and the assumption the reviewer made, and
263
+ each question that holds a spec.
264
+ Do not commit, publish, or ask me for API keys.
265
+ ```
266
+
267
+ **What it does not do.**
268
+
269
+ - The queue check finds only the gaps that a program can find. The agent reads each
270
+ spec for the rest, for example a criterion that needs work from a later spec.
271
+ - An assumption can be wrong. You see it at session end, after the spec is done.
272
+ - After a feature is archived, session end no longer lists its follow-up questions.
273
+ The reviews stay in the archive.
274
+ - A criterion can still pass on a test that only the implementing agent wrote.
275
+ Joycraft does not yet check that the test fails for broken behavior.
276
+
194
277
  ### The gates: no spec is done without an accepted review
195
278
 
196
279
  Joycraft's rule is that only an accepted review completes a spec. Without the
@@ -209,23 +292,31 @@ It sends the agent back with the spec or file name and the next step. A spec tha
209
292
  **Why you want it.** Use the gates for long sessions and for sessions that you do
210
293
  not watch. A prompt tells the agent what to do, but a prompt is not a guarantee.
211
294
  With the gates on, Claude Code runs the check each time the agent tries to stop. The
212
- agent cannot stop until the problem is gone.
295
+ agent cannot stop until the problem is gone. For a spec marked done with no accepted
296
+ review, the agent sets the spec back to `in-review` without asking you.
213
297
 
214
298
  **Before you turn them on.** An older project can have specs marked done with no
215
- accepted review. The check sends each one back for a review. To see them first, say:
299
+ accepted review. Turning on the gates runs the check first. The hook goes in only
300
+ after a clean check. The agent sets each of these specs back to
301
+ `in-review` itself, tells you what it changed, and checks again. It stops and asks
302
+ you only about a file that it cannot read. A look at the problems first is optional.
303
+ To see them, say:
216
304
 
217
305
  ```text
218
306
  Run Joycraft's gate check with `node .joycraft/runtime/gate.mjs check` and show me
219
- what it names. Change nothing yet.
307
+ what it names. Change nothing yet. For each spec it names, tell me what you recommend.
308
+ Do not commit, publish, or ask me for API keys.
220
309
  ```
221
310
 
222
- Do this also after you update an older project to 1.4.1, because session end now
223
- runs the same check.
311
+ Do this also after you update an older project to 1.4.1 or later, because session
312
+ end now runs the same check.
224
313
 
225
314
  **Turn them on.** Say:
226
315
 
227
316
  ```text
228
- Turn on Joycraft's gates.
317
+ Turn on Joycraft's gates. Show me the change to .claude/settings.json on a page,
318
+ and write it only on my yes.
319
+ Do not commit, publish, or ask me for API keys.
229
320
  ```
230
321
 
231
322
  The agent shows you the change to `.claude/settings.json` on a page. It writes the
@@ -235,7 +326,8 @@ also offers the gates one time.
235
326
  **Turn them off.** Say:
236
327
 
237
328
  ```text
238
- Turn off Joycraft's gates.
329
+ Turn off Joycraft's gates. Remove only Joycraft's hook, and tell me what you removed.
330
+ Do not commit, publish, or ask me for API keys.
239
331
  ```
240
332
 
241
333
  The agent removes Joycraft's hook. Your own hooks stay. If you remove Joycraft from
@@ -252,7 +344,8 @@ the project, the agent removes this hook first.
252
344
  **A fourth review is refused.** On every agent, one spec gets at most three
253
345
  reviews. A round is one set of reviewed inputs, so a new review of the same code
254
346
  does not count again. Reviewer startup prints the round and refuses a fourth
255
- review. The agent then records `## Decision needed` in the spec and asks you.
347
+ review. The agent then records `## Decision needed` in the spec and holds that spec.
348
+ The specs that do not depend on it go on.
256
349
 
257
350
  ## Answering questions: the decision page
258
351
 
@@ -315,7 +408,9 @@ always your choice.
315
408
  This is an instruction the agent follows, so it can forget. To check yourself, ask:
316
409
 
317
410
  ```text
318
- Check for a Joycraft update.
411
+ Check for a Joycraft update. If there is one, run
412
+ `npx joycraft@latest update . --plan --json`, show me what changes, and update on my yes.
413
+ Do not commit, publish, or ask me for API keys.
319
414
  ```
320
415
 
321
416
  ## Hosts
@@ -344,6 +439,8 @@ in [Prompts](docs/prompts.md):
344
439
  | Change a setting | "Keep Joycraft's specs in working/features." |
345
440
  | Connect your wiki | "Link our wiki and keep it up to date." |
346
441
  | Clean up | "Clean up the docs and the workspace." |
442
+ | Start a queue and leave | "Build <what you want> with Joycraft. I will be away while the queue runs." |
443
+ | Get the follow-up questions | "Run Joycraft's session end and ask me each follow-up question." |
347
444
  | Turn the gates on | "Turn on Joycraft's gates." |
348
445
  | Turn the gates off | "Turn off Joycraft's gates." |
349
446
  | Undo the 1.0 upgrade | "Undo this project's upgrade to Joycraft 1.0." |
package/dist/cli.js CHANGED
@@ -1428,8 +1428,25 @@ function recoverLegacy(dir) {
1428
1428
  }
1429
1429
 
1430
1430
  // src/rollback.ts
1431
+ import { spawnSync } from "child_process";
1431
1432
  import { copyFileSync as copyFileSync3, existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync4, rmdirSync as rmdirSync2, rmSync as rmSync3, statSync } from "fs";
1432
1433
  import { dirname as dirname4, join as join4, relative, resolve as resolve3, sep as sep3 } from "path";
1434
+ var SETTINGS = ".claude/settings.json";
1435
+ var RUNTIME = ".joycraft/runtime/";
1436
+ var GATE = `${RUNTIME}gate.mjs`;
1437
+ var GATE_HOOK_COMMAND = 'node "$CLAUDE_PROJECT_DIR"/.joycraft/runtime/gate.mjs check --root "$CLAUDE_PROJECT_DIR"';
1438
+ function gateHookIn(root) {
1439
+ const file = join4(root, SETTINGS);
1440
+ if (!existsSync4(file)) return false;
1441
+ let data;
1442
+ try {
1443
+ data = JSON.parse(readFileSync4(file, "utf8").replace(/^\uFEFF/, ""));
1444
+ } catch {
1445
+ return false;
1446
+ }
1447
+ const stop = data?.hooks?.Stop;
1448
+ return Array.isArray(stop) && stop.some((group) => Array.isArray(group?.hooks) && group.hooks.some((hook) => hook?.type === "command" && hook.command === GATE_HOOK_COMMAND));
1449
+ }
1433
1450
  function inside3(root, path) {
1434
1451
  const full = resolve3(root, path);
1435
1452
  if (full !== root && !full.startsWith(root + sep3)) throw new Error(`Path escapes the project: ${path}`);
@@ -1473,12 +1490,14 @@ function planRollback(dir, stamp2, { force = false } = {}) {
1473
1490
  if (existsSync4(inside3(root, from)) && !removing.has(from)) blocked.push(from);
1474
1491
  else restore.push(from);
1475
1492
  }
1476
- return { root, backup, restore, remove, edited, blocked };
1493
+ const gateHook = !record.settingsBackup && remove.some((path) => path.startsWith(RUNTIME)) && gateHookIn(root);
1494
+ return { root, backup, restore, remove, edited, blocked, gateHook };
1477
1495
  }
1478
1496
  function formatRollback(plan) {
1479
1497
  return [
1480
1498
  `Roll back to before ${plan.backup}:`,
1481
1499
  ` restore ${plan.restore.length} 0.7 file(s) \xB7 remove ${plan.remove.length} 1.0 file(s)`,
1500
+ ...plan.gateHook ? [` remove Joycraft's gate Stop hook from ${SETTINGS}; rollback removes runtime files it needs`] : [],
1482
1501
  ...plan.edited.map((path) => ` kept, edited after the migration (use --force to remove): ${path}`),
1483
1502
  ...plan.blocked.map((path) => ` not restored, a file is already there: ${path}`),
1484
1503
  ` The backup stays in ${plan.backup}.`
@@ -1496,6 +1515,10 @@ function prune(root, path) {
1496
1515
  function applyRollback(plan) {
1497
1516
  const { root } = plan;
1498
1517
  const record = JSON.parse(readFileSync4(join4(root, plan.backup, MIGRATION_RECORD), "utf8"));
1518
+ if (plan.gateHook && existsSync4(join4(root, GATE))) {
1519
+ const off = spawnSync(process.execPath, [join4(root, GATE), "hook", "--off", "--root", root], { cwd: root, encoding: "utf8" });
1520
+ if (off.status !== 0) throw new Error(`Could not remove Joycraft's gate Stop hook from ${SETTINGS}; nothing was rolled back. ${off.stderr.trim()}`);
1521
+ }
1499
1522
  for (const path of plan.remove) {
1500
1523
  rmSync3(inside3(root, path), { force: true });
1501
1524
  prune(root, path);