joycraft 1.1.2 → 1.2.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 +15 -10
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +5 -1
- package/payload/.agents/skills/joycraft-entry/SKILL.md +28 -7
- package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -0
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +1 -1
- package/payload/.agents/skills/joycraft-testing/SKILL.md +7 -5
- package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +4 -3
- package/payload/.agents/skills/joycraft-verify/SKILL.md +1 -1
- package/payload/.claude/agents/joycraft-reviewer.md +7 -2
- package/payload/.joycraft/assets/artifacts/kit.css +7 -0
- package/payload/.joycraft/assets/artifacts/kit.js +23 -7
- package/payload/.joycraft/contracts/types.d.ts +22 -0
- package/payload/.joycraft/references/archive.md +4 -2
- package/payload/.joycraft/references/artifacts.md +66 -9
- package/payload/.joycraft/references/completion.md +55 -2
- package/payload/.joycraft/references/dispatch.md +12 -0
- package/payload/.joycraft/references/setup.md +70 -30
- package/payload/.joycraft/references/testing.md +14 -7
- package/payload/.joycraft/references/update.md +8 -0
- package/payload/.joycraft/references/workflow.md +10 -5
- package/payload/.joycraft/runtime/archive.mjs +19 -4
- package/payload/.joycraft/runtime/artifacts/cli.mjs +29 -5
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +13 -5
- package/payload/.joycraft/runtime/artifacts/model.mjs +1 -1
- package/payload/.joycraft/runtime/artifacts/preferences.mjs +95 -2
- package/payload/.joycraft/runtime/completion.mjs +210 -10
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +16 -3
- package/payload/.joycraft/runtime/evidence.mjs +4 -0
- package/payload/.joycraft/runtime/identity.mjs +11 -0
- package/payload/.joycraft/runtime/review-tools.json +110 -30
- package/payload/.joycraft/runtime/review-tools.mjs +658 -129
- package/payload/.joycraft/runtime/status.mjs +1 -1
- package/payload/.joycraft/runtime/worktrees.mjs +1 -1
- package/payload/.joycraft/templates/brief.md +1 -1
- package/payload/PIN +35 -35
package/README.md
CHANGED
|
@@ -165,20 +165,24 @@ the agent says what it does not cover and installs nothing without your yes.
|
|
|
165
165
|
|
|
166
166
|
## Answering questions: the decision page
|
|
167
167
|
|
|
168
|
-
When the agent needs you to choose between options, it
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
brief changes while the page is open, the page names the questions that changed and
|
|
173
|
-
keeps your other answers. The answers go into the brief, so the agent does not ask
|
|
174
|
-
again.
|
|
175
|
-
|
|
176
|
-
Sometimes the agent forgets and lists the options in chat. Then say:
|
|
168
|
+
When the agent needs you to choose between options, it asks in your question
|
|
169
|
+
style. Setup asks for it once: one decision at a time with a short talk about each
|
|
170
|
+
answer, or a page of decisions; on a decision page or as numbered prose in chat.
|
|
171
|
+
To change it for one feature, say:
|
|
177
172
|
|
|
178
173
|
```text
|
|
179
|
-
|
|
174
|
+
Ask me one question at a time, in chat, for this feature.
|
|
180
175
|
```
|
|
181
176
|
|
|
177
|
+
A consequential question gives the context, the question, two to four options each
|
|
178
|
+
with an example and a trade-off, and the agent's recommendation with its reason. On
|
|
179
|
+
the decision page, you pick an answer, or "Something else" and say what you want,
|
|
180
|
+
add a note if you want, and save. You can add or change a note after saving. If the
|
|
181
|
+
brief changes while the page is open, the page names the questions that changed and
|
|
182
|
+
keeps your other answers. In chat or on the page, the answers go into the brief, so
|
|
183
|
+
the agent does not ask again. If a question is not clear, say "wait, what?" and the
|
|
184
|
+
agent explains it again with more context.
|
|
185
|
+
|
|
182
186
|
**Colors.** The page uses a light or dark theme. To match your project, ask:
|
|
183
187
|
|
|
184
188
|
```text
|
|
@@ -263,6 +267,7 @@ should forget:
|
|
|
263
267
|
- **Lauren** (Cursor): prefer fixes in this order: architecture, then lint and CI, then skills and rules, then asking a human.
|
|
264
268
|
- **Robert C. Martin**: impose values, not disciplines.
|
|
265
269
|
- **aka-luan** ([doc-cleanup](https://github.com/aka-luan/doc-cleanup), MIT), brought to Joycraft by **David Moshal**: Joycraft's doc audit follows its method. Treat every doc claim as a hypothesis and the code as the evidence.
|
|
270
|
+
- **David Moshal**, with his `questions-dm` skill: ask one question at a time, give the context first, and never assume the user remembers what the agent remembers. **Matt Pocock** ([`wait-what`](https://github.com/mattpocock/skills/tree/main/skills/productivity/wait-what), MIT): when a message does not land, say it again in plain words with the missing context.
|
|
266
271
|
|
|
267
272
|
The levels this project aims at are Dan Shapiro's. See [The levels](docs/guides/levels.md).
|
|
268
273
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "joycraft",
|
|
3
|
-
"version": "1.1
|
|
3
|
+
"version": "1.2.1",
|
|
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.1
|
|
17
|
-
"summary": "
|
|
16
|
+
"release": "1.2.1",
|
|
17
|
+
"summary": "Joycraft asks questions your way: one at a time or as a page, in chat or on the decision page, set at setup and changeable per feature; each question gives context, options with an example and a trade-off, and a recommendation.",
|
|
18
18
|
"autoSafeEligible": false
|
|
19
19
|
},
|
|
20
20
|
"scripts": {
|
|
@@ -18,7 +18,11 @@ decision status or ask for approval again when the session already supplies it.
|
|
|
18
18
|
Use `.joycraft/templates/spec.md` and `queue.json` as small starting
|
|
19
19
|
points. Keep each spec independently testable and put requirement text in stable
|
|
20
20
|
brief/spec anchors. Each queued criterion points to its source and declares the
|
|
21
|
-
needed runtime, visual or structural evidence.
|
|
21
|
+
needed runtime, visual or structural evidence. Write each criterion so the
|
|
22
|
+
package's recorded review tools (the `Review loop` section of `AGENTS.md`) can
|
|
23
|
+
check it within their `canShow`. A main claim those tools cannot show at all
|
|
24
|
+
goes back to the brief as a tooling-change question, asked once in the
|
|
25
|
+
interview and recorded; it does not enter the queue. A check that only a deployed
|
|
22
26
|
environment can show is not a criterion; list it under the spec's "Deferred until
|
|
23
27
|
deploy" section instead. Include the brief, spec and exact
|
|
24
28
|
relevant code, test/configuration and fixture paths as verification inputs. Plan
|
|
@@ -70,13 +70,34 @@ Settle each goal's "Done when" with the user while writing the brief; if it
|
|
|
70
70
|
cannot be filled yet, record it as an open decision so dependent specs wait for
|
|
71
71
|
the answer instead of a reviewer discovering it.
|
|
72
72
|
|
|
73
|
-
**
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
73
|
+
**Review defaults stay strict.** Every feature starts with the review loop on
|
|
74
|
+
and its tools required. Record a waiver only from the user's own words in that
|
|
75
|
+
feature's interview: put them in the note of a settled brief decision and write
|
|
76
|
+
the feature's `waiver.json` naming that decision, before any review runs
|
|
77
|
+
(`.joycraft/references/completion.md`). A `no-review` waiver blocks reviewer
|
|
78
|
+
dispatch for the feature. Never propose or ask about one, and never carry it
|
|
79
|
+
into the next feature.
|
|
80
|
+
|
|
81
|
+
**Feature sessions stay quiet about the review loop.** A feature interview
|
|
82
|
+
asks nothing about review tools: read the recorded `## Review loop` and write
|
|
83
|
+
criteria its tools can check. Ask once, before any spec, only when the
|
|
84
|
+
feature's main claim needs something the recorded tools cannot show (a drag on a
|
|
85
|
+
screenshots-only tool). That is a tooling change: follow
|
|
86
|
+
[change a tool](../../../.joycraft/references/setup.md#review-loop-tools) and
|
|
87
|
+
record the answer, so it is not asked again.
|
|
88
|
+
|
|
89
|
+
**Ask in the user's question style.** When the user must choose between
|
|
90
|
+
options, record each choice as a brief decision. Then run
|
|
91
|
+
`node .joycraft/runtime/artifacts/cli.mjs questions --brief <brief>` and ask as
|
|
92
|
+
it says: one decision at a time with a short discussion after each answer, or a
|
|
93
|
+
page of decisions; in the decision artifact or as numbered prose in chat. Give
|
|
94
|
+
each consequential question its context, options with an example and a
|
|
95
|
+
trade-off, and your recommendation with the reason, in Simplified Technical
|
|
96
|
+
English. Never assume the user remembers what you remember. Save every answer
|
|
97
|
+
to the brief. Follow
|
|
98
|
+
[asking questions](../../../.joycraft/references/artifacts.md#asking-questions).
|
|
99
|
+
Plain chat with no decision is only for one quick yes/no or an open question
|
|
100
|
+
with no options.
|
|
80
101
|
|
|
81
102
|
**Use the project's folders.** If `joycraft.yaml` exists, run
|
|
82
103
|
`node .joycraft/runtime/config.mjs` and use its `paths` wherever Joycraft guidance
|
|
@@ -81,6 +81,22 @@ If it returns unenforced, or a separate review context/capability is unavailable
|
|
|
81
81
|
leave the spec `in-review`; do not invent an ID or prompt to continue. This holds
|
|
82
82
|
the claimed review, not unrelated authorized or hooks-disabled/manual work.
|
|
83
83
|
|
|
84
|
+
When a recorded tool breaks during a run (the dev server does not start, a
|
|
85
|
+
port is taken, the browser or simulator crashes), repair it with what the user
|
|
86
|
+
already agreed to: restart the dev server, free the port, relaunch the browser
|
|
87
|
+
or simulator, then retry once. A repair never installs, upgrades or
|
|
88
|
+
reconfigures anything; that needs the user's yes. If the repair fails, record an
|
|
89
|
+
`UNVERIFIED` observation with `cause: 'tool-break'` and the reason, leave that
|
|
90
|
+
spec `in-review`, and continue with the specs that do not depend on it. At the
|
|
91
|
+
first hold, tell the user in the conversation while workers run: the spec, the
|
|
92
|
+
tool, the cause and the repair tried. The session-end summary lists every held
|
|
93
|
+
spec again.
|
|
94
|
+
|
|
95
|
+
A tool break stops the whole queue only when the project will not build or
|
|
96
|
+
install, the worktree or repository is broken, or the next step would touch data
|
|
97
|
+
or systems outside the project (a shared database, a deploy). Every other tool
|
|
98
|
+
break is repair, then hold.
|
|
99
|
+
|
|
84
100
|
Only the guarded completion path can move an `in-review` spec to `done`. Use its manual snapshot/complete commands only at an explicit non-native boundary; read [completion guidance](../../../.joycraft/references/completion.md) before doing so.
|
|
85
101
|
|
|
86
102
|
When a current independent review is `FAIL` or `UNVERIFIED`, first fix
|
|
@@ -23,7 +23,7 @@ force local state to a remote tip. Start a replacement only from the durable
|
|
|
23
23
|
run journal and a newly printed dispatch plan. This guidance describes the
|
|
24
24
|
project/native runtime boundary; it does not enforce lifecycle behavior.
|
|
25
25
|
|
|
26
|
-
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.
|
|
26
|
+
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
27
|
|
|
28
28
|
If a completion operation failed or was interrupted, do not declare success or hand-edit statuses. Retain the helper's error and journal/recovery information, then use the bounded local recovery process in [completion guidance](../../../.joycraft/references/completion.md). It only restores the two status surfaces and accepted-report receipt captured by the journal; it does not retry unrelated work.
|
|
29
29
|
|
|
@@ -25,11 +25,13 @@ remain valid; only assertions intended to detect the new behavior need meaningfu
|
|
|
25
25
|
red/green. If a red check was not run, say so. Do not weaken assertions to obtain
|
|
26
26
|
green or alter unrelated tests to manufacture universal failure.
|
|
27
27
|
|
|
28
|
-
For UI requirements, use the
|
|
29
|
-
`
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
28
|
+
For UI requirements, use the package's recorded tool and commands from the
|
|
29
|
+
worker packet's `reviewLoop` (the `Review loop` section of `AGENTS.md`, plus
|
|
30
|
+
`local` host tools), within its `canShow`. A claim beyond `canShow`, or in a
|
|
31
|
+
package the user skipped, is an agreed limit, not UNVERIFIED: check what the
|
|
32
|
+
tool can show and say how you checked. Render and inspect the relevant route,
|
|
33
|
+
state and viewport. When the tool can interact, perform the interactions the
|
|
34
|
+
claim needs and observe their outcomes. Fix observed
|
|
33
35
|
problems within scope, then rerender and reinspect affected states. A saved
|
|
34
36
|
screenshot, DOM check or browser launch alone is not visual inspection. Preserve
|
|
35
37
|
tool access boundaries: if a check is blocked or unavailable, record UNVERIFIED
|
|
@@ -19,9 +19,10 @@ current render cannot answer them. Otherwise build or modify the smallest runnab
|
|
|
19
19
|
slice in the project's actual stack. Show the consequential state and a useful
|
|
20
20
|
interaction when interaction matters. One viewport is a useful starting size, not
|
|
21
21
|
a rule for all products. Put explanatory detail behind disclosure. The slice is
|
|
22
|
-
exploration, not production approval. Render and inspect it early with
|
|
23
|
-
|
|
24
|
-
|
|
22
|
+
exploration, not production approval. Render and inspect it early with the
|
|
23
|
+
package's recorded review tool (`Review loop` in `AGENTS.md`) or the host's
|
|
24
|
+
permitted tools; record the route, state, viewport, interactions the tool can
|
|
25
|
+
perform and observed outcomes. If blocked, record UNVERIFIED and the reason; respect denials without
|
|
25
26
|
alternate access routes.
|
|
26
27
|
|
|
27
28
|
The optional local helper below needs the installed shared runtime. If it is
|
|
@@ -51,7 +51,7 @@ weakened assertions that could hide the requested behavior.
|
|
|
51
51
|
|
|
52
52
|
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
53
|
|
|
54
|
-
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
|
|
54
|
+
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
55
|
|
|
56
56
|
Run each test command once in single-run mode with `CI=1` and a 300000 ms
|
|
57
57
|
timeout; follow [running tests](../../../.joycraft/references/testing.md#running-tests)
|
|
@@ -34,6 +34,11 @@ criterion by what you observe.
|
|
|
34
34
|
Report every finding with a severity and the criterion it touches. Only a failing
|
|
35
35
|
stated criterion, or a reproducible defect or regression in the changed code with
|
|
36
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.
|
|
38
|
-
|
|
37
|
+
needed", not FAIL. Do not repeat an earlier round's finding as new.
|
|
38
|
+
|
|
39
|
+
Take evidence with each package's recorded tool from the packet's `reviewLoop`,
|
|
40
|
+
within its `canShow`, and say in plain words how you checked. A limit the user
|
|
41
|
+
agreed to (a claim beyond `canShow`, or a package the user skipped) is not
|
|
42
|
+
UNVERIFIED; the parent agent judges what is left. UNVERIFIED is a check that
|
|
43
|
+
should have run and did not. Record only what you observed. Keep the final message
|
|
39
44
|
short: verdict, blocking findings, decision-needed items, report path.
|
|
@@ -89,6 +89,13 @@ html[data-jca-theme] body { margin: 0; background: var(--canvas); color: var(--i
|
|
|
89
89
|
.jca-option input { margin-top: .28rem; accent-color: var(--accent); }
|
|
90
90
|
.jca-option strong, .jca-option small { display: block; }
|
|
91
91
|
.jca-option small { margin-top: .1rem; color: var(--muted); }
|
|
92
|
+
.jca-option .jca-option-line { margin-top: .3rem; }
|
|
93
|
+
.jca-option-line b, .jca-recommendation b { color: var(--ink); font-weight: 650; }
|
|
94
|
+
.jca-badge { display: inline-block; margin-left: .5rem; padding: .05rem .45rem; border-radius: 999px; background: var(--accent); color: var(--accent-text); font-size: .7rem; font-weight: 700; letter-spacing: .04em; vertical-align: .1em; }
|
|
95
|
+
.jca-option-recommended { border-color: var(--accent); }
|
|
96
|
+
.jca-context { margin: .8rem 0 0; }
|
|
97
|
+
.jca-context p { margin: .55rem 0; }
|
|
98
|
+
.jca-recommendation { margin: 0 0 1rem; padding: .7rem .8rem; border-left: 3px solid var(--accent); background: var(--accent-soft); }
|
|
92
99
|
.jca-note-label { display: block; margin-bottom: .35rem; font-size: .88rem; font-weight: 700; }
|
|
93
100
|
.jca-note { display: block; width: 100%; resize: vertical; border: 1px solid var(--control-line); border-radius: 8px; padding: .7rem; color: var(--ink); background: var(--input); font: inherit; }
|
|
94
101
|
.jca-note::placeholder { color: var(--muted); opacity: 1; }
|
|
@@ -46,8 +46,9 @@
|
|
|
46
46
|
return JSON.stringify({
|
|
47
47
|
question: question.question || '',
|
|
48
48
|
options: (question.options || []).map(function (option) {
|
|
49
|
-
return { value: option.value, label: option.label || '', description: option.description || '', requiresNote: Boolean(option.requiresNote) };
|
|
49
|
+
return { value: option.value, label: option.label || '', description: option.description || '', example: option.example || '', tradeoff: option.tradeoff || '', recommended: Boolean(option.recommended), requiresNote: Boolean(option.requiresNote) };
|
|
50
50
|
}),
|
|
51
|
+
recommendation: question.recommendation || '',
|
|
51
52
|
status: question.status || '',
|
|
52
53
|
answer: question.answer == null ? null : question.answer,
|
|
53
54
|
note: question.note == null ? '' : question.note
|
|
@@ -336,23 +337,38 @@
|
|
|
336
337
|
body.append(node('p', { class: 'jca-status jca-status-' + (question.status || 'open'), text: statusLabel(question.status) }));
|
|
337
338
|
if (question.answer) body.append(node('p', { class: 'jca-recorded', text: 'Brief record: ' + question.answer }));
|
|
338
339
|
(model.comparisons || []).filter(function (comparison) { return comparison.decisionId === question.id; }).forEach(function (comparison) { body.append(renderComparison(comparison)); });
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
340
|
+
// Context comes before the choice, never behind a click: a person should not have to remember it.
|
|
341
|
+
if (question.context || question.why) {
|
|
342
|
+
body.append(node('div', { class: 'jca-context' }, [
|
|
343
|
+
question.context ? node('p', { text: question.context }) : null,
|
|
344
|
+
question.why ? node('p', { text: question.why }) : null
|
|
345
|
+
]));
|
|
346
|
+
}
|
|
347
|
+
if (question.details || (question.affected || []).length) {
|
|
348
|
+
var detail = node('details', { class: 'jca-details' }, [node('summary', { text: 'More detail' })]);
|
|
349
|
+
if (question.details) detail.append(node('p', { text: question.details }));
|
|
343
350
|
if ((question.affected || []).length) detail.append(node('p', { text: 'Affected: ' + question.affected.join(', ') }));
|
|
344
351
|
body.append(detail);
|
|
345
352
|
}
|
|
346
353
|
var fieldset = node('fieldset', { class: 'jca-options', disabled: readOnly });
|
|
347
354
|
fieldset.append(node('legend', { text: readOnly ? 'Responses are read-only' : 'Choose one response' }));
|
|
348
|
-
|
|
355
|
+
// The recommended option leads; "Something else" always closes the list.
|
|
356
|
+
var rank = function (option) { return option.value === 'custom' ? 2 : option.recommended ? 0 : 1; };
|
|
357
|
+
var ordered = (question.options || []).map(function (option, position) { return { option: option, position: position }; })
|
|
358
|
+
.sort(function (left, right) { return rank(left.option) - rank(right.option) || left.position - right.position; })
|
|
359
|
+
.map(function (item) { return item.option; });
|
|
360
|
+
var optionLine = function (name, value) { return value ? node('small', { class: 'jca-option-line' }, [node('b', { text: name + ': ' }), text(value)]) : null; };
|
|
361
|
+
ordered.forEach(function (option) {
|
|
349
362
|
var id = 'jca-' + question.id + '-' + option.value;
|
|
350
363
|
var radio = node('input', { type: 'radio', id: id, name: 'jca-answer-' + question.id, value: option.value, checked: current.answer === option.value,
|
|
351
364
|
onchange: function () { draft[question.id] = { answer: option.value, note: (draft[question.id] || {}).note || '' }; setMessage('quiet', 'Unsaved changes.'); syncLiveUi(); syncNoteRequirement(); } });
|
|
352
|
-
var
|
|
365
|
+
var title = node('strong', { text: option.label }, [option.recommended ? node('span', { class: 'jca-badge', text: 'Recommended' }) : null]);
|
|
366
|
+
var label = node('label', { class: 'jca-option' + (option.recommended ? ' jca-option-recommended' : ''), for: id }, [radio, node('span', { class: 'jca-option-copy' }, [title, option.description ? node('small', { text: option.description }) : null, optionLine('Example', option.example), optionLine('Trade-off', option.tradeoff)])]);
|
|
353
367
|
fieldset.append(label);
|
|
354
368
|
});
|
|
355
369
|
body.append(fieldset);
|
|
370
|
+
var pick = (question.options || []).find(function (option) { return option.recommended; });
|
|
371
|
+
if (pick && question.recommendation) body.append(node('p', { class: 'jca-recommendation' }, [node('b', { text: 'Recommendation: ' + pick.label + '. ' }), text(question.recommendation)]));
|
|
356
372
|
var note = node('textarea', { class: 'jca-note', id: 'jca-note-' + question.id, rows: 3, disabled: !canEditNote(question), placeholder: 'Optional note' });
|
|
357
373
|
note.value = current.note || '';
|
|
358
374
|
function syncNoteRequirement() {
|
|
@@ -68,6 +68,8 @@ export interface QueueSpec {
|
|
|
68
68
|
acceptedReport?: { path: string; sha256: string };
|
|
69
69
|
/** Explicit owner exception, mutually exclusive with acceptedReport; not a PASS. */
|
|
70
70
|
ownerAcceptance?: Receipt;
|
|
71
|
+
/** The feature's FeatureWaiver file, plus the UNVERIFIED report a tool-break waiver completed on; mutually exclusive with acceptedReport and ownerAcceptance. */
|
|
72
|
+
waiver?: Receipt & { review?: Receipt };
|
|
71
73
|
}
|
|
72
74
|
export interface SpecQueue { schemaVersion: 1; feature: string; specs: QueueSpec[] }
|
|
73
75
|
export interface BoundInput extends VerificationInput {
|
|
@@ -103,6 +105,8 @@ export interface Observation {
|
|
|
103
105
|
result: Result;
|
|
104
106
|
actual: string;
|
|
105
107
|
receipts: Receipt[];
|
|
108
|
+
/** Set only on an UNVERIFIED observation whose recorded tool did not work during the run. */
|
|
109
|
+
cause?: 'tool-break';
|
|
106
110
|
/** Mandatory for test/command observations; null means unavailable. */
|
|
107
111
|
command?: { argv: string[]; exitCode: number | null };
|
|
108
112
|
/** Mandatory for visual observations. Interactions name actual outcomes. */
|
|
@@ -156,6 +160,24 @@ export interface OwnerAcceptance {
|
|
|
156
160
|
limitations: string[];
|
|
157
161
|
createdAt: string;
|
|
158
162
|
}
|
|
163
|
+
/**
|
|
164
|
+
* The user's own words, from one feature's interview, loosening that feature's queue only. Never covers a FAIL.
|
|
165
|
+
* Lives at `<feature folder>/waiver.json`. While it covers no-review, reviewer dispatch for the queue is refused.
|
|
166
|
+
*/
|
|
167
|
+
export interface FeatureWaiver {
|
|
168
|
+
schemaVersion: 1;
|
|
169
|
+
kind: 'feature-waiver';
|
|
170
|
+
queuePath: string;
|
|
171
|
+
/** Nonempty subset: complete without a review report, or with an UNVERIFIED report whose gaps are all tool breaks. */
|
|
172
|
+
covers: Array<'no-review' | 'tool-break'>;
|
|
173
|
+
/** The user's exact words: whole words of the named decision's note or answer, at least three. */
|
|
174
|
+
instruction: string;
|
|
175
|
+
/** Id of the clarified or assigned brief decision whose note holds the instruction. */
|
|
176
|
+
decision: string;
|
|
177
|
+
/** Receipt of the feature brief that holds the decision. */
|
|
178
|
+
source: Receipt;
|
|
179
|
+
createdAt: string;
|
|
180
|
+
}
|
|
159
181
|
export interface ValidationResult { ok: boolean; errors: string[] }
|
|
160
182
|
export type Need = 'repair' | 'feature' | 'context' | 'decision' | 'ui-exploration' | 'implementation' | 'verification' | 'unknown';
|
|
161
183
|
export type NextInteraction = 'continue' | 'inspect' | 'render-slice' | 'ask-focused' | 'verify' | 'abstain';
|
|
@@ -33,8 +33,10 @@ another decision or approval authority.
|
|
|
33
33
|
|
|
34
34
|
The preview validates the complete queue before any write: the canonical queue
|
|
35
35
|
must be the only queue anywhere in the feature tree, all specs must be
|
|
36
|
-
`done`, and each spec must have exactly one of an accepted PASS report
|
|
37
|
-
explicit `ownerAcceptance` receipt
|
|
36
|
+
`done`, and each spec must have exactly one of an accepted PASS report, an
|
|
37
|
+
explicit `ownerAcceptance` receipt, or a feature `waiver` receipt. A waiver
|
|
38
|
+
keeps its record bytes, the user's quoted instruction as its limitation, and
|
|
39
|
+
for a tool-break completion its UNVERIFIED `waiver.review` report and receipts. A normal accepted report must retain its
|
|
38
40
|
PASS evidence. An owner-acceptance record is historical exception metadata:
|
|
39
41
|
it binds the queue/spec/subject identity to a hashed independent review whose
|
|
40
42
|
verdict remains `FAIL` or `UNVERIFIED`, carries nonempty limitations, and is
|
|
@@ -1,11 +1,64 @@
|
|
|
1
1
|
# Decision artifacts
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
for an editorial comparison of existing screenshots or
|
|
6
|
-
|
|
7
|
-
the source of truth. Do not use one for a routine native question,
|
|
8
|
-
slice whose real interaction must be explored, or a long
|
|
3
|
+
Record every choice the user must make between options as a brief decision,
|
|
4
|
+
then ask it in the user's [question style](#asking-questions): on this page or
|
|
5
|
+
in chat. Also use a page for an editorial comparison of existing screenshots or
|
|
6
|
+
a review summary. A page renders a selected view of the brief; the brief and
|
|
7
|
+
queue remain the source of truth. Do not use one for a routine native question,
|
|
8
|
+
a product UI slice whose real interaction must be explored, or a long
|
|
9
|
+
questionnaire.
|
|
10
|
+
|
|
11
|
+
## Asking questions
|
|
12
|
+
|
|
13
|
+
Do not assume the user remembers what you remember. Before you ask, run:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
node .joycraft/runtime/artifacts/cli.mjs questions --brief docs/features/<slug>/brief.md
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
It prints `pacing`, `surface` and where each came from. With `unset: true`, the
|
|
20
|
+
project has no recorded style yet: ask for it as [setup](setup.md) step 2 says,
|
|
21
|
+
then continue.
|
|
22
|
+
|
|
23
|
+
- **Pacing `one-at-a-time`.** Ask one decision. After the answer, tell the user
|
|
24
|
+
what it changes and ask if that is correct, and stop there: do not put the
|
|
25
|
+
next decision in the same message. Ask the next decision after the user
|
|
26
|
+
replies. Ask first the decision that the others depend on.
|
|
27
|
+
- **Pacing `page`.** Show the open decisions together. After the save, say in
|
|
28
|
+
one line per answer what it changes.
|
|
29
|
+
- **Surface `artifact`.** Serve the page for the decisions you ask now (the
|
|
30
|
+
view's `decisionIds`). Discuss the answers in chat.
|
|
31
|
+
- **Surface `chat`.** Write the question as prose with numbered options, in the
|
|
32
|
+
order below. Save each answer to its brief decision with the user's exact
|
|
33
|
+
words as the note. The brief stays the only record of the answer.
|
|
34
|
+
|
|
35
|
+
The user can change the style for one feature ("ask me one at a time here"):
|
|
36
|
+
`questions --brief <brief> --set pacing=one-at-a-time`. That writes a
|
|
37
|
+
`question-style:` line in that brief only. `--clear` removes it. A request to
|
|
38
|
+
change it for every feature is `questions --set ...` without `--brief`.
|
|
39
|
+
|
|
40
|
+
**Order for a consequential choice** (one that changes scope, cost or what is
|
|
41
|
+
built):
|
|
42
|
+
|
|
43
|
+
1. Context: what you are doing, the current state, and why you are blocked.
|
|
44
|
+
2. The question: one sentence, one decision.
|
|
45
|
+
3. Two to four options. Each has a short explanation, a concrete example of the
|
|
46
|
+
result, and the main trade-off.
|
|
47
|
+
4. Your recommendation: the option and the reason.
|
|
48
|
+
|
|
49
|
+
On the page, put these in `context` (and `why`), `question`, each option's
|
|
50
|
+
`description`, `example` and `tradeoff`, and `recommended: true` on one option
|
|
51
|
+
with the reason in `recommendation`. A small choice can be shorter, but still
|
|
52
|
+
give the context the user needs to answer it.
|
|
53
|
+
|
|
54
|
+
**Words.** Write questions in
|
|
55
|
+
[ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/): one
|
|
56
|
+
meaning for each word, active voice, short sentences, one idea in each sentence.
|
|
57
|
+
Use the project's terms from `GLOSSARY.md`, or the glossary that `GLOSSARY-MAP.md`
|
|
58
|
+
names, when the project has one. When the user says a question is not clear
|
|
59
|
+
("wait, what?"), do not repeat it. Write it again with the context that was
|
|
60
|
+
missing. This follows `wait-what` in
|
|
61
|
+
[mattpocock/skills](https://github.com/mattpocock/skills/tree/main/skills/productivity/wait-what).
|
|
9
62
|
|
|
10
63
|
The renderer is deterministic. Agents author a short view-data file, such as
|
|
11
64
|
[`templates/artifact.json`](../templates/artifact.json), and link existing
|
|
@@ -32,9 +85,13 @@ review) is shown where they are working, and you always say its path:
|
|
|
32
85
|
## Decisions and view data
|
|
33
86
|
|
|
34
87
|
A brief decision keeps its existing `id`, `status`, `question`, `answer`,
|
|
35
|
-
`options`, and `affected` fields.
|
|
36
|
-
|
|
37
|
-
|
|
88
|
+
`options`, and `affected` fields. A decision can also have `context` and `why`
|
|
89
|
+
(shown before the options), `details` (under "More detail") and
|
|
90
|
+
`recommendation` (the reason for the recommended option). An option can have
|
|
91
|
+
`description`, `example`, `tradeoff`, `recommended: true` (one option at most;
|
|
92
|
+
not `custom`) and `requiresNote: true` when that option needs a short
|
|
93
|
+
explanation. All of these are optional, and the page lists the recommended
|
|
94
|
+
option first. Every question also offers "Something else" (value `custom`,
|
|
38
95
|
note required), so the person can always answer in their own words; do not
|
|
39
96
|
declare it unless you want different wording. The canonical answer remains an
|
|
40
97
|
option `value`, including `custom`. A saved answer keeps its note box: the
|
|
@@ -11,10 +11,11 @@ node .joycraft/runtime/completion.mjs scope --queue <queue-path> --spec <id>
|
|
|
11
11
|
node .joycraft/runtime/completion.mjs snapshot --queue <queue-path> --spec <id> --out <subject.json>
|
|
12
12
|
node .joycraft/runtime/completion.mjs finalize-review --queue <queue-path> --spec <id> --report <report.json>
|
|
13
13
|
node .joycraft/runtime/completion.mjs accept-owner --queue <queue-path> --spec <id> --decision <owner-acceptance.json>
|
|
14
|
+
node .joycraft/runtime/completion.mjs accept-waiver --queue <queue-path> --spec <id> --waiver <feature-waiver.json> [--report <report.json>]
|
|
14
15
|
node .joycraft/runtime/completion.mjs recover --queue <queue-path>
|
|
15
16
|
```
|
|
16
17
|
|
|
17
|
-
`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`, `acceptedReport`, and `
|
|
18
|
+
`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`, `acceptedReport`, `ownerAcceptance`, and `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.
|
|
18
19
|
|
|
19
20
|
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.
|
|
20
21
|
|
|
@@ -86,9 +87,61 @@ verified, and the original failed or unverified report remains historical
|
|
|
86
87
|
evidence. Archive may preserve this paired history only at session end; it does
|
|
87
88
|
not rewrite the report or create a fresh acceptance.
|
|
88
89
|
|
|
90
|
+
## Feature waiver
|
|
91
|
+
|
|
92
|
+
Review defaults are strict for every feature. A `FeatureWaiver` loosens them for
|
|
93
|
+
one feature's queue, only in the user's own words from that feature's
|
|
94
|
+
interview. The agent never proposes or asks about one, and the next feature
|
|
95
|
+
starts from the defaults. Record the user's words in the note of a settled brief
|
|
96
|
+
decision, then write the feature's one waiver file, `waiver.json` beside
|
|
97
|
+
`brief.md` (never a verification input), before any review runs:
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"schemaVersion": 1,
|
|
102
|
+
"kind": "feature-waiver",
|
|
103
|
+
"queuePath": "docs/features/example/specs/.joycraft-spec-queue.json",
|
|
104
|
+
"covers": ["no-review"],
|
|
105
|
+
"instruction": "quick janky prototype, skip review on this",
|
|
106
|
+
"decision": "skip-review",
|
|
107
|
+
"source": { "path": "docs/features/example/brief.md", "sha256": "<SHA-256 of the brief>" },
|
|
108
|
+
"createdAt": "2026-11-02T12:00:00.000Z"
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`covers` is a nonempty subset of `no-review` and `tool-break`. `decision` is the
|
|
113
|
+
id of the brief decision that holds the user's words. `accept-waiver` refuses a
|
|
114
|
+
waiver for another queue, at another path, with unknown fields or covers, an
|
|
115
|
+
empty instruction, a `source` that is not this feature's `brief.md`, a brief hash
|
|
116
|
+
that differs, or a `decision` that is missing, not `clarified`/`assigned` with an
|
|
117
|
+
answer, or whose `note` or `answer` does not contain the instruction as whole
|
|
118
|
+
words (at least three; whitespace and line wraps are normalized).
|
|
119
|
+
|
|
120
|
+
- **Skip means review never runs** (decision `block-review-dispatch`).
|
|
121
|
+
`dispatch-preflight.mjs` refuses a reviewer for a queue whose `waiver.json`
|
|
122
|
+
covers `no-review`, in the worker tree or the coordinator tree, and refuses
|
|
123
|
+
while that file is unreadable. So no review, and no `FAIL`, exists for a spec
|
|
124
|
+
that `no-review` completes. Without `--report`, `no-review` completes an
|
|
125
|
+
`in-review` spec. As an extra guard it still refuses when a review report for
|
|
126
|
+
the spec is visible in the feature folder or `.joycraft/local/packets/`.
|
|
127
|
+
- With `--report`, the report must be current and independent (validated as for
|
|
128
|
+
`accept-owner`), `UNVERIFIED`, and every non-`PASS` observation must carry
|
|
129
|
+
`cause: "tool-break"`; the waiver must cover `tool-break`. The report keeps
|
|
130
|
+
its verdict; evidence errors are returned as diagnostics. A tool-break-only
|
|
131
|
+
waiver does not block reviewer dispatch.
|
|
132
|
+
- A `FAIL` verdict or any `FAIL` observation never completes, whatever `covers`
|
|
133
|
+
says. A `PASS` report uses `finalize-review`.
|
|
134
|
+
|
|
135
|
+
Limit: a review that ran before `waiver.json` existed is caught only by the
|
|
136
|
+
folder guard. The waiver comes from the interview, so it exists before dispatch.
|
|
137
|
+
On success the queue entry records `waiver: { path, sha256 }`, plus
|
|
138
|
+
`review: { path, sha256 }` for a report-backed completion, mutually exclusive
|
|
139
|
+
with `acceptedReport` and `ownerAcceptance`. A waived spec counts as `done` for
|
|
140
|
+
dependents. Report it as `done, waived by the user: "<instruction>"`.
|
|
141
|
+
|
|
89
142
|
## Evidence and reporting
|
|
90
143
|
|
|
91
|
-
Evidence records observations rather than promises. Command and test observations retain their actual argv, exit code, and unfiltered output receipt. Source review supports structural claims only. A required visual claim needs an inspected render, route, state, viewport, interactions, and observed outcomes. Record
|
|
144
|
+
Evidence records observations rather than promises. Command and test observations retain their actual argv, exit code, and unfiltered output receipt. Source review supports structural claims only. A required visual claim needs an inspected render, route, state, viewport, interactions, and observed outcomes. Record a check that should have run and did not (a tool break, an app that did not start) as `UNVERIFIED`, failures as `FAIL`, and limits explicitly. A claim that needs evidence beyond the recorded tool's `canShow`, or a package the user skipped, is an agreed limit, not `UNVERIFIED`; a check within `canShow` that could not run because the tool broke is `UNVERIFIED` with `cause: 'tool-break'`.
|
|
92
145
|
|
|
93
146
|
Report the command result, reviewer identity, receipt paths, actual observations, and limitations. A green suite or an implementation commit alone is not accepted completion.
|
|
94
147
|
|
|
@@ -10,6 +10,9 @@ For a mutable worker or stateful runtime check, first apply the conditional
|
|
|
10
10
|
worktree or a resource lease. A `read-only` workspace keeps declared source
|
|
11
11
|
inputs frozen; it may still write declared review reports and receipts outside
|
|
12
12
|
those inputs. Cache-mutating runtime work needs separate mutable state.
|
|
13
|
+
Reviewer preflight refuses a queue whose feature `waiver.json` covers
|
|
14
|
+
`no-review` ([completion guidance](completion.md#feature-waiver)); complete
|
|
15
|
+
those specs with `accept-waiver` instead.
|
|
13
16
|
|
|
14
17
|
## Contents
|
|
15
18
|
|
|
@@ -93,6 +96,11 @@ more, alone, with a fresh packet path. If it fails again, stop that spec's
|
|
|
93
96
|
review and tell the user its printed reason; never continue as if the review
|
|
94
97
|
started. Do not retry a `Task startup stopped:` refusal unchanged; fix its cause.
|
|
95
98
|
|
|
99
|
+
A worker that holds a spec for a tool break reports the spec, the tool, the
|
|
100
|
+
cause and the repair it tried. The coordinator tells the user at the first hold,
|
|
101
|
+
in the conversation, while other workers keep running; it does not wait for the
|
|
102
|
+
session end. The session-end summary lists every held spec again.
|
|
103
|
+
|
|
96
104
|
The return is `ready: true` for an available valid startup path, including a
|
|
97
105
|
hooks-disabled/manual path. It is not a cryptographic attestation. Missing human
|
|
98
106
|
prompt history for an enforced startup is explicit
|
|
@@ -158,6 +166,10 @@ decisions. Without a selector, the packet conservatively carries every current
|
|
|
158
166
|
answered decision from that brief. The packet retains its whole-brief reference
|
|
159
167
|
so workers can read each decision in context. Its inputs include any current
|
|
160
168
|
coupled counterpart required to review the requested behavior.
|
|
169
|
+
When `AGENTS.md` has a `## Review loop` section or this machine has
|
|
170
|
+
`.joycraft/local/review-loop.json`, the packet carries `reviewLoop`:
|
|
171
|
+
`{ path, section, local? }`, the shared section plus, when present,
|
|
172
|
+
`local: { path, record }` with this machine's host tools.
|
|
161
173
|
|
|
162
174
|
## Bind the hook source view
|
|
163
175
|
|