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.
- package/README.md +154 -4
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-context/SKILL.md +5 -6
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +9 -8
- package/payload/.agents/skills/joycraft-entry/SKILL.md +8 -19
- package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -17
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +10 -15
- package/payload/.agents/skills/joycraft-testing/SKILL.md +3 -9
- package/payload/.agents/skills/joycraft-verify/SKILL.md +20 -21
- 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/architecture.md +2 -4
- package/payload/.joycraft/references/completion.md +16 -21
- package/payload/.joycraft/references/context.md +11 -34
- package/payload/.joycraft/references/dispatch.md +7 -40
- package/payload/.joycraft/references/gates.md +60 -0
- package/payload/.joycraft/references/retro.md +6 -15
- package/payload/.joycraft/references/settings.md +6 -3
- package/payload/.joycraft/references/setup.md +4 -4
- package/payload/.joycraft/references/testing.md +21 -21
- package/payload/.joycraft/references/worktrees.md +1 -1
- package/payload/.joycraft/runtime/completion.mjs +92 -6
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +1 -1
- package/payload/.joycraft/runtime/dispatch-start.mjs +61 -4
- package/payload/.joycraft/runtime/evidence.mjs +134 -0
- package/payload/.joycraft/runtime/gate.mjs +308 -0
- package/payload/.joycraft/runtime/identity.mjs +5 -1
- package/payload/.joycraft/runtime/queue-check.mjs +355 -0
- package/payload/.joycraft/runtime/status.mjs +46 -5
- package/payload/PIN +31 -28
- package/payload/scripts/export.mjs +5 -2
package/README.md
CHANGED
|
@@ -135,8 +135,11 @@ archive fails, the archive still counts as done.
|
|
|
135
135
|
At the end of a session the agent checks the workspace for you. You do not run
|
|
136
136
|
anything:
|
|
137
137
|
|
|
138
|
-
- **Status.** It
|
|
139
|
-
|
|
138
|
+
- **Status.** It runs the gate check (below). The check finds specs marked done with
|
|
139
|
+
no accepted review and specs whose text disagrees with the queue. It also finds
|
|
140
|
+
features that are finished but not archived.
|
|
141
|
+
- **Questions.** It asks you each follow-up question that the reviews left. See
|
|
142
|
+
[Running a queue while you are away](#running-a-queue-while-you-are-away).
|
|
140
143
|
- **Worktrees.** It removes its worker worktrees once their spec is done and merged.
|
|
141
144
|
It keeps anything unfinished, unmerged or not made by Joycraft, and says why.
|
|
142
145
|
- **One coordinator.** One session coordinates each queue, so a second session's
|
|
@@ -190,6 +193,148 @@ counts as evidence; your project keeps its own tools.
|
|
|
190
193
|
After an update, the agent checks the review loop again and asks only about what
|
|
191
194
|
changed.
|
|
192
195
|
|
|
196
|
+
### Running a queue while you are away
|
|
197
|
+
|
|
198
|
+
You can start a queue and leave. The agent asks its questions before the queue
|
|
199
|
+
starts. Work stops only for an answer that must come from you or for a broken
|
|
200
|
+
project. A broken tool that the agent cannot repair holds its spec, not the queue.
|
|
201
|
+
Other open points wait for you as a list of follow-up questions at session end.
|
|
202
|
+
You do not run a command at any step.
|
|
203
|
+
|
|
204
|
+
**Before the queue starts.** The agent checks each spec for gaps that a program can
|
|
205
|
+
find:
|
|
206
|
+
|
|
207
|
+
- An acceptance criterion has no check.
|
|
208
|
+
- A spec names an input file that does not exist and is not planned work.
|
|
209
|
+
- A spec depends on a spec that is not in the queue, or two specs depend on each
|
|
210
|
+
other.
|
|
211
|
+
- A question in the brief is still open, and a queued spec needs its answer.
|
|
212
|
+
|
|
213
|
+
The agent adds each gap to the brief as a question and asks you while you are still
|
|
214
|
+
there.
|
|
215
|
+
|
|
216
|
+
**While you are away.** A question holds a spec only for a mandatory answer: a
|
|
217
|
+
case where two readings of the brief give opposite results for a stated criterion,
|
|
218
|
+
or where a wrong guess cannot be undone. The specs that depend on it wait too. All
|
|
219
|
+
other specs go on. Three other cases hold one spec and the specs that depend on
|
|
220
|
+
it: a broken tool, a refused fourth review, or a second FAIL on the same criterion.
|
|
221
|
+
The whole queue stops only for a broken project: it does not build or install, or
|
|
222
|
+
the repository is broken. It also stops before a step that touches data or systems
|
|
223
|
+
outside the project, such as a shared database or a deploy.
|
|
224
|
+
|
|
225
|
+
Some hosts cannot start a separate reviewer context. On such a host, each spec
|
|
226
|
+
stays `in-review`, and the specs that depend on it do not start while you are away.
|
|
227
|
+
Specs that do not depend on it go on.
|
|
228
|
+
|
|
229
|
+
**When you come back.** A case that the spec does not decide does not stop the
|
|
230
|
+
queue. The reviewer takes the reading closest to your brief and writes down that
|
|
231
|
+
assumption, and the spec can complete. At session end, the agent asks you each
|
|
232
|
+
follow-up question with its spec. For a case the spec did not decide, the question
|
|
233
|
+
gives the assumption the reviewer made. The agent also asks each mandatory question
|
|
234
|
+
that holds a spec. A spec that a broken tool, a refused fourth review or a second
|
|
235
|
+
FAIL holds is not in this list of questions. Session end reports it with its
|
|
236
|
+
status, `in-review`. For a refused review or a second FAIL, the spec has a note
|
|
237
|
+
under `## Decision needed`.
|
|
238
|
+
|
|
239
|
+
**Why you want it.** The questions come while you are there, so a queue does not
|
|
240
|
+
wait hours for a small answer. A guess is not hidden: each one comes back to you as
|
|
241
|
+
a question.
|
|
242
|
+
|
|
243
|
+
**Start a queue and leave.** Say:
|
|
244
|
+
|
|
245
|
+
```text
|
|
246
|
+
Build <what you want> with Joycraft. I will be away while the queue runs.
|
|
247
|
+
Before you start the queue, check it for gaps and ask me every question now.
|
|
248
|
+
While I am away, stop only for an answer that must come from me or for a broken project.
|
|
249
|
+
At session end, ask me each follow-up question with the assumption the reviewer made.
|
|
250
|
+
Do not archive a feature until I have answered its follow-up questions.
|
|
251
|
+
Do not commit to the default branch, push, publish, or ask me for API keys.
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
**Get the follow-up questions.** The questions stay available until the feature is
|
|
255
|
+
archived. Before then, you can ask for them again later, or in a new session:
|
|
256
|
+
|
|
257
|
+
```text
|
|
258
|
+
Run Joycraft's session end. Before you archive a feature, ask me each follow-up
|
|
259
|
+
question from its reviews, with the spec and the assumption the reviewer made, and
|
|
260
|
+
each question that holds a spec.
|
|
261
|
+
Do not commit, publish, or ask me for API keys.
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
**What it does not do.**
|
|
265
|
+
|
|
266
|
+
- The queue check finds only the gaps that a program can find. The agent reads each
|
|
267
|
+
spec for the rest, for example a criterion that needs work from a later spec.
|
|
268
|
+
- An assumption can be wrong. You see it at session end, after the spec is done.
|
|
269
|
+
- After a feature is archived, session end no longer lists its follow-up questions.
|
|
270
|
+
The reviews stay in the archive.
|
|
271
|
+
- A criterion can still pass on a test that only the implementing agent wrote.
|
|
272
|
+
Joycraft does not yet check that the test fails for broken behavior.
|
|
273
|
+
|
|
274
|
+
### The gates: no spec is done without an accepted review
|
|
275
|
+
|
|
276
|
+
Joycraft's rule is that only an accepted review completes a spec. Without the
|
|
277
|
+
gates, this rule is an instruction in a skill. An agent can forget the rule or skip
|
|
278
|
+
it, for example late in a long session. The gates make the rule a check.
|
|
279
|
+
|
|
280
|
+
**What the gate stops.** The gate check finds three problems:
|
|
281
|
+
|
|
282
|
+
- A spec is marked done with no accepted review, no acceptance from you and no waiver.
|
|
283
|
+
- A spec has one status in the queue and a different status in the spec file.
|
|
284
|
+
- Joycraft cannot read a queue file or a spec file.
|
|
285
|
+
|
|
286
|
+
It sends the agent back with the spec or file name and the next step. A spec that waits at
|
|
287
|
+
`in-review` is not a problem.
|
|
288
|
+
|
|
289
|
+
**Why you want it.** Use the gates for long sessions and for sessions that you do
|
|
290
|
+
not watch. A prompt tells the agent what to do, but a prompt is not a guarantee.
|
|
291
|
+
With the gates on, Claude Code runs the check each time the agent tries to stop. The
|
|
292
|
+
agent cannot stop until the problem is gone.
|
|
293
|
+
|
|
294
|
+
**Before you turn them on.** An older project can have specs marked done with no
|
|
295
|
+
accepted review. The check sends each one back for a review. To see them first, say:
|
|
296
|
+
|
|
297
|
+
```text
|
|
298
|
+
Run Joycraft's gate check with `node .joycraft/runtime/gate.mjs check` and show me
|
|
299
|
+
what it names. Change nothing yet.
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
Do this also after you update an older project to 1.4.1 or later, because session
|
|
303
|
+
end now runs the same check.
|
|
304
|
+
|
|
305
|
+
**Turn them on.** Say:
|
|
306
|
+
|
|
307
|
+
```text
|
|
308
|
+
Turn on Joycraft's gates.
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
The agent shows you the change to `.claude/settings.json` on a page. It writes the
|
|
312
|
+
change only on your yes. The change adds one Stop hook and no other line. Setup
|
|
313
|
+
also offers the gates one time.
|
|
314
|
+
|
|
315
|
+
**Turn them off.** Say:
|
|
316
|
+
|
|
317
|
+
```text
|
|
318
|
+
Turn off Joycraft's gates.
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
The agent removes Joycraft's hook. Your own hooks stay. If you remove Joycraft from
|
|
322
|
+
the project, the agent removes this hook first.
|
|
323
|
+
|
|
324
|
+
**What the gates do not do.**
|
|
325
|
+
|
|
326
|
+
- The hook is for Claude Code only for now. On the other agents, the session-end
|
|
327
|
+
skill runs the check. That step is an instruction, so the agent can still skip it.
|
|
328
|
+
- There is no CI check. Joycraft does not check your pull requests.
|
|
329
|
+
- The hook is not a sandbox. A shell command can still change the queue file. The
|
|
330
|
+
check finds the result at the next stop.
|
|
331
|
+
|
|
332
|
+
**A fourth review is refused.** On every agent, one spec gets at most three
|
|
333
|
+
reviews. A round is one set of reviewed inputs, so a new review of the same code
|
|
334
|
+
does not count again. Reviewer startup prints the round and refuses a fourth
|
|
335
|
+
review. The agent then records `## Decision needed` in the spec and holds that spec.
|
|
336
|
+
The specs that do not depend on it go on.
|
|
337
|
+
|
|
193
338
|
## Answering questions: the decision page
|
|
194
339
|
|
|
195
340
|
When the agent needs you to choose between options, it asks in your question
|
|
@@ -232,8 +377,9 @@ project:
|
|
|
232
377
|
|
|
233
378
|
All of it lives in your repository. Joycraft collects no data and does not call an AI
|
|
234
379
|
model itself. Its only network use is the version check below. Joycraft adds no
|
|
235
|
-
agent hooks and changes no agent settings
|
|
236
|
-
|
|
380
|
+
agent hooks and changes no agent settings, except the gate hook that you turn on
|
|
381
|
+
([The gates](#the-gates-no-spec-is-done-without-an-accepted-review)). A command
|
|
382
|
+
after an archive runs only if you asked for one.
|
|
237
383
|
|
|
238
384
|
## Updates
|
|
239
385
|
|
|
@@ -279,6 +425,10 @@ in [Prompts](docs/prompts.md):
|
|
|
279
425
|
| Change a setting | "Keep Joycraft's specs in working/features." |
|
|
280
426
|
| Connect your wiki | "Link our wiki and keep it up to date." |
|
|
281
427
|
| Clean up | "Clean up the docs and the workspace." |
|
|
428
|
+
| Start a queue and leave | "Build <what you want> with Joycraft. I will be away while the queue runs." |
|
|
429
|
+
| Get the follow-up questions | "Run Joycraft's session end and ask me each follow-up question." |
|
|
430
|
+
| Turn the gates on | "Turn on Joycraft's gates." |
|
|
431
|
+
| Turn the gates off | "Turn off Joycraft's gates." |
|
|
282
432
|
| Undo the 1.0 upgrade | "Undo this project's upgrade to Joycraft 1.0." |
|
|
283
433
|
| Remove Joycraft | "Remove Joycraft from this project." |
|
|
284
434
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "joycraft",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.0",
|
|
4
4
|
"description": "Install and update Joycraft, a skill bundle and runtime for agent-led software work, in any project",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -13,8 +13,8 @@
|
|
|
13
13
|
"payload"
|
|
14
14
|
],
|
|
15
15
|
"joycraft": {
|
|
16
|
-
"release": "1.
|
|
17
|
-
"summary": "
|
|
16
|
+
"release": "1.5.0",
|
|
17
|
+
"summary": "Start a queue and leave: the agent asks its questions before the queue starts and stops only for a mandatory answer or a broken project. At session end, it asks you the other open points as follow-up questions.",
|
|
18
18
|
"autoSafeEligible": false
|
|
19
19
|
},
|
|
20
20
|
"scripts": {
|
|
@@ -20,16 +20,15 @@ node .joycraft/runtime/context/cli.mjs --query "<current request>"
|
|
|
20
20
|
Narrow discovery with `--paths docs/context src/relevant-area` when the relevant
|
|
21
21
|
area is known. Retrieval excludes `docs/archive/` unless historical material is
|
|
22
22
|
specifically needed; add `--history` to inspect it as reading context, never as
|
|
23
|
-
current authority.
|
|
24
|
-
installed; otherwise they come in local-search order. Read `.joycraft/references/context.md` for output
|
|
23
|
+
current authority. Results come in local-search order. Read `.joycraft/references/context.md` for output
|
|
25
24
|
and failure details.
|
|
26
25
|
|
|
27
|
-
Read useful
|
|
28
|
-
reading order; low scores do not remove files or define task scope. Check omitted
|
|
29
|
-
|
|
26
|
+
Read useful source files and follow their relevant links. Local scores guide
|
|
27
|
+
reading order; low scores do not remove files or define task scope. Check omitted
|
|
28
|
+
and unreadable reasons.
|
|
30
29
|
Refine the query or paths when local keyword matching misses a known dependency.
|
|
31
30
|
When the requested change has an unclear state, data, or responsibility seam,
|
|
32
|
-
trace the actual counterpart sources beyond the
|
|
31
|
+
trace the actual counterpart sources beyond the result list: for example, the
|
|
33
32
|
owner alongside its callers, readers, writers, or persistence boundary. Add
|
|
34
33
|
discovered sources to the work's declared inputs and report any unresolved
|
|
35
34
|
coverage. Read `.joycraft/references/architecture.md` only for that
|
|
@@ -27,9 +27,9 @@ environment can show is not a criterion; list it under the spec's "Deferred unti
|
|
|
27
27
|
deploy" section instead. Include the brief, spec and exact
|
|
28
28
|
relevant code, test/configuration and fixture paths as verification inputs. Plan
|
|
29
29
|
paths explicitly and update them when implementation reveals more relevant files.
|
|
30
|
-
|
|
30
|
+
Declare a deletion only as an explicit
|
|
31
31
|
non-requirement input with `state: 'absent'`; a rename needs the old absent input
|
|
32
|
-
and the new present one.
|
|
32
|
+
and the new present one. Change scope is opt-in:
|
|
33
33
|
add `verification.changeScope` only when a spec needs a scope check, with an
|
|
34
34
|
explicit full base SHA recorded before implementation. Give any unrelated changed
|
|
35
35
|
path a narrow path-and-reason exclusion; do not turn a broad branch or directory
|
|
@@ -54,12 +54,13 @@ between the intended behavior and the coupled path. Use
|
|
|
54
54
|
check; omit this detail for a simple local edit. It does not replace the brief as
|
|
55
55
|
the authority for product behavior.
|
|
56
56
|
|
|
57
|
-
Before
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
57
|
+
Before handing the queue on, run
|
|
58
|
+
`node .joycraft/runtime/queue-check.mjs --queue <queue>` and act on each gap it
|
|
59
|
+
names. Then check what it cannot; a failing spec goes back to the brief as an
|
|
60
|
+
open decision: open-input rules name their check set, costlier error and
|
|
61
|
+
threshold; no criterion depends on an unbuilt spec; runtime and visual criteria
|
|
62
|
+
carry their environment recipe or are deferred; settled rulings are quoted with
|
|
63
|
+
their ID. Check coverage against the original request and
|
|
63
64
|
resolved answers, not just the spec list. Retain visible pending choices and dependencies. Pass the ready queue
|
|
64
65
|
to `joycraft-implement`, which continues authorized work without per-spec approval.
|
|
65
66
|
For native execution, hand off raw sources and the selected queue/spec to the
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: joycraft-entry
|
|
3
3
|
description: Start any Joycraft work. After Joycraft is installed, when asked to "set up Joycraft", "check the context map", change Joycraft settings or remove Joycraft, read the project, interview the user and build the context map in AGENTS.md; then turn a repair, feature, or mixed request into a context-backed brief and the next useful action.
|
|
4
|
-
compatibility: Setup
|
|
4
|
+
compatibility: Setup helpers require Node.js 22+ and the installed .joycraft runtime only when used; ordinary brief and context navigation has no project-stack prerequisite.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Run `node .joycraft/runtime/update-check.mjs check` first, once per session. If it
|
|
@@ -24,7 +24,7 @@ alone does not start a full setup.
|
|
|
24
24
|
|
|
25
25
|
Read existing project instructions first. During an upgrade, inspect the installed
|
|
26
26
|
manifest’s `legacyConflicts` and reconcile competing old skill discovery before
|
|
27
|
-
|
|
27
|
+
choosing skills; preserved custom content is not a completed migration.
|
|
28
28
|
On a bare project, offer the
|
|
29
29
|
[kickoff](../../../.joycraft/references/setup.md#kickoff-for-a-new-project)
|
|
30
30
|
in one line before any brief or scaffold, and run it when the user asks for it on
|
|
@@ -49,7 +49,7 @@ scope or a consequential choice.
|
|
|
49
49
|
|
|
50
50
|
When an unclear state, data, or responsibility boundary could change the work,
|
|
51
51
|
do focused discovery before splitting it: inspect the actual owner and its
|
|
52
|
-
callers, readers, writers, or other coupled counterpart.
|
|
52
|
+
callers, readers, writers, or other coupled counterpart. Search can point to
|
|
53
53
|
sources, but does not replace that trace. Keep settled product behavior in the
|
|
54
54
|
brief; record only durable, source-backed navigation in the project's existing
|
|
55
55
|
context homes. Read `.joycraft/references/architecture.md` for this
|
|
@@ -109,6 +109,9 @@ page, connect their wiki, see their settings or remove Joycraft, follow
|
|
|
109
109
|
[settings](../../../.joycraft/references/settings.md). The user never edits
|
|
110
110
|
`joycraft.yaml` or runs a Joycraft command by hand.
|
|
111
111
|
|
|
112
|
+
**Gates by request.** When the user asks to turn Joycraft's gates on or off, or
|
|
113
|
+
what they do, follow [gates](../../../.joycraft/references/gates.md).
|
|
114
|
+
|
|
112
115
|
**Show documents as pages.** A brief, plan, spec set or review that the user must
|
|
113
116
|
read or approve is also rendered, never left as Markdown in chat: the decision
|
|
114
117
|
artifact for a brief, an HTML page for anything else. Show it as
|
|
@@ -132,20 +135,6 @@ existing direct path when it fits the request. Do not turn routine data entry
|
|
|
132
135
|
into a code-spec factory or create per-record plans when an approved batch tool
|
|
133
136
|
already owns the operation. Preserve its validation, approval and readback rules.
|
|
134
137
|
|
|
135
|
-
When a native hook adds routing advice to the prompt, use it to select relevant
|
|
136
|
-
skills. Keep all expressed goals even when a classifier misses a signal. Do not
|
|
137
|
-
repeat a live routing call when the hook already provided current advice.
|
|
138
|
-
Routing does not approve scope, answer a decision, or establish evidence.
|
|
139
|
-
|
|
140
138
|
Use `joycraft-context` when you need to find relevant project files beyond the
|
|
141
|
-
context map. Its deterministic search
|
|
142
|
-
|
|
143
|
-
failures, read `.joycraft/references/hooks-runtime.md`. Treat unavailable
|
|
144
|
-
checks as unavailable, never as approval. For a denial, compare its cited scope
|
|
145
|
-
with the current task and the actual human question/answer. Repair missing
|
|
146
|
-
source delivery once through the documented binding flow, then resume understood
|
|
147
|
-
authorized work. Do not ask for the same permission again, move a chat answer to
|
|
148
|
-
a different document as an enforcement workaround, weaken a gate, or wrap a
|
|
149
|
-
denied command. Ask the host for the legitimate correction when needed.
|
|
150
|
-
If native hooks are absent and routing is materially uncertain, the explicit adapter in `.joycraft/references/routing.md` remains available.
|
|
151
|
-
When requested setup includes native hooks, use [Codex hook installation](../../../.joycraft/references/hooks-install.md) or [Claude Code hook installation](../../../.joycraft/references/hooks-claude.md) for the active host. Installation and project setup do not establish host trust or execution.
|
|
139
|
+
context map. Its deterministic search provides pointers; read the selected
|
|
140
|
+
source before relying on it.
|
|
@@ -30,22 +30,20 @@ For normal native execution, the host launches the selected worker first. The
|
|
|
30
30
|
child bootstraps from its actual root, then runs `dispatch-start.mjs --role
|
|
31
31
|
implementer` with its actual native identity before any tasked edit or mutation.
|
|
32
32
|
The coordinator runs that start itself only when it is the implementer actor.
|
|
33
|
-
Use the returned packet only when `ready` is true.
|
|
34
|
-
workflow can be ready; unavailable hook status is not a new permission gate for
|
|
35
|
-
all work. When startup returns unenforced, hold only that claimed enforced task,
|
|
36
|
-
report why, and continue unrelated authorized or manual/disabled workflow.
|
|
33
|
+
Use the returned packet only when `ready` is true.
|
|
37
34
|
|
|
38
35
|
If existing independent reports reveal a possible recurring failure, follow [recurring failure guidance](../../../.joycraft/references/recurring-failures.md) before carrying it forward: inspect the current scoped sources and actual counterpart path or journey, then provide any proposed lesson as exact inputs through the existing dispatch flow. A verified repair may establish its local project fact; a broader method benefit remains pending later reuse.
|
|
39
36
|
|
|
40
|
-
Before the first dispatch, claim the queue
|
|
41
|
-
|
|
37
|
+
Before the first dispatch, claim the queue with your actual host session ID and
|
|
38
|
+
pass it as `--coordinator-session` to every startup:
|
|
42
39
|
|
|
43
40
|
```sh
|
|
44
41
|
node .joycraft/runtime/coordinator.mjs claim --queue <queue> --session <your-session-id> --host <host>
|
|
45
42
|
```
|
|
46
43
|
|
|
47
|
-
If another session holds the queue, stop and report the holder;
|
|
48
|
-
|
|
44
|
+
If another session holds the queue, stop and report the holder; use
|
|
45
|
+
`--take-over` only when the user says that session has ended. Then run
|
|
46
|
+
`node .joycraft/runtime/queue-check.mjs --queue <queue>`; act on each gap.
|
|
49
47
|
|
|
50
48
|
For a spec marked `execution.parallel: true`, use a separate linked worktree for
|
|
51
49
|
each concurrent mutator, including its build/cache state. Create it with
|
|
@@ -58,7 +56,7 @@ isolation cannot be obtained, replan the affected wave and set the current
|
|
|
58
56
|
queue entry's `execution.parallel` to `false` before dispatch, recording why;
|
|
59
57
|
then run it serially. Otherwise leave it unstarted.
|
|
60
58
|
|
|
61
|
-
Implement the spec and run meaningful checks and any relevant rendered inspection during implementation. Do not defer ordinary checks to the batch boundary. Run each test command
|
|
59
|
+
Implement the spec and run meaningful checks and any relevant rendered inspection during implementation. Do not defer ordinary checks to the batch boundary. Run each test command with `node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`; see [running tests](../../../.joycraft/references/testing.md#running-tests). Write one focused test per acceptance `Check:`, from the spec rather than the code, and tag it with its queue criterion ID as `[AC:<criterion-id>]` in the test name or a comment; if a criterion or test looks wrong, report a spec gap instead of editing it to pass. When the implementation is finished, set it `in-review` with `node .joycraft/runtime/completion.mjs submit --queue <queue> --spec <id>`. A passing test suite, commit, or empty ready set does not accept the work.
|
|
62
60
|
|
|
63
61
|
Honor the queue's commit mode. In `batch`, commit and review the independent ready
|
|
64
62
|
wave at its boundary before advancing its dependents; do not wait for an entire
|
|
@@ -77,9 +75,9 @@ It needs actual host session/agent identity and available current authority
|
|
|
77
75
|
as described in [dispatch guidance](../../../.joycraft/references/dispatch.md).
|
|
78
76
|
Write its packet or subject beneath a confirmed Git-ignored project-local
|
|
79
77
|
directory, not among reviewed sources.
|
|
80
|
-
If
|
|
81
|
-
|
|
82
|
-
|
|
78
|
+
If a separate review context/capability is unavailable, leave the spec
|
|
79
|
+
`in-review`; do not invent an ID to continue. This holds the claimed review,
|
|
80
|
+
not unrelated authorized work.
|
|
83
81
|
|
|
84
82
|
When a recorded tool breaks during a run (the dev server does not start, a
|
|
85
83
|
port is taken, the browser or simulator crashes), repair it with what the user
|
|
@@ -101,11 +99,12 @@ Only the guarded completion path can move an `in-review` spec to `done`. Use its
|
|
|
101
99
|
|
|
102
100
|
When a current independent review is `FAIL` or `UNVERIFIED`, first fix
|
|
103
101
|
straightforward failures within the existing authorization and obtain a fresh
|
|
104
|
-
review. A spec gets at most three reviews
|
|
105
|
-
|
|
106
|
-
on the same criterion
|
|
107
|
-
|
|
108
|
-
|
|
102
|
+
review. A spec gets at most three reviews: reviewer startup prints
|
|
103
|
+
`reviewRound` and refuses a fourth. If startup refuses a review or a second FAIL
|
|
104
|
+
on the same criterion occurs, send no further fix and never amend acceptance
|
|
105
|
+
yourself: note it under `## Decision needed` in the spec, leave it `in-review`,
|
|
106
|
+
and continue independent ready work. Treat a held `decision-needed` finding
|
|
107
|
+
(`$joycraft-verify`) the same, without the note: `status.mjs` lists it. An owner can explicitly accept the
|
|
109
108
|
current findings and their stated limits through `accept-owner`; that is a
|
|
110
109
|
bounded exception, not a PASS or verified result. Do not ask merely because a
|
|
111
110
|
review failed. Ask only when an explicit override is needed to proceed and a
|
|
@@ -8,11 +8,6 @@ compatibility: Requires Node.js 22+ and the installed .joycraft runtime for the
|
|
|
8
8
|
|
|
9
9
|
Use this skill when pausing or finishing an authorized queue session.
|
|
10
10
|
|
|
11
|
-
On Claude `SessionEnd`, write only the local session summary and deduplicate the
|
|
12
|
-
transition record. Do not call an API or archive from that hook. On other hosts,
|
|
13
|
-
use their metrics/manual or portable summary path when available; never infer a
|
|
14
|
-
Claude lifecycle event from a generic session boundary.
|
|
15
|
-
|
|
16
11
|
Read each touched queue and report the real state of every affected spec: `todo`, `in-review`, or `done`. `done` must have either an accepted PASS report receipt or a completion-helper owner-acceptance record bound to a current failed or unverified report; a commit, PASS command, or implementer assertion is not acceptance. Keep blocked or failed dependency branches explicit while identifying independent ready work that can continue next.
|
|
17
12
|
|
|
18
13
|
If the session stops or restarts a concurrent run, report its recorded
|
|
@@ -20,8 +15,7 @@ coordinator ownership, captured refs, known worker trees, leases, locks, and
|
|
|
20
15
|
runtime processes. Release only resources demonstrably owned by that run;
|
|
21
16
|
retain ambiguous merges, locks, processes, and trees for diagnosis. Do not
|
|
22
17
|
force local state to a remote tip. Start a replacement only from the durable
|
|
23
|
-
run journal and a newly printed dispatch plan.
|
|
24
|
-
project/native runtime boundary; it does not enforce lifecycle behavior.
|
|
18
|
+
run journal and a newly printed dispatch plan.
|
|
25
19
|
|
|
26
20
|
For each completed spec, report the implementation revision, independent reviewer session ID, report and receipt paths, actual commands and outcomes, visual inspection status where required, and known limitations. For owner-accepted work, also report the owner-acceptance record and its inherited limits as `done, owner-accepted with <limits>`; preserve the original `FAIL` or `UNVERIFIED` report rather than calling it PASS or verified. List each spec completed under a feature waiver as `done, waived by the user: "<instruction>"`, with any report's real verdict; never call it reviewed or verified.
|
|
27
21
|
|
|
@@ -29,20 +23,21 @@ If a completion operation failed or was interrupted, do not declare success or h
|
|
|
29
23
|
|
|
30
24
|
Leave enough project-relative paths and next actions for another session to resume the autonomous ready authorized queue without recreating settled context or decisions.
|
|
31
25
|
|
|
32
|
-
Before ending
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
26
|
+
Before ending, run `node .joycraft/runtime/status.mjs --fix` (repairs lagging
|
|
27
|
+
frontmatter of accepted specs, lists features ready to archive) and
|
|
28
|
+
`node .joycraft/runtime/gate.mjs check`. Do the step each gate message names,
|
|
29
|
+
such as a completing command. Tell the user each message you could not clear.
|
|
30
|
+
Ask the user each status `questions` entry (findings rule: `$joycraft-verify`).
|
|
31
|
+
Then preview `node .joycraft/runtime/worktrees.mjs prune` and apply it with
|
|
32
|
+
`--apply`: it removes only clean, integrated trees of done specs and keeps the
|
|
33
|
+
rest with their reason. Report kept trees and their size from `list`.
|
|
38
34
|
When this session coordinated a queue and no work on it remains, release the
|
|
39
35
|
lease with `node .joycraft/runtime/coordinator.mjs release --queue <queue> --session <your-session-id>`. See [worker isolation](../../../.joycraft/references/worktrees.md)
|
|
40
36
|
when the session used parallel mutable workers.
|
|
41
37
|
|
|
42
38
|
When an `UNVERIFIED` review identifies only an environment condition, record
|
|
43
39
|
that condition and arrange a fresh review after it is corrected. Do not create
|
|
44
|
-
an unchanged-code fix round.
|
|
45
|
-
owner of acceptance and status changes.
|
|
40
|
+
an unchanged-code fix round.
|
|
46
41
|
|
|
47
42
|
Before ending, and before any archival, route each reusable fact the session established (a decision with its reason, a trap, a reference, a production fact) to its one home per [knowledge guidance](../../../.joycraft/references/knowledge.md). Rewrite a changed fact in place and put its reason in the decision log; add a context-map row for a new home; keep each touched row's "read when" true. Leave feature intent in the brief. A session with nothing reusable changes no context file.
|
|
48
43
|
|
|
@@ -6,12 +6,6 @@ compatibility: The optional shared evidence validator requires Node.js 22+ and t
|
|
|
6
6
|
|
|
7
7
|
# Useful testing evidence
|
|
8
8
|
|
|
9
|
-
Use any post-edit hook findings as candidate gaps to inspect against the active
|
|
10
|
-
requirements and relevant tests. A flag is not proof of a defect, and no flag is
|
|
11
|
-
not proof of coverage. Keep valid gaps visible until a useful assertion or
|
|
12
|
-
observed interaction resolves them; missing tests during intermediate edits do
|
|
13
|
-
not require stopping understood implementation.
|
|
14
|
-
|
|
15
9
|
Read the active requirements and relevant existing tests. Choose the smallest
|
|
16
10
|
boundary that can establish each claim: real function inputs for arithmetic,
|
|
17
11
|
composed transitions for stateful behavior, rendered interaction for UI behavior.
|
|
@@ -42,9 +36,9 @@ than from the code, sized like neighboring tests. Do not commit tests of one-off
|
|
|
42
36
|
run state. If a criterion or test looks wrong, or conflicts with a later owner
|
|
43
37
|
decision, report a spec gap; never edit it to pass.
|
|
44
38
|
|
|
45
|
-
Run each test command
|
|
46
|
-
|
|
47
|
-
|
|
39
|
+
Run each test command with
|
|
40
|
+
`node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`;
|
|
41
|
+
see [running tests](../../../.joycraft/references/testing.md#running-tests).
|
|
48
42
|
|
|
49
43
|
Retain the executed command, actual exit status and unfiltered output. Describe
|
|
50
44
|
what happened separately from what was expected. Bind observations and supporting
|
|
@@ -29,10 +29,9 @@ prepare a source packet for a manual boundary, but it must not bind the child
|
|
|
29
29
|
using the parent's identity. After launch, the reviewer child bootstraps at its
|
|
30
30
|
actual root and runs `dispatch-start.mjs --role reviewer` with its own actual
|
|
31
31
|
native identity, which captures the subject, preflights delivery, writes the
|
|
32
|
-
bounded packet
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
result holds only the claimed review, not unrelated work.
|
|
32
|
+
bounded packet. If the real ID or a separate reviewer context is unavailable,
|
|
33
|
+
leave the spec `in-review`; do not manufacture either. This holds only the
|
|
34
|
+
claimed review, not unrelated work.
|
|
36
35
|
Reviewer startup output also carries `trace`, the spec's criteria with the tests
|
|
37
36
|
tagged `[AC:<criterion-id>]` (`node .joycraft/runtime/trace.mjs --queue <queue> --spec <id>`
|
|
38
37
|
produces the same). Report untraced criteria as findings; a missing tag alone is
|
|
@@ -44,34 +43,34 @@ Dispatch `collaboration.spawn_agent` with `fork_turns: "none"` and the packet's
|
|
|
44
43
|
|
|
45
44
|
When already dispatched as the independent reviewer, perform the review directly; do not recursively dispatch another reviewer. Read the parent brief, spec, queue entry, declared criteria and exact verification inputs. Use the supplied subject, set independence truthfully, and do not self-certify implementation from your own context.
|
|
46
45
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
score or clean hook receipt cannot establish acceptance. Check changed tests for
|
|
50
|
-
weakened assertions that could hide the requested behavior.
|
|
46
|
+
Check changed tests for weakened assertions that could hide the requested
|
|
47
|
+
behavior.
|
|
51
48
|
|
|
52
49
|
Review scope as well as behavior: determine whether the listed inputs and criteria cover the requested work, including relevant newly changed files. For a cross-boundary change, inspect the combined observable behavior across the relevant producer, consumer, state or storage boundary; separate green helpers, snapshots, or assertion counts do not establish that behavior. If a material counterpart or owning decision/context source was omitted, report the scope gap and require its exact path to be added before a fresh current review subject is prepared. Preserve the snapshot's implementation revision as provenance while checking its current bound inputs. A changed, missing, or renamed input makes the subject stale; do not substitute a newer HEAD as its identity.
|
|
53
50
|
|
|
54
51
|
Create a schema-v1 verification report tied to that subject, using the shared fields in [.joycraft/contracts/types.d.ts](../../../.joycraft/contracts/types.d.ts). For every declared criterion, provide PASS observations for its required evidence kinds. Keep unfiltered command output and its real exit status in hashed, project-relative receipts. A source scan supports only structural observations. Visual observations require a reviewer-inspected render plus route, state, viewport, interactions, and outcomes. Take evidence with the package's recorded tool, start command and evidence command from the packet's `reviewLoop` (`section`: the `Review loop` section of `AGENTS.md`; `local`: this machine's host tools), within that tool's `canShow`. A claim beyond `canShow`, or in a package the user skipped, is an agreed limit, not `UNVERIFIED`: check what the agreed tool can show, say in plain words how you checked, and leave what is left to the parent agent. A picture-only tool gives `interactions: []`. `UNVERIFIED` means a check that should have run and did not: the tool broke, the app did not start, or a render was saved but not inspected. On a tool break, first repair with what the user agreed to: restart the dev server, free the port, relaunch the browser or simulator, retry once. A repair never installs, upgrades or reconfigures anything. If it still fails, record `UNVERIFIED` with `cause: 'tool-break'` and the reason. Mark a failing result or an unresolved concern as `FAIL` or `UNVERIFIED` truthfully.
|
|
55
52
|
|
|
56
|
-
Run each test command
|
|
57
|
-
|
|
58
|
-
|
|
53
|
+
Run each test command with
|
|
54
|
+
`node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`;
|
|
55
|
+
see [running tests](../../../.joycraft/references/testing.md#running-tests). Record an unresolved hang as `UNVERIFIED` with its receipt.
|
|
59
56
|
|
|
60
57
|
Run the dispatch helper's `check-report` before completion. It reuses the same
|
|
61
58
|
subject, receipt, and evidence validators without changing a queue status. If
|
|
62
59
|
it rejects a packaging or report problem, return the correction to this same
|
|
63
60
|
reviewer; do not invent observations or replace the independent identity.
|
|
64
61
|
|
|
65
|
-
Items under a spec's "Deferred until deploy" section are not criteria
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
62
|
+
Items under a spec's "Deferred until deploy" section are not criteria; list
|
|
63
|
+
each as a `follow-up` finding for the owner.
|
|
64
|
+
|
|
65
|
+
Findings rule: give each `findings` entry its `class`, `origin`, and `criterion`
|
|
66
|
+
or `at` (file:line or receipt). `blocking` is only a failing stated criterion or
|
|
67
|
+
a reproducible defect or regression in the changed code. A case the spec does
|
|
68
|
+
not decide is a `follow-up`: take the reading closest to the brief's intent,
|
|
69
|
+
recorded as `assumption`. `decision-needed` is only for two readings that give
|
|
70
|
+
opposite verdicts on a stated criterion, or a guess that cannot be undone; it
|
|
71
|
+
holds this spec and its dependents, never the queue. A probe outside the named
|
|
72
|
+
checks is a `follow-up` unless it regresses. Never repeat an earlier round's
|
|
73
|
+
finding as new.
|
|
75
74
|
|
|
76
75
|
Set a PASS verdict only when scope is reviewed, all required evidence is sufficient, and no blocking finding or unresolved UNVERIFIED evidence remains. Then run guarded completion:
|
|
77
76
|
|
|
@@ -24,14 +24,14 @@ message.
|
|
|
24
24
|
|
|
25
25
|
Write one focused test per acceptance `Check:`, taken from the spec rather than
|
|
26
26
|
from your code, sized like neighboring tests. Tag each with its queue criterion
|
|
27
|
-
ID as `[AC:<criterion-id>]` in the test name or a comment. Run each test command
|
|
28
|
-
|
|
27
|
+
ID as `[AC:<criterion-id>]` in the test name or a comment. Run each test command with
|
|
28
|
+
`node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`; see
|
|
29
29
|
`.joycraft/references/testing.md#running-tests`. Never wait in a
|
|
30
30
|
foreground loop, never weaken an existing test, and never change the spec's acceptance:
|
|
31
31
|
if a criterion or test looks wrong, report it as a spec gap.
|
|
32
32
|
|
|
33
33
|
For a user-facing change, render and inspect it as `joycraft-testing` describes.
|
|
34
|
-
Before you finish, run the project's
|
|
35
|
-
in `AGENTS.md`,
|
|
36
|
-
status and the commit
|
|
34
|
+
Before you finish, run the project's test, typecheck and lint commands named
|
|
35
|
+
in `AGENTS.md`, then `node .joycraft/runtime/completion.mjs submit`, commit by
|
|
36
|
+
file name, and report each command, its exit status and the commit. Keep the final message short: what changed,
|
|
37
37
|
checks and results, open gaps.
|
|
@@ -23,18 +23,15 @@ message.
|
|
|
23
23
|
|
|
24
24
|
Judge the current code against every acceptance bullet and its `Check:`, and
|
|
25
25
|
against the owner intent in the brief. Reuse a suite receipt bound to the same
|
|
26
|
-
revision instead of rerunning the full suite; run the spec's own tests once
|
|
27
|
-
|
|
26
|
+
revision instead of rerunning the full suite; run the spec's own tests once with
|
|
27
|
+
`node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`. Never give a verdict while
|
|
28
28
|
a command you started is still running.
|
|
29
29
|
|
|
30
30
|
Startup output includes `trace`: each criterion with its `[AC:<id>]` tests. Report
|
|
31
31
|
each untraced criterion as a finding. A missing tag alone is not a FAIL; judge the
|
|
32
32
|
criterion by what you observe.
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
stated criterion, or a reproducible defect or regression in the changed code with
|
|
36
|
-
file:line or a receipt, blocks. A case the spec does not decide is "decision
|
|
37
|
-
needed", not FAIL. Do not repeat an earlier round's finding as new.
|
|
34
|
+
Record findings by the findings rule in the verify skill.
|
|
38
35
|
|
|
39
36
|
Take evidence with each package's recorded tool from the packet's `reviewLoop`,
|
|
40
37
|
within its `canShow`, and say in plain words how you checked. A limit the user
|