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
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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
|
|
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);
|