joycraft 1.4.1 → 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 +86 -3
- 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 +11 -10
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +2 -2
- 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/testing.md +21 -21
- package/payload/.joycraft/runtime/completion.mjs +92 -6
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +1 -1
- package/payload/.joycraft/runtime/evidence.mjs +134 -0
- 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 +18 -17
package/README.md
CHANGED
|
@@ -138,6 +138,8 @@ anything:
|
|
|
138
138
|
- **Status.** It runs the gate check (below). The check finds specs marked done with
|
|
139
139
|
no accepted review and specs whose text disagrees with the queue. It also finds
|
|
140
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).
|
|
141
143
|
- **Worktrees.** It removes its worker worktrees once their spec is done and merged.
|
|
142
144
|
It keeps anything unfinished, unmerged or not made by Joycraft, and says why.
|
|
143
145
|
- **One coordinator.** One session coordinates each queue, so a second session's
|
|
@@ -191,6 +193,84 @@ counts as evidence; your project keeps its own tools.
|
|
|
191
193
|
After an update, the agent checks the review loop again and asks only about what
|
|
192
194
|
changed.
|
|
193
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
|
+
|
|
194
274
|
### The gates: no spec is done without an accepted review
|
|
195
275
|
|
|
196
276
|
Joycraft's rule is that only an accepted review completes a spec. Without the
|
|
@@ -219,8 +299,8 @@ Run Joycraft's gate check with `node .joycraft/runtime/gate.mjs check` and show
|
|
|
219
299
|
what it names. Change nothing yet.
|
|
220
300
|
```
|
|
221
301
|
|
|
222
|
-
Do this also after you update an older project to 1.4.1, because session
|
|
223
|
-
runs the same check.
|
|
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.
|
|
224
304
|
|
|
225
305
|
**Turn them on.** Say:
|
|
226
306
|
|
|
@@ -252,7 +332,8 @@ the project, the agent removes this hook first.
|
|
|
252
332
|
**A fourth review is refused.** On every agent, one spec gets at most three
|
|
253
333
|
reviews. A round is one set of reviewed inputs, so a new review of the same code
|
|
254
334
|
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
|
|
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.
|
|
256
337
|
|
|
257
338
|
## Answering questions: the decision page
|
|
258
339
|
|
|
@@ -344,6 +425,8 @@ in [Prompts](docs/prompts.md):
|
|
|
344
425
|
| Change a setting | "Keep Joycraft's specs in working/features." |
|
|
345
426
|
| Connect your wiki | "Link our wiki and keep it up to date." |
|
|
346
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." |
|
|
347
430
|
| Turn the gates on | "Turn on Joycraft's gates." |
|
|
348
431
|
| Turn the gates off | "Turn off Joycraft's gates." |
|
|
349
432
|
| Undo the 1.0 upgrade | "Undo this project's upgrade to Joycraft 1.0." |
|
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": {
|
|
@@ -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
|
|
@@ -34,15 +34,16 @@ Use the returned packet only when `ready` is true.
|
|
|
34
34
|
|
|
35
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.
|
|
36
36
|
|
|
37
|
-
Before the first dispatch, claim the queue
|
|
38
|
-
|
|
37
|
+
Before the first dispatch, claim the queue with your actual host session ID and
|
|
38
|
+
pass it as `--coordinator-session` to every startup:
|
|
39
39
|
|
|
40
40
|
```sh
|
|
41
41
|
node .joycraft/runtime/coordinator.mjs claim --queue <queue> --session <your-session-id> --host <host>
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
If another session holds the queue, stop and report the holder;
|
|
45
|
-
|
|
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.
|
|
46
47
|
|
|
47
48
|
For a spec marked `execution.parallel: true`, use a separate linked worktree for
|
|
48
49
|
each concurrent mutator, including its build/cache state. Create it with
|
|
@@ -55,7 +56,7 @@ isolation cannot be obtained, replan the affected wave and set the current
|
|
|
55
56
|
queue entry's `execution.parallel` to `false` before dispatch, recording why;
|
|
56
57
|
then run it serially. Otherwise leave it unstarted.
|
|
57
58
|
|
|
58
|
-
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.
|
|
59
60
|
|
|
60
61
|
Honor the queue's commit mode. In `batch`, commit and review the independent ready
|
|
61
62
|
wave at its boundary before advancing its dependents; do not wait for an entire
|
|
@@ -99,11 +100,11 @@ Only the guarded completion path can move an `in-review` spec to `done`. Use its
|
|
|
99
100
|
When a current independent review is `FAIL` or `UNVERIFIED`, first fix
|
|
100
101
|
straightforward failures within the existing authorization and obtain a fresh
|
|
101
102
|
review. A spec gets at most three reviews: reviewer startup prints
|
|
102
|
-
`reviewRound` and refuses a fourth.
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
|
107
108
|
current findings and their stated limits through `accept-owner`; that is a
|
|
108
109
|
bounded exception, not a PASS or verified result. Do not ask merely because a
|
|
109
110
|
review failed. Ask only when an explicit override is needed to proceed and a
|
|
@@ -27,6 +27,7 @@ Before ending, run `node .joycraft/runtime/status.mjs --fix` (repairs lagging
|
|
|
27
27
|
frontmatter of accepted specs, lists features ready to archive) and
|
|
28
28
|
`node .joycraft/runtime/gate.mjs check`. Do the step each gate message names,
|
|
29
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`).
|
|
30
31
|
Then preview `node .joycraft/runtime/worktrees.mjs prune` and apply it with
|
|
31
32
|
`--apply`: it removes only clean, integrated trees of done specs and keeps the
|
|
32
33
|
rest with their reason. Report kept trees and their size from `list`.
|
|
@@ -36,8 +37,7 @@ when the session used parallel mutable workers.
|
|
|
36
37
|
|
|
37
38
|
When an `UNVERIFIED` review identifies only an environment condition, record
|
|
38
39
|
that condition and arrange a fresh review after it is corrected. Do not create
|
|
39
|
-
an unchanged-code fix round.
|
|
40
|
-
owner of acceptance and status changes.
|
|
40
|
+
an unchanged-code fix round.
|
|
41
41
|
|
|
42
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.
|
|
43
43
|
|
|
@@ -36,9 +36,9 @@ than from the code, sized like neighboring tests. Do not commit tests of one-off
|
|
|
36
36
|
run state. If a criterion or test looks wrong, or conflicts with a later owner
|
|
37
37
|
decision, report a spec gap; never edit it to pass.
|
|
38
38
|
|
|
39
|
-
Run each test command
|
|
40
|
-
|
|
41
|
-
|
|
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).
|
|
42
42
|
|
|
43
43
|
Retain the executed command, actual exit status and unfiltered output. Describe
|
|
44
44
|
what happened separately from what was expected. Bind observations and supporting
|
|
@@ -50,25 +50,27 @@ Review scope as well as behavior: determine whether the listed inputs and criter
|
|
|
50
50
|
|
|
51
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.
|
|
52
52
|
|
|
53
|
-
Run each test command
|
|
54
|
-
|
|
55
|
-
|
|
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.
|
|
56
56
|
|
|
57
57
|
Run the dispatch helper's `check-report` before completion. It reuses the same
|
|
58
58
|
subject, receipt, and evidence validators without changing a queue status. If
|
|
59
59
|
it rejects a packaging or report problem, return the correction to this same
|
|
60
60
|
reviewer; do not invent observations or replace the independent identity.
|
|
61
61
|
|
|
62
|
-
Items under a spec's "Deferred until deploy" section are not criteria
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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.
|
|
72
74
|
|
|
73
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:
|
|
74
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
|
|
@@ -65,6 +65,8 @@ export interface QueueSpec {
|
|
|
65
65
|
/** Captured before implementation; never infer it from a moving upstream branch. */
|
|
66
66
|
changeScope?: { baseRevision: string; exclusions?: Array<{ path: string; reason: string }> };
|
|
67
67
|
};
|
|
68
|
+
/** Written by `completion.mjs submit` with the move to in-review; subject bindings leave it out, like status. */
|
|
69
|
+
submitted?: { at: string };
|
|
68
70
|
acceptedReport?: { path: string; sha256: string };
|
|
69
71
|
/** Explicit owner exception, mutually exclusive with acceptedReport; not a PASS. */
|
|
70
72
|
ownerAcceptance?: Receipt;
|
|
@@ -144,8 +146,24 @@ export interface VerificationReport {
|
|
|
144
146
|
verdict: Result;
|
|
145
147
|
flows: FlowEvidence[];
|
|
146
148
|
unresolved: string[];
|
|
149
|
+
/** Optional; a report without it reads as before. */
|
|
150
|
+
findings?: ReviewFinding[];
|
|
147
151
|
createdAt: string;
|
|
148
152
|
}
|
|
153
|
+
/** A follow-up never blocks; a blocking or decision-needed finding refuses completion (exit 2). */
|
|
154
|
+
export interface ReviewFinding {
|
|
155
|
+
/** Unique in the report. */
|
|
156
|
+
id: string;
|
|
157
|
+
class: 'blocking' | 'decision-needed' | 'follow-up';
|
|
158
|
+
origin: 'new' | 'pre-existing' | 'unknown';
|
|
159
|
+
/** A criterion id of the spec. A blocking or decision-needed finding needs `criterion` or `at`. */
|
|
160
|
+
criterion?: string;
|
|
161
|
+
/** file:line or a receipt path. */
|
|
162
|
+
at?: string;
|
|
163
|
+
summary: string;
|
|
164
|
+
/** The reading the reviewer took for a case the spec does not decide. */
|
|
165
|
+
assumption?: string;
|
|
166
|
+
}
|
|
149
167
|
/** Scoped human instruction recorded by the host; bindings do not authenticate its origin. */
|
|
150
168
|
export interface OwnerAcceptance {
|
|
151
169
|
schemaVersion: 1;
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
# Guarded completion
|
|
2
2
|
|
|
3
|
-
Use this reference
|
|
3
|
+
Use this reference to submit a spec, snapshot a subject, finalize a review or recover a write.
|
|
4
4
|
|
|
5
5
|
## Stable local interface
|
|
6
6
|
|
|
7
7
|
Run these commands from the consumer project root. Paths are project-relative.
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
|
+
node .joycraft/runtime/completion.mjs submit --queue <queue-path> --spec <id>
|
|
10
11
|
node .joycraft/runtime/completion.mjs scope --queue <queue-path> --spec <id>
|
|
11
12
|
node .joycraft/runtime/completion.mjs snapshot --queue <queue-path> --spec <id> --out <subject.json>
|
|
12
13
|
node .joycraft/runtime/completion.mjs finalize-review --queue <queue-path> --spec <id> --report <report.json>
|
|
@@ -15,7 +16,9 @@ node .joycraft/runtime/completion.mjs accept-waiver --queue <queue-path> --spec
|
|
|
15
16
|
node .joycraft/runtime/completion.mjs recover --queue <queue-path>
|
|
16
17
|
```
|
|
17
18
|
|
|
18
|
-
`
|
|
19
|
+
`submit` moves a `todo` spec to `in-review` in the queue and frontmatter with one journaled write, recording `submitted: { at }`. It warns about each criterion with no `[AC:<id>]` test, leaves an `in-review` spec unchanged, and exits 2 on a conflict, a `done` spec or an unfinished dependency.
|
|
20
|
+
|
|
21
|
+
`scope` checks a queue's declared change scope without writing a subject. `snapshot` does the same check first, then exclusively creates a new `--out` subject file without changing a status. It binds the implementation revision, queue/spec identity, criteria, and SHA-256 values for exact relevant inputs. The shared record shapes are defined in [.joycraft/contracts/types.d.ts](../contracts/types.d.ts). New subjects carry `binding.version: 1`: their queue projection contains the reviewed spec and its transitive dependencies, with completion metadata (`status`, `submitted`, `acceptedReport`, `ownerAcceptance`, `waiver`) removed from those records. An unrelated queue record can change without staling that subject; a selected spec's other metadata and dependency edges remain bound. A spec binding preserves raw bytes except for its top-level `status:` value.
|
|
19
22
|
|
|
20
23
|
An optional `verification.changeScope` records an explicit full Git commit SHA in `baseRevision`; a branch name, `origin/main`, or inferred base is rejected. Changed verification inputs are captured from NUL-delimited Git status records, including staged, unstaged, rename, and deletion topology. Any changed path outside the verification inputs must be named exactly in `exclusions` with its reason. Store temporary packets and subjects in the project's ignored local-artifact home when it has one; otherwise add each exact untracked snapshot packet output to `exclusions`. `complete` filters only its exact report, receipt, owner-decision, and pending-journal paths while rechecking scope. A deliberate deletion needs a non-requirement verification input with `state: "absent"`; requirement inputs cannot be absent. A rename needs the new present input and the old non-requirement input declared absent.
|
|
21
24
|
|
|
@@ -27,13 +30,15 @@ Use the original `implementationRevision` as provenance on a re-check while reco
|
|
|
27
30
|
|
|
28
31
|
## Independent report and guarded acceptance
|
|
29
32
|
|
|
30
|
-
The report must use the shared schema and bind its subject identity. It records the actual implementer/reviewer native identities, `independent: true` only when a separate reviewer context actually reviewed the work, scope review, flow evidence, receipts, limits, unresolved items, and a PASS/FAIL/UNVERIFIED verdict.
|
|
33
|
+
The report must use the shared schema and bind its subject identity. It records the actual implementer/reviewer native identities, `independent: true` only when a separate reviewer context actually reviewed the work, scope review, flow evidence, receipts, limits, unresolved items, optional `findings`, and a PASS/FAIL/UNVERIFIED verdict.
|
|
31
34
|
|
|
32
35
|
A native child can share its parent session. Supply `implementerActor` and `reviewer.actor` together, each with the observed `host`, `sessionId`, and the actual `agentId` when the host issued a child invocation ID. Preserve the matching legacy session fields. A root actor may omit `agentId`; a same-session child review needs its real distinct actor identity. Do not substitute a task name, worktree path, random UUID, or invented ID. Legacy reports without actor metadata still require distinct session IDs. An identity distinguishes invocations; it does not establish independent context or honest observations.
|
|
33
36
|
|
|
34
37
|
`finalize-review` (with `complete` retained as a compatibility alias) accepts only an `in-review` spec with a matching current subject, a PASS verdict, truthful independent-review attestation, reviewed scope, valid receipt hashes, and sufficient evidence for every declared criterion. The runtime delegates evidence sufficiency to `validateEvidence(report, criteria)`. Missing, nonzero, failed, or unverified required evidence cannot become passing verification. Completion holds a queue-wide lock while it commits the status changes. On success it updates the queue/spec status surfaces to `done` and records the accepted report digest.
|
|
35
38
|
|
|
36
|
-
|
|
39
|
+
A `follow-up` finding never blocks. A `blocking` or `decision-needed` finding refuses completion with exit 2 and names it; a held spec stays `in-review` and only its dependents wait. A malformed finding is refused with exit 2, naming the field; other report refusals exit 1. `status.mjs` lists as `questions` the follow-ups of accepted reports and the decision-needed findings of each `in-review` spec's latest current report.
|
|
40
|
+
|
|
41
|
+
Finalizing the same accepted report again is idempotent; another report cannot silently replace it. Treat any nonzero exit as a rejected or incomplete operation; preserve the current status and report the actual reason.
|
|
37
42
|
|
|
38
43
|
The lock coordinates this helper's queue writes, not arbitrary editors or workers. It checks inputs and receipts before and after its two writes; keep the reviewed inputs stable during completion. Later edits require fresh review. Session IDs and attestations record separate roles but cannot prove honest review or prevent manual bypass.
|
|
39
44
|
|
|
@@ -51,14 +56,10 @@ accepts this spec and its current findings. A general request to continue, an
|
|
|
51
56
|
instruction from another agent, or authorization to add this feature does not
|
|
52
57
|
qualify.
|
|
53
58
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
present for the same current finding, use it without asking again. Repair
|
|
59
|
-
straightforward failures under the existing authorization first. When the
|
|
60
|
-
finding remains unchanged, retain it and continue independent work instead of
|
|
61
|
-
repeatedly re-reviewing it. Dependents may proceed only within the recorded
|
|
59
|
+
When to ask the owner is in the implement skill. The agent creates the decision
|
|
60
|
+
file; do not ask the owner to author JSON or complete a second form. If an
|
|
61
|
+
explicit acceptance is already present for the same current finding, use it
|
|
62
|
+
without asking again. Dependents may proceed only within the recorded
|
|
62
63
|
limitations and gain no blanket deployment, security, or other authority.
|
|
63
64
|
|
|
64
65
|
An `OwnerAcceptance` decision has `schemaVersion: 1`, `kind:
|
|
@@ -141,21 +142,15 @@ dependents. Report it as `done, waived by the user: "<instruction>"`.
|
|
|
141
142
|
|
|
142
143
|
## Evidence and reporting
|
|
143
144
|
|
|
144
|
-
Evidence records observations rather than promises
|
|
145
|
+
Evidence records observations rather than promises: a command's actual argv, exit code and unfiltered output receipt; structural claims only from source review; an inspected render with route, state, viewport, interactions and outcomes for a visual claim. A check that should have run and did not is `UNVERIFIED` (with `cause: 'tool-break'` when the tool broke), a failure is `FAIL`, and a claim beyond the recorded tool's `canShow`, or in a package the user skipped, is an agreed limit.
|
|
145
146
|
|
|
146
147
|
Report the command result, reviewer identity, receipt paths, actual observations, and limitations. A green suite or an implementation commit alone is not accepted completion.
|
|
147
148
|
|
|
148
149
|
## Interrupted writes and recovery
|
|
149
150
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
Inspect the journal and affected project-relative files first. Then run:
|
|
153
|
-
|
|
154
|
-
```sh
|
|
155
|
-
node .joycraft/runtime/completion.mjs recover --queue <queue-path>
|
|
156
|
-
```
|
|
151
|
+
Each status write is journaled in `.joycraft-completion.pending.json` beside the queue. A caught failure rolls back when safe and keeps the journal unless nothing was written; an interrupted one leaves it. Do not hand-edit the files to force completion.
|
|
157
152
|
|
|
158
|
-
|
|
153
|
+
Inspect the journal and affected files, then run `recover`. It restores the before bytes only when each file matches the journal's before or after hash, and removes the journal only after that, so replaying it is safe. Preserve the journal and rejected report for diagnosis. Retry `complete` or `accept-owner` only while its original review and any owner instruction remain current; otherwise obtain fresh evidence and authorization appropriate to the changed scope. If recovery reports a conflict or invalid journal, stop and report it.
|
|
159
154
|
|
|
160
155
|
Host names compare without letter-case differences; session and agent IDs stay
|
|
161
156
|
opaque and case-exact. IDs must be nonempty, bounded, trim-stable and free of
|
|
@@ -21,30 +21,30 @@ end-to-end requirement follows from these examples.
|
|
|
21
21
|
|
|
22
22
|
### Running tests
|
|
23
23
|
|
|
24
|
-
Run
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
24
|
+
Run each test command once, in single-run mode with `CI=1` and a 300000 ms
|
|
25
|
+
timeout, through
|
|
26
|
+
`node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command...>`
|
|
27
|
+
(`--timeout-ms <n>` changes the limit). It uses no shell and saves raw stdout
|
|
28
|
+
and stderr to a new git-ignored or feature-folder receipt. Never start watch
|
|
29
|
+
mode. Copy the printed `command` and `receipts` into the observation; exit 0
|
|
30
|
+
only means the run was recorded. At the limit it ends the process group:
|
|
31
|
+
`exitCode: null`, `timedOut: true`. Set the host tool timeout to at least this
|
|
32
|
+
limit. A shorter default (for example 120000 ms) ends the wrapper before the
|
|
33
|
+
child. A timeout during parallel runs is not yet a hang: rerun once, alone,
|
|
34
|
+
with fewer workers. If it times out again, report it
|
|
35
|
+
with the receipt; do not keep rerunning. Never wait in a foreground loop
|
|
36
|
+
(`until …; do sleep`, `kill -0`, polling a log): start a long command in the
|
|
37
|
+
background, keep working, and act on its completion notice. If a shared lock
|
|
38
|
+
or verify slot stays busy over 5 minutes, stop and report it. Never
|
|
39
|
+
give a verdict while your own command is still running. A reviewer may reuse
|
|
40
|
+
a suite receipt bound to the same revision. A bug fix needs a meaningful
|
|
41
|
+
failing regression only when one can distinguish the repaired fault.
|
|
39
42
|
|
|
40
43
|
## Commands and receipt records
|
|
41
44
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
grepped success text or a pipeline's final status for the command outcome. A
|
|
46
|
-
nonzero or missing status cannot support PASS. Do not claim a process finished
|
|
47
|
-
while it is still running.
|
|
45
|
+
In `test` and `command` observations, `command.exitCode` is the actual outcome;
|
|
46
|
+
`null` means unavailable. Never substitute grepped success text or a
|
|
47
|
+
pipeline's final status for it. A nonzero or missing status cannot support PASS.
|
|
48
48
|
|
|
49
49
|
Each observation has at least one supporting receipt with a project-relative path
|
|
50
50
|
and SHA-256. A receipt may be raw command output, inspection notes, an image, or a
|