joycraft 1.2.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -23,9 +23,10 @@ Install Joycraft in this project.
23
23
  docs, interview me about what the repo cannot tell you, then show me the
24
24
  AGENTS.md and CLAUDE.md changes on a page before you write them. If the project
25
25
  is new or empty, ask me what I want to build.
26
- 4. Run `node .joycraft/runtime/review-tools.mjs plan --root .`. Tell me which tools
27
- you need to check your own work, which ones I have, and which ones are missing.
28
- Ask me before you install anything.
26
+ 4. Show me the review loop that setup found: for each package, the tool that
27
+ checks it and what that tool can show. If setup did not do this, run
28
+ `node .joycraft/runtime/review-tools.mjs plan --root .`. Ask me before you
29
+ install anything.
29
30
  Do not commit, publish, or ask me for API keys.
30
31
  ```
31
32
 
@@ -47,8 +48,8 @@ bigger than one quick change:
47
48
  3. **The agent builds each spec with tests.**
48
49
  4. **A second agent checks each spec.** It did not write the code. It reads the spec,
49
50
  runs the checks, and says PASS or FAIL. Only a PASS completes the spec. For a
50
- screen or page, it looks at the real result in a browser or simulator, if you
51
- installed those tools in step 4 of the install.
51
+ screen or page, it looks at the real result with the package's review tool
52
+ (see [The review loop](#the-review-loop)).
52
53
  5. **The agent wraps up.** It records what it learned for the next session.
53
54
 
54
55
  You do not need to call the Joycraft skills by name. Describe the work and the agent
@@ -163,22 +164,55 @@ If your docs are step-by-step procedures, the agent can offer
163
164
  [Doc Detective](https://docs.doc-detective.com) to run them as tests. It is opt-in:
164
165
  the agent says what it does not cover and installs nothing without your yes.
165
166
 
166
- ## Answering questions: the decision page
167
+ ## The review loop
168
+
169
+ The reviewing agent needs a tool that shows the real result: a browser for a web
170
+ app, a simulator for a mobile app, an HTTP check for an API. Joycraft decides what
171
+ counts as evidence; your project keeps its own tools.
172
+
173
+ - **Setup finds your tools.** For each package it looks for the tool you already
174
+ use (Playwright, Cypress, WebdriverIO, Maestro, Newman, an e2e script, a CI job
175
+ and others) and records one row per package in AGENTS.md, with what that tool can
176
+ show. Tools that belong to this machine, such as your agent's built-in browser, go
177
+ to `.joycraft/local/`. Packages that are not declared workspaces are found too, or
178
+ name them with `--packages`.
179
+ - **A gap gets one recommendation.** If a package has no tool, the agent recommends
180
+ one with its trade-offs and offers to look at others. It installs only on your yes,
181
+ and never with `sudo`, a licence or a sign-in. A project with no app records that
182
+ once and is not asked again.
183
+ - **Limits you agreed to are not failures.** A claim the recorded tool cannot show,
184
+ or a package you skipped, is reported as a limit. `UNVERIFIED` means a check that
185
+ should have run and did not.
186
+ - **Skipping review for one feature.** Say "skip review" in the feature interview.
187
+ The feature's `waiver.json` records your words, and no reviewer runs for it. A
188
+ waiver never hides a FAIL, and a new install keeps every check on.
189
+ - **A broken tool holds one spec.** If the browser or server breaks, the agent
190
+ tries one repair (restart, free the port, relaunch). Then it holds that spec as
191
+ `UNVERIFIED`, tells you, and keeps the rest of the queue going.
192
+
193
+ After an update, the agent checks the review loop again and asks only about what
194
+ changed.
167
195
 
168
- When the agent needs you to choose between options, it shows the questions on a
169
- decision page instead of in chat. Each question shows its context, its options and
170
- what it affects. You pick an answer, or "Something else" and say what you want, add
171
- a note if you want, and save. You can add or change a note after saving. If the
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.
196
+ ## Answering questions: the decision page
175
197
 
176
- Sometimes the agent forgets and lists the options in chat. Then say:
198
+ When the agent needs you to choose between options, it asks in your question
199
+ style. Setup asks for it once: one decision at a time with a short talk about each
200
+ answer, or a page of decisions; on a decision page or as numbered prose in chat.
201
+ To change it for one feature, say:
177
202
 
178
203
  ```text
179
- Put these questions in a Joycraft decision artifact so I can answer them there.
204
+ Ask me one question at a time, in chat, for this feature.
180
205
  ```
181
206
 
207
+ A consequential question gives the context, the question, two to four options each
208
+ with an example and a trade-off, and the agent's recommendation with its reason. On
209
+ the decision page, you pick an answer, or "Something else" and say what you want,
210
+ add a note if you want, and save. You can add or change a note after saving. If the
211
+ brief changes while the page is open, the page names the questions that changed and
212
+ keeps your other answers. In chat or on the page, the answers go into the brief, so
213
+ the agent does not ask again. If a question is not clear, say "wait, what?" and the
214
+ agent explains it again with more context.
215
+
182
216
  **Colors.** The page uses a light or dark theme. To match your project, ask:
183
217
 
184
218
  ```text
@@ -211,7 +245,9 @@ day. The check sends no project data. If there is a new version, the agent tells
211
245
  whether it is a patch, a minor release or a migration, lists each release since
212
246
  yours, and asks: update now, not now, or turn off. Automatic updates apply only
213
247
  patches. On a yes, it does the update
214
- for you, checks the result, and tells you what is different. A new major version is
248
+ for you, checks the result, and tells you what is different. After a minor release
249
+ it names what you can now do, and asks how you want questions if you have not said
250
+ yet. A new major version is
215
251
  always your choice.
216
252
 
217
253
  This is an instruction the agent follows, so it can forget. To check yourself, ask:
@@ -263,6 +299,7 @@ should forget:
263
299
  - **Lauren** (Cursor): prefer fixes in this order: architecture, then lint and CI, then skills and rules, then asking a human.
264
300
  - **Robert C. Martin**: impose values, not disciplines.
265
301
  - **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.
302
+ - **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
303
 
267
304
  The levels this project aims at are Dan Shapiro's. See [The levels](docs/guides/levels.md).
268
305
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "releaseVersion": "1.2.0",
3
+ "releaseVersion": "1.2.2",
4
4
  "manifestSchemas": [
5
5
  1
6
6
  ],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "joycraft",
3
- "version": "1.2.0",
3
+ "version": "1.2.2",
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.2.0",
17
- "summary": "The review loop uses the tool your project already has: setup finds it per package, recommends one only for a gap and installs on your yes; agreed limits are no longer UNVERIFIED; a per-feature waiver can skip review; a broken tool holds one spec, not the queue.",
16
+ "release": "1.2.2",
17
+ "summary": "The README describes the 1.2 review loop, the install prompt shows what setup found, and an update names what is new and offers the question style.",
18
18
  "autoSafeEligible": false
19
19
  },
20
20
  "scripts": {
@@ -86,13 +86,18 @@ screenshots-only tool). That is a tooling change: follow
86
86
  [change a tool](../../../.joycraft/references/setup.md#review-loop-tools) and
87
87
  record the answer, so it is not asked again.
88
88
 
89
- **Ask answerable questions in an artifact.** When the user must choose between
90
- options, record each choice as a brief decision and render the open decisions
91
- with the decision artifact (`.joycraft/references/artifacts.md`). Do not list
92
- option questions in chat: the artifact shows each question with its context and
93
- options, and saves the answers to the brief. Plain chat is only for one quick
94
- yes/no or an open question with no options. If you already asked option
95
- questions in chat and they are unanswered, move them to an artifact now.
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.
96
101
 
97
102
  **Use the project's folders.** If `joycraft.yaml` exists, run
98
103
  `node .joycraft/runtime/config.mjs` and use its `paths` wherever Joycraft guidance
@@ -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
- if (question.context || question.why || (question.affected || []).length) {
340
- var detail = node('details', { class: 'jca-details' }, [node('summary', { text: 'Context and impact' })]);
341
- if (question.context) detail.append(node('p', { text: question.context }));
342
- if (question.why) detail.append(node('p', { text: question.why }));
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
- (question.options || []).forEach(function (option) {
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 label = node('label', { class: 'jca-option', for: id }, [radio, node('span', { class: 'jca-option-copy' }, [node('strong', { text: option.label }), option.description ? node('small', { text: option.description }) : null])]);
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() {
@@ -1,11 +1,64 @@
1
1
  # Decision artifacts
2
2
 
3
- Use an artifact for every question that asks the user to choose between
4
- options: record the choices as brief decisions, then render them. Also use one
5
- for an editorial comparison of existing screenshots or a review summary. Plain
6
- chat is only for one quick yes/no or an open question with no options. It renders a selected view of the brief; the brief and queue remain
7
- the source of truth. Do not use one for a routine native question, a product UI
8
- slice whose real interaction must be explored, or a long questionnaire.
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. Artifact views also support an optional
36
- `description` on an option and `requiresNote: true` when that option needs a
37
- short explanation. Every question also offers "Something else" (value `custom`,
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
@@ -54,9 +54,18 @@ render nothing, ask nothing: a repeated setup must leave the project unchanged.
54
54
  each choice with options as a decision in a setup brief at
55
55
  `.joycraft/local/setup/brief.md` (format of `.joycraft/templates/brief.md`,
56
56
  `feature: setup`; give `.joycraft/local/` a `.gitignore` of `*` when it has
57
- none, so nothing there becomes a project change) and serve the decision
58
- artifact on it ([artifacts.md](artifacts.md)); plain chat is only for one
59
- quick yes/no or an open question with no options. The brief is scratch:
57
+ none, so nothing there becomes a project change). First, when
58
+ `node .joycraft/runtime/artifacts/cli.mjs questions` prints `unset: true`,
59
+ ask how the user wants questions, as two decisions: pacing (one decision at
60
+ a time with a short discussion after each answer, or a page of decisions)
61
+ and surface (the decision page, or numbered prose in chat). Give an example
62
+ of each. Ask only these two, in today's style (a page), and wait for the
63
+ answer before you ask any other setup question. Record it with
64
+ `questions --set pacing=...,surface=...` and say that the user can change it
65
+ for one feature later. Never ask again when a style is recorded. Then ask the
66
+ other setup decisions in that style ([asking questions](artifacts.md#asking-questions));
67
+ plain chat with no decision is only for one quick yes/no or an open question
68
+ with no options. The brief is scratch:
60
69
  each answer then goes to its home in step 3. Stop when the user says enough. Never ask again
61
70
  what the user answered or a home already states. Keep the user's words apart
62
71
  from your observations and assumptions. On a bare project, offer the
@@ -66,12 +75,16 @@ render nothing, ask nothing: a repeated setup must leave the project unchanged.
66
75
  “First action in each session: run
67
76
  `node .joycraft/runtime/update-check.mjs check`. If it prints JSON, follow
68
77
  `.joycraft/references/update.md`.” and “Show every document a person must
69
- read, review or answer (a brief, plan, spec set, review or set of
70
- questions) as a rendered page, never only as Markdown in chat: use the
71
- decision artifact (`node .joycraft/runtime/artifacts/cli.mjs`, see
72
- `.joycraft/references/artifacts.md`) for a brief or questions, or an HTML
73
- page for any other document. Show it where the person works (see
74
- `.joycraft/references/artifacts.md#showing-a-page`) and say where it is.”
78
+ read or review (a brief, plan, spec set or review) as a rendered page,
79
+ never only as Markdown in chat: use the decision artifact
80
+ (`node .joycraft/runtime/artifacts/cli.mjs`, see
81
+ `.joycraft/references/artifacts.md`) for a brief, or an HTML page for any
82
+ other document. Show it where the person works (see
83
+ `.joycraft/references/artifacts.md#showing-a-page`) and say where it is.
84
+ Ask questions in the project's question style
85
+ (`.joycraft/references/artifacts.md#asking-questions`).” Replace an older
86
+ version of this line that lists a "set of questions", so it does not
87
+ override a chat question style.
75
88
  - **The map**: one `## Context Map` table (`| Document | Read when |`). One
76
89
  row per real home: each required or reference doc, and each home you
77
90
  create. A read-when names the work that needs the doc ("Changing how counts
@@ -168,9 +181,11 @@ detects each package from its manifests, probes versions read-only, and prints
168
181
  one table and at most one question. It never installs. When it prints
169
182
  `Review loop unchanged.`, ask nothing. Packages come from declared workspaces;
170
183
  with none and no root manifest, from the manifests below the root that git does
171
- not ignore. When it prints `No packages found`, ask the user which folders hold
172
- the apps and pass them as `--packages <dir,dir>` to `plan`, `install` and
173
- `record`.
184
+ not ignore. When it prints `No packages found`, ask the user once which folders
185
+ hold the apps and pass them as `--packages <dir,dir>` to `plan`, `install` and
186
+ `record`. When the user says there is no app to review (for example one script
187
+ with no manifest), record their words with `record --none "<reason>"`; a
188
+ repeated setup then prints `Review loop unchanged.` and asks nothing.
174
189
 
175
190
  Show the table: what the plan found per package. Ask the user to confirm it or
176
191
  name a tool the plan missed, together with its one question. For a gap, say
@@ -296,10 +311,11 @@ changes the next action. Prefer one short contextual question and continue
296
311
  independent work while it is pending. Do not generate a questionnaire or start
297
312
  building an imagined app.
298
313
 
299
- Use the project’s existing interaction home for a choice. A question with
300
- options goes in the decision artifact; only one quick yes/no or an open question
301
- with no options stays in native chat. Retain a chat answer in the
302
- owning brief and do not ask it again.
314
+ Use the project’s existing interaction home for a choice. Ask a question with
315
+ options in the user's question style ([asking questions](artifacts.md#asking-questions)),
316
+ in the decision artifact or in chat; only one quick yes/no or an open question
317
+ with no options stays in native chat without a decision. Retain a chat answer in
318
+ the owning brief and do not ask it again.
303
319
 
304
320
  ## Finish setup and continue
305
321
 
@@ -315,7 +331,7 @@ installation manifest `.joycraft/installation.json` records the installed bytes;
315
331
  it is dispatch input, not proof that hooks ran or that a review was independent.
316
332
 
317
333
  A new worker reads `.joycraft/preferences.json` before work, reuses explicit
318
- model, effort, role, concurrency and verification choices, and inspects the
334
+ model, effort, role, concurrency, verification and question-style choices, and inspects the
319
335
  host's available planner, implementer, reviewer, testing, UI and fixture
320
336
  capabilities instead of assuming a model. It states unavailable roles plainly.
321
337
  Setup and upgrade never change accepted queues, decision state, user guidance or
@@ -28,7 +28,12 @@ Use the version from `latest`:
28
28
  migration plan and stops: show the plan and follow its steps with the user. Never
29
29
  apply a migration without the user's yes.
30
30
  3. Run `npx joycraft@<latest> doctor .`.
31
- 4. Tell the user in plain words what is different now.
31
+ 4. Tell the user in plain words what is different now. For a `minor` or
32
+ `migration`, name what the user can now do or say, one line per release since
33
+ the old version, from the release summaries the check listed (and the
34
+ changelog, when you can read it). When
35
+ `node .joycraft/runtime/artifacts/cli.mjs questions` prints `unset: true`,
36
+ ask for the question style now, as [setup](setup.md) step 2 says.
32
37
  5. Run the review-loop plan
33
38
  ([review loop tools](setup.md#review-loop-tools)). When it prints
34
39
  `Review loop unchanged.`, say nothing about it. When it reports a newly
@@ -24,8 +24,10 @@ Routine refinements within the answer do not require another approval.
24
24
 
25
25
  ## Decision artifacts
26
26
 
27
- Ask the user to choose between options through the artifact workflow in
28
- [artifacts.md](artifacts.md), not as a list in chat. Plain chat is only for one
27
+ Record each choice between options as a brief decision and ask it in the
28
+ user's question style ([asking questions](artifacts.md#asking-questions)): one
29
+ at a time or as a page, in the artifact or in chat. Save every answer to the
30
+ brief, whatever the surface. Plain chat with no decision record is only for one
29
31
  quick yes/no or an open question with no options.
30
32
  The brief remains authoritative; artifact data selects what to show and does not
31
33
  copy the brief or hold independent answers.
@@ -36,7 +38,9 @@ The optional `joycraft-ui-slice/scripts/serve.mjs` helper supports a JSON flow
36
38
  array under top-level `decisions:` in YAML frontmatter, as in the brief template.
37
39
  Each displayed record has `id`, `status`, `question`, `answer` (null or an option
38
40
  value), `options` (two or more `{value,label}` records) and `affected` (paths/IDs).
39
- Options may additionally have a concise `description` and `requiresNote: true`.
41
+ Options may additionally have a concise `description`, `example`, `tradeoff`,
42
+ `recommended: true` and `requiresNote: true`; a decision may have `context`,
43
+ `why`, `details` and `recommendation` ([decisions](artifacts.md#decisions-and-view-data)).
40
44
  Other record fields and all text outside that array are preserved. Unsupported or
41
45
  malformed frontmatter is rejected; adapt the artifact to an existing project
42
46
  format instead of migrating it without cause. This is an authoring convention,
@@ -1,19 +1,19 @@
1
1
  import { resolve } from 'node:path';
2
2
  import { pathToFileURL } from 'node:url';
3
- import { loadArtifact, persistResponses, readProjectFile, writeArtifact } from './model.mjs';
3
+ import { loadArtifact, persistResponses, readProjectFile, replaceBrief, writeArtifact } from './model.mjs';
4
4
  import { renderArtifact } from './render.mjs';
5
5
  import { startArtifact } from './server.mjs';
6
- import { setArtifactColors, setArtifactTheme } from './preferences.mjs';
6
+ import { briefQuestionStyle, effectiveQuestionStyle, parseQuestionStyle, projectQuestionStyle, setArtifactColors, setArtifactTheme, setQuestionStyle, withBriefQuestionStyle } from './preferences.mjs';
7
7
 
8
8
  export async function main(argv, root = process.cwd()) {
9
9
  const [command, ...args] = argv;
10
- const flags = command === 'serve' ? ['--brief', '--view', '--theme'] : command === 'build' ? ['--brief', '--view', '--out', '--mode', '--theme'] : command === 'import' ? ['--brief', '--view', '--responses', '--apply'] : command === 'theme' ? ['--set'] : command === 'colors' ? ['--set', '--reset'] : [];
11
- if (!flags.length) throw new Error('Use serve --brief <path> [--view <path>] [--theme light|dark], build --brief <path> [--view <path>] --out <path> --mode claude|portable [--theme light|dark], import --brief <path> [--view <path>] --responses <path> [--apply], theme --set light|dark, or colors --set <colors.json> | --reset');
10
+ const flags = command === 'serve' ? ['--brief', '--view', '--theme'] : command === 'build' ? ['--brief', '--view', '--out', '--mode', '--theme'] : command === 'import' ? ['--brief', '--view', '--responses', '--apply'] : command === 'theme' ? ['--set'] : command === 'colors' ? ['--set', '--reset'] : command === 'questions' ? ['--brief', '--set', '--clear'] : [];
11
+ if (!flags.length) throw new Error('Use serve --brief <path> [--view <path>] [--theme light|dark], build --brief <path> [--view <path>] --out <path> --mode claude|portable [--theme light|dark], import --brief <path> [--view <path>] --responses <path> [--apply], theme --set light|dark, colors --set <colors.json> | --reset, or questions [--brief <path>] [--set pacing=one-at-a-time|page,surface=chat|artifact | --clear]');
12
12
  const values = {};
13
13
  for (let i = 0; i < args.length; i += 1) {
14
14
  const flag = args[i];
15
15
  if (!flags.includes(flag) || Object.hasOwn(values, flag)) throw new Error(`Unknown or repeated argument: ${flag}`);
16
- if (flag === '--apply' || flag === '--reset') values[flag] = true;
16
+ if (flag === '--apply' || flag === '--reset' || flag === '--clear') values[flag] = true;
17
17
  else { if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`Missing value for ${flag}`); values[flag] = args[++i]; }
18
18
  }
19
19
  if (command === 'theme') {
@@ -22,6 +22,30 @@ export async function main(argv, root = process.cwd()) {
22
22
  console.log(JSON.stringify({ path: '.joycraft/preferences.json', theme: preferences.artifacts.theme }, null, 2));
23
23
  return preferences;
24
24
  }
25
+ if (command === 'questions') {
26
+ // With --brief, --set and --clear change only that feature; without it, --set changes the project default.
27
+ const briefPath = values['--brief'];
28
+ if (values['--set'] && values['--clear']) throw new Error('Use --set or --clear, not both');
29
+ if (values['--clear'] && !briefPath) throw new Error('--clear needs --brief: it removes a feature\'s own question style');
30
+ const change = values['--set'] ? parseQuestionStyle(values['--set']) : values['--clear'] ? null : undefined;
31
+ // Read the project default first: a bad stored preference must stop the command before any write.
32
+ const project = await projectQuestionStyle(root);
33
+ let brief;
34
+ if (briefPath) {
35
+ const text = (await readProjectFile(root, briefPath)).toString('utf8');
36
+ brief = briefQuestionStyle(text);
37
+ if (change !== undefined) {
38
+ const updated = withBriefQuestionStyle(text, change);
39
+ // Check the new text before the write: a failed command must leave the brief as it was.
40
+ brief = briefQuestionStyle(updated);
41
+ if (JSON.stringify(brief ?? null) !== JSON.stringify(change === null ? null : { ...(briefQuestionStyle(text) ?? {}), ...change })) throw new Error('Could not write question-style: safely; the brief is unchanged');
42
+ await replaceBrief(root, briefPath, text, updated);
43
+ }
44
+ } else if (change) await setQuestionStyle(root, change);
45
+ const style = effectiveQuestionStyle({ project: change && !briefPath ? await projectQuestionStyle(root) : project, brief });
46
+ console.log(JSON.stringify(style, null, 2));
47
+ return style;
48
+ }
25
49
  if (command === 'colors') {
26
50
  if (!values['--set'] === !values['--reset']) throw new Error('Colors needs --set <colors.json> or --reset');
27
51
  let colors = null;
@@ -102,16 +102,25 @@ function displayedDecision(brief, id) {
102
102
  !Array.isArray(decision.affected) || !decision.affected.every(nonempty)) {
103
103
  throw new Error('Displayed decision needs question, options and affected references');
104
104
  }
105
- for (const field of ['why', 'context', 'details']) validateOptionalString(decision[field], `Decision ${field}`);
105
+ for (const field of ['why', 'context', 'details', 'recommendation']) validateOptionalString(decision[field], `Decision ${field}`);
106
106
  const values = new Set();
107
+ let recommended = 0;
107
108
  for (const option of decision.options) {
108
109
  if (!option || typeof option !== 'object' || Array.isArray(option) || !nonempty(option.value) || !nonempty(option.label) || values.has(option.value)) {
109
110
  throw new Error('Invalid decision options');
110
111
  }
111
- validateOptionalString(option.description, 'Option description');
112
+ for (const field of ['description', 'example', 'tradeoff']) validateOptionalString(option[field], `Option ${field}`);
112
113
  if (option.requiresNote !== undefined && typeof option.requiresNote !== 'boolean') throw new Error('Option requiresNote must be boolean');
114
+ if (option.recommended !== undefined && typeof option.recommended !== 'boolean') throw new Error('Option recommended must be boolean');
115
+ if (option.recommended === true) {
116
+ if (option.value === CUSTOM_OPTION.value) throw new Error('"Something else" cannot be the recommended option');
117
+ recommended += 1;
118
+ }
113
119
  values.add(option.value);
114
120
  }
121
+ // One recommendation at most, and a stated reason needs the option it recommends.
122
+ if (recommended > 1) throw new Error('Only one option can be recommended');
123
+ if (decision.recommendation !== undefined && recommended === 0) throw new Error('A recommendation needs a recommended option');
115
124
  values.add(CUSTOM_OPTION.value);
116
125
  if (!(decision.answer === null || values.has(decision.answer)) || (decision.status === 'clarified' && decision.answer === null)) {
117
126
  throw new Error('Invalid decision answer');
@@ -127,15 +136,14 @@ function publicQuestion(decision) {
127
136
  question: decision.question,
128
137
  options: withCustomOption(decision.options).map(option => {
129
138
  const result = { value: option.value, label: option.label };
130
- if (option.description !== undefined) result.description = option.description;
131
- if (option.requiresNote !== undefined) result.requiresNote = option.requiresNote;
139
+ for (const field of ['description', 'example', 'tradeoff', 'requiresNote', 'recommended']) if (option[field] !== undefined) result[field] = option[field];
132
140
  return result;
133
141
  }),
134
142
  affected: [...decision.affected],
135
143
  status: decision.status,
136
144
  answer: decision.answer
137
145
  };
138
- for (const field of ['why', 'context', 'details']) if (decision[field] !== undefined) question[field] = decision[field];
146
+ for (const field of ['why', 'context', 'details', 'recommendation']) if (decision[field] !== undefined) question[field] = decision[field];
139
147
  if (decision.note !== undefined) question.note = decision.note;
140
148
  return question;
141
149
  }
@@ -111,7 +111,7 @@ export function validateEnvelope(envelope, model) {
111
111
  }
112
112
 
113
113
  /** Cooperative lock + compare before atomic replacement; no silent stale write. */
114
- async function replaceBrief(root, path, before, after) {
114
+ export async function replaceBrief(root, path, before, after) {
115
115
  if (before === after) return;
116
116
  const absolute = await checkedPath(root, path);
117
117
  const lock = `${absolute}.joycraft-answer-lock`;
@@ -76,6 +76,7 @@ function parsePreferences(bytes) {
76
76
  catch { throw new Error(`Invalid JSON: ${preferencePath}`); }
77
77
  if (!preferences || typeof preferences !== 'object' || Array.isArray(preferences)) throw new Error(`${preferencePath} must contain an object`);
78
78
  if (preferences.artifacts !== undefined && (!preferences.artifacts || typeof preferences.artifacts !== 'object' || Array.isArray(preferences.artifacts))) throw new Error(`${preferencePath} artifacts must be an object`);
79
+ if (preferences.questions !== undefined) checkedQuestionStyle(preferences.questions, `${preferencePath} questions`);
79
80
  return preferences;
80
81
  }
81
82
 
@@ -87,7 +88,7 @@ export async function artifactTheme(root) {
87
88
  return preferences.artifacts?.theme === undefined ? undefined : checkedTheme(preferences.artifacts.theme, 'Artifact preference theme');
88
89
  }
89
90
 
90
- async function updatePreferences(root, change) {
91
+ async function updatePreferences(root, change, section = 'artifacts') {
91
92
  const base = await realpath(root);
92
93
  const directory = join(base, '.joycraft');
93
94
  await mkdir(directory, { recursive: true });
@@ -97,7 +98,7 @@ async function updatePreferences(root, change) {
97
98
  let preferences;
98
99
  try { preferences = parsePreferences(await readFile(path)); }
99
100
  catch (error) { if (error.code !== 'ENOENT') throw error; preferences = { schemaVersion: 1 }; }
100
- const updated = { ...preferences, artifacts: change({ ...(preferences.artifacts ?? {}) }) };
101
+ const updated = { ...preferences, [section]: change({ ...(preferences[section] ?? {}) }) };
101
102
  const temporary = `${path}.prefs-${randomBytes(8).toString('hex')}`;
102
103
  const file = await open(temporary, 'wx', 0o600);
103
104
  try { await file.writeFile(`${JSON.stringify(updated, null, 2)}\n`); await file.sync(); }
@@ -125,3 +126,95 @@ export async function setArtifactColors(root, colors) {
125
126
  const checked = colors === null ? null : await checkedColors(colors);
126
127
  return updatePreferences(root, ({ colors: _colors, ...artifacts }) => checked && Object.keys(checked).length ? { ...artifacts, colors: checked } : artifacts);
127
128
  }
129
+
130
+ // How an agent asks the user: how many decisions at once, and where.
131
+ const questionValues = Object.freeze({ pacing: ['one-at-a-time', 'page'], surface: ['chat', 'artifact'] });
132
+ /** With no recorded style, Joycraft asks as it always has (decision `unset-default`). */
133
+ export const DEFAULT_QUESTION_STYLE = Object.freeze({ pacing: 'page', surface: 'artifact' });
134
+ const styleLine = /^question-style:[ \t]*([^\r\n]*)/gm;
135
+
136
+ export function checkedQuestionStyle(style, source = 'Question style') {
137
+ if (!style || typeof style !== 'object' || Array.isArray(style)) throw new Error(`${source} must be an object with pacing and/or surface`);
138
+ for (const [key, value] of Object.entries(style)) {
139
+ if (!Object.hasOwn(questionValues, key)) throw new Error(`${source} has an unknown key: ${key}. Use: ${Object.keys(questionValues).join(', ')}`);
140
+ if (!questionValues[key].includes(value)) throw new Error(`${source} ${key} must be ${questionValues[key].join(' or ')}`);
141
+ }
142
+ return style;
143
+ }
144
+
145
+ /** Parse `pacing=one-at-a-time,surface=chat` from the command line. */
146
+ export function parseQuestionStyle(value) {
147
+ const style = {};
148
+ for (const pair of String(value).split(',')) {
149
+ const [key, choice, extra] = pair.split('=').map(part => part.trim());
150
+ if (!key || choice === undefined || extra !== undefined || Object.hasOwn(style, key)) throw new Error('Use --set key=value[,key=value], for example pacing=one-at-a-time,surface=chat');
151
+ style[key] = choice;
152
+ }
153
+ return checkedQuestionStyle(style, 'Question style');
154
+ }
155
+
156
+ function frontmatterBounds(text) {
157
+ const match = /^(---\r?\n)([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
158
+ if (!match) throw new Error('Brief needs YAML frontmatter');
159
+ const start = match[1].length;
160
+ return { start, end: start + match[2].length };
161
+ }
162
+
163
+ function styleLines(text) {
164
+ const { start, end } = frontmatterBounds(text);
165
+ return [...text.slice(start, end).matchAll(styleLine)].map(match => ({ index: start + match.index, length: match[0].length, value: match[1] }));
166
+ }
167
+
168
+ /** The brief's own question style, or undefined when it keeps the project's. */
169
+ export function briefQuestionStyle(text) {
170
+ const lines = styleLines(text);
171
+ if (lines.length > 1) throw new Error('Expected at most one question-style: line');
172
+ if (!lines.length) return undefined;
173
+ let style;
174
+ try { style = JSON.parse(lines[0].value); }
175
+ catch { throw new Error('question-style: must be a JSON object, for example {"pacing":"one-at-a-time"}'); }
176
+ return checkedQuestionStyle(style, 'Brief question-style');
177
+ }
178
+
179
+ /** Replace, add or (with null) remove only the brief's question-style line. */
180
+ export function withBriefQuestionStyle(text, style) {
181
+ const current = briefQuestionStyle(text);
182
+ const [line] = styleLines(text);
183
+ if (style === null) {
184
+ if (!line) return text;
185
+ // Remove the line with its own ending, whatever the rest of the file uses.
186
+ const next = text.indexOf('\n', line.index + line.length);
187
+ return text.slice(0, line.index) + text.slice(next + 1);
188
+ }
189
+ const merged = checkedQuestionStyle({ ...(current ?? {}), ...style }, 'Brief question-style');
190
+ const replacement = `question-style: ${JSON.stringify(merged)}`;
191
+ if (line) return text.slice(0, line.index) + replacement + text.slice(line.index + line.length);
192
+ // The new line takes the ending of the last frontmatter line, so --clear gives the same bytes back.
193
+ const { end } = frontmatterBounds(text);
194
+ const newline = text.startsWith('\r\n', end) ? '\r\n' : '\n';
195
+ return text.slice(0, end) + newline + replacement + text.slice(end);
196
+ }
197
+
198
+ export async function projectQuestionStyle(root) {
199
+ let path;
200
+ try { path = await checkedPreferencePath(root); }
201
+ catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
202
+ return parsePreferences(await readFile(path)).questions;
203
+ }
204
+
205
+ export async function setQuestionStyle(root, style) {
206
+ checkedQuestionStyle(style);
207
+ return updatePreferences(root, questions => ({ ...questions, ...style }), 'questions');
208
+ }
209
+
210
+ /** Each key from the brief first, then the project, then the default; `source` says which. */
211
+ export function effectiveQuestionStyle({ project, brief } = {}) {
212
+ const result = {};
213
+ const source = {};
214
+ for (const key of Object.keys(questionValues)) {
215
+ [result[key], source[key]] = brief?.[key] !== undefined ? [brief[key], 'brief'] : project?.[key] !== undefined ? [project[key], 'project'] : [DEFAULT_QUESTION_STYLE[key], 'default'];
216
+ }
217
+ result.source = source;
218
+ if (project === undefined || Object.keys(project).length === 0) result.unset = true;
219
+ return result;
220
+ }
@@ -554,7 +554,8 @@ const roleText = { ui: 'tool that can show the UI', request: 'HTTP check', tests
554
554
  export function renderPlan(plan, changes = null) {
555
555
  if (!plan.packages.length) {
556
556
  return ['Review loop plan', '', 'No packages found: no workspaces are declared and no project manifest was found below the root.',
557
- '', 'Which folders hold the apps? Name them with `--packages <dir,dir>` on plan, install and record.'].join('\n');
557
+ '', 'Which folders hold the apps? Name them with `--packages <dir,dir>` on plan, install and record.',
558
+ 'If the project has no app to review, record the user\'s reason with `record --none "<reason>"`, so this is not asked again.'].join('\n');
558
559
  }
559
560
  const lines = ['Review loop plan', '', '| Package | Kind | Tool | Status | To install | Can show |', '|---|---|---|---|---|---|'];
560
561
  for (const entry of plan.packages) for (const item of entry.tools.filter(tool => !tool.shared)) {
@@ -781,8 +782,10 @@ const cellSafe = text => String(text).replace(/\|/g, '\\|').replace(/\n+/g, '; '
781
782
  * Write the chosen setup to AGENTS.md under `## Review loop`, replacing only that section: one row per package.
782
783
  * Earlier picks and skips stay for the packages this call does not name. Host tools go to the local record only.
783
784
  */
784
- export function recordReviewLoop(root, plan, { skipped = [], choose = [], commands = [], canShow = [], host = null, hostTools = [] } = {}) {
785
- if (!plan.packages.length) throw new Error('No packages found, so there is nothing to record; name them with --packages <dir,dir>');
785
+ export function recordReviewLoop(root, plan, { skipped = [], choose = [], commands = [], canShow = [], host = null, hostTools = [], none = null } = {}) {
786
+ if (none !== null && (typeof none !== 'string' || !none.trim())) throw new Error('--none takes the user\'s reason, for example --none "a single script, no app to review"');
787
+ if (none !== null && plan.packages.length) throw new Error(`--none records that there are no packages, but this project has ${plan.packages.map(entry => entry.path).join(', ')}`);
788
+ if (!plan.packages.length && none === null) throw new Error('No packages found, so there is nothing to record; name them with --packages <dir,dir>, or record the user\'s reason with --none "<reason>"');
786
789
  if (hostTools.length && !host) throw new Error('--host-tools needs --host <name>, the host these tools belong to');
787
790
  const picks = picksFor(root, plan, { choose, commands, canShow });
788
791
  const skips = skipsFor(plan, skipped);
@@ -822,8 +825,8 @@ export function recordReviewLoop(root, plan, { skipped = [], choose = [], comman
822
825
  const section = [sectionHeading, '',
823
826
  'Recorded by Joycraft setup. The implementer, reviewer and UI checks use these tools and commands.',
824
827
  `Tools a host brings itself are recorded per machine in \`${localFile}\`, not here.`, '',
825
- ...rows,
826
- '', `<!-- joycraft:review-loop v2 ${JSON.stringify({ packages })} -->`, ''].join('\n');
828
+ ...(none === null ? rows : [`No app packages to review. The user said: ${cellSafe(none.trim())}`]),
829
+ '', `<!-- joycraft:review-loop v2 ${JSON.stringify({ packages, ...(none === null ? {} : { none: none.trim() }) })} -->`, ''].join('\n');
827
830
  const file = path.join(root, 'AGENTS.md');
828
831
  const text = read(file);
829
832
  let created = false;
@@ -863,6 +866,8 @@ export async function main(argv = process.argv.slice(2)) {
863
866
  const repeated = new Set(['--choose', '--command', '--can-show', '--skip']);
864
867
  for (let index = 0; index < rest.length; index += 1) {
865
868
  if (rest[index] === '--yes') { flags['--yes'] = true; continue; }
869
+ // A flag's value is the next word; another flag there means the value is missing.
870
+ if (rest[index + 1] === undefined || rest[index + 1].startsWith('--')) throw new Error(`Missing value for ${rest[index]}`);
866
871
  if (repeated.has(rest[index])) (flags[rest[index]] ??= []).push(rest[index + 1]);
867
872
  else flags[rest[index]] = rest[index + 1];
868
873
  index += 1;
@@ -889,12 +894,12 @@ export async function main(argv = process.argv.slice(2)) {
889
894
  // The shared record is detected without the host's tools; those go to the local record.
890
895
  const result = recordReviewLoop(root, reviewLoopPlan(root, { ...options, hostTools: [] }), {
891
896
  skipped: many('--skip'), choose: many('--choose'), commands: many('--command', false), canShow: many('--can-show', false),
892
- host: flags['--host'] ?? null, hostTools: options.hostTools });
897
+ host: flags['--host'] ?? null, hostTools: options.hostTools, none: flags['--none'] ?? null });
893
898
  process.stdout.write(`${JSON.stringify(result)}\n`);
894
899
  return result;
895
900
  }
896
901
  throw new Error('Usage: review-tools.mjs plan|install|record --root <project> [--packages apps/web,apps/api] [--host-tools browser,simulator] [--tools playwright --yes]'
897
- + ' [record: --choose <package>=<tool> --command <package>=<command> --can-show <package>=picture,run --skip <tool>|<package>:<tool>|<package> --host <name>]');
902
+ + ' [record: --choose <package>=<tool> --command <package>=<command> --can-show <package>=picture,run --skip <tool>|<package>:<tool>|<package> --host <name> | --none "<reason>"]');
898
903
  }
899
904
 
900
905
  if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  feature: example-feature
3
3
  decisions: [
4
- {"id":"presentation","status":"open","question":"Which presentation fits your task?","answer":null,"options":[{"value":"rows","label":"Compact rows"},{"value":"cards","label":"Visual cards"}],"affected":["collection-presentation"]}
4
+ {"id":"presentation","status":"open","question":"Which presentation fits your task?","answer":null,"context":"The collection page lists 200 items. Today it shows plain rows, and users ask for pictures.","options":[{"value":"rows","label":"Compact rows","description":"Keep the list and add a small picture to each row.","example":"About 20 items show without scrolling.","tradeoff":"Pictures are too small to compare."},{"value":"cards","label":"Visual cards","recommended":true,"description":"Show each item as a card with a large picture.","example":"About 8 items show without scrolling.","tradeoff":"More scrolling to find one item."}],"recommendation":"Users asked for pictures, and cards show them best.","affected":["collection-presentation"]}
5
5
  ]
6
6
  ---
7
7
  # Feature intent
package/payload/PIN CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "source": "joycraft-prototype",
4
- "tag": "field-15",
5
- "commit": "5ee330f48d06ee222a27656cf0864d66384cce05",
4
+ "tag": "field-17",
5
+ "commit": "0e88e6da3adc605a306db1ec058a4690b2eb5cb2",
6
6
  "files": {
7
7
  ".agents/skills/joycraft-cleanup/SKILL.md": "99ce785e551be33412ac7a99ce44585a9b2be4440617caac273680383b4f7057",
8
8
  ".agents/skills/joycraft-context/SKILL.md": "e2f85baa47058fd61811fdb60d0cb41fb3f505f3957812d929db95bb99124f1b",
9
9
  ".agents/skills/joycraft-decompose/SKILL.md": "71b518d4fa8aeda5d1c0e72f34b3f7f846b3bba055adf509344b40bea35f070e",
10
- ".agents/skills/joycraft-entry/SKILL.md": "33c30a55fe1b6c8576456bf43e37df50772ed03d94eb2e99da93664c6019f499",
10
+ ".agents/skills/joycraft-entry/SKILL.md": "6b2ac0e52f0751c7b7587b495349c29f707c61421312dc9ad8d3821aec936855",
11
11
  ".agents/skills/joycraft-implement/SKILL.md": "65909a6e3a320d8c0591e10ea1fc26469facadc27dafd3060dd0eabaf06890d9",
12
12
  ".agents/skills/joycraft-retro/SKILL.md": "156f36cb047604c734bf273bd02822d964b6af86619ed6c2a30fa6d79eb9a986",
13
13
  ".agents/skills/joycraft-retro/agents/openai.yaml": "f0eb4732261635f41e08f0bbe9a931d62fd8ac645149d3406e6fc7e16a81750b",
@@ -18,13 +18,13 @@
18
18
  ".agents/skills/joycraft-verify/SKILL.md": "219f08d5f66d6c63338c7d4cc75e81fe7d2d993723728876136ab8ca5ed6f8c5",
19
19
  ".claude/agents/joycraft-implementer.md": "30b26779bd49d2d66758bcb26442e78755b018a3830ac52ff634ebf057ce1cc5",
20
20
  ".claude/agents/joycraft-reviewer.md": "d671eb39827d5139d9d458d4cb7f5ce624bd40ec8cc5479f9d285bb787b5e5c6",
21
- ".joycraft/assets/artifacts/kit.css": "b3481214b73fa8919708075e97aae60ed42dda386c8837129ee153099adf5b43",
22
- ".joycraft/assets/artifacts/kit.js": "5de876e66536ad1e10ad6dc65d775c6d0a59540c81c5b48b5d4239fbdbf0569a",
21
+ ".joycraft/assets/artifacts/kit.css": "9c19cc52f16eb1d1beb6222ec4e206c567daf9952ff1f5597ea4d6050b72125a",
22
+ ".joycraft/assets/artifacts/kit.js": "c60ae4441fb20146677313b27f949598889f40e8b90167b70db04f997854966d",
23
23
  ".joycraft/assets/artifacts/transports.js": "318e97895468b47f07febc913d3a6e100b0ad19b78b3a4fc51bebc488e67c25d",
24
24
  ".joycraft/contracts/types.d.ts": "e91f6a4199c0219cda3630a27ee0281ef94d4284221910840961061ee3b30d4f",
25
25
  ".joycraft/references/architecture.md": "52eaaa4b88053481c9f8cad2418ea0f1db880184c3a50c95901f30f24be75852",
26
26
  ".joycraft/references/archive.md": "e9e662096f9e95d132c29e07d1a2624ca0826b5e9c1042f411e4ea2bf3805b67",
27
- ".joycraft/references/artifacts.md": "f9ae6d86f604eea7424b97076aad91bec0f6b69e4c4d6954f86d2b15fb531f66",
27
+ ".joycraft/references/artifacts.md": "7fab219f6d6d8b23ef3b44a509f637b085b551b34f28622d6dc1167a7f484c6a",
28
28
  ".joycraft/references/cleanup.md": "aa784c63442a289c67de359d82c78abca3aa8cab5b5e2d91fcd731b45c209003",
29
29
  ".joycraft/references/completion.md": "7e6b1fe95aab6d97e514995a35f0f6cc67bdea18e4570565e2eef4900e0da01b",
30
30
  ".joycraft/references/context.md": "df72d3b59d55f0d9741234d4a3d7b56532f560d787c88d5d8630d954472bc430",
@@ -34,16 +34,16 @@
34
34
  ".joycraft/references/knowledge.md": "a08a117a5d0ae65a45dfd8ab3f3da92dd3c7aeedaa09ae1d71ddf3d6528c7f95",
35
35
  ".joycraft/references/recurring-failures.md": "7080f6c55492bc19c2897f4f0b128a830a71cdb516678c79ff6e97ffa1dc6b86",
36
36
  ".joycraft/references/retro.md": "f359eae19747777fb4687c1bc7eb280f0319ae629ee62913346e60fc56551562",
37
- ".joycraft/references/setup.md": "e50cf15215ae58ebb1eb7df5b47027319ce7f4fd4c2b981f335ab0d3eac6db34",
37
+ ".joycraft/references/setup.md": "a9bd9072adc9f021b46287ff0422281ddb2285ac34738b6e29ad11cc60e8a6e5",
38
38
  ".joycraft/references/testing.md": "ddbc0e69212f4bf29f32f65e139c016b12eb40c29f621a99510129bedf292950",
39
- ".joycraft/references/update.md": "b6ca2f6f4073ed9a566ae467cbe4c60bf79baead845cc45138eec4c4ae28891e",
40
- ".joycraft/references/workflow.md": "f634423039b7ed48a8c470df37153036e6fe6a2b64a0e878db3a062f77a6527c",
39
+ ".joycraft/references/update.md": "36af36ab3d47b5ea46a8f71090333771e5e1deaa6ca19739a75c9fd4aea14eba",
40
+ ".joycraft/references/workflow.md": "5b330debc6759b8f7975b159632f51074802067291fe4f4bebfb344f5b60cc52",
41
41
  ".joycraft/references/worktrees.md": "fb18af0cd76d4e3c5d5b892a7ae10946f21f189e642243235c188b571635f735",
42
42
  ".joycraft/runtime/archive.mjs": "82b4d9567942a4abd21594ea299c4d323a8306ec7545cb0030431c87bd37f8b2",
43
- ".joycraft/runtime/artifacts/cli.mjs": "d30152e6829e07d9c7ff6ceedbfa6813931674d8529778f62b0d64e3a4049ab0",
44
- ".joycraft/runtime/artifacts/decisions.mjs": "fda4289eb0b7059906e0bd03b6078d1ff6fa45e23a495630721ee84ee84e0f1d",
45
- ".joycraft/runtime/artifacts/model.mjs": "fbe44d37049759387ecc02ba2580c94e26e6c5cb8cac3dcbcc79aeab3b75756b",
46
- ".joycraft/runtime/artifacts/preferences.mjs": "9165e1c753aa8533affe976cacecb135b0ee3cc9f455f5f80b1568103bb49fd6",
43
+ ".joycraft/runtime/artifacts/cli.mjs": "b3472857b6f8f680dc0d8a7be6495c502a430f5d0c47c88d44b42217e541b528",
44
+ ".joycraft/runtime/artifacts/decisions.mjs": "e54fe173ca9050d495fd20b05aaedee8c918f3074553b6b7292cb40f500cbcb2",
45
+ ".joycraft/runtime/artifacts/model.mjs": "1349e081d9ef24b0bbcc1e3d9b220d043917a51e89a3e1798950ed241c8ab41d",
46
+ ".joycraft/runtime/artifacts/preferences.mjs": "859c46cb9639888d0143fec7533962c22faf7accdff43e87ffd72a730b9b71e3",
47
47
  ".joycraft/runtime/artifacts/render.mjs": "488673cab94fa6bfde223c2c41650f8e183f7ac0be3840d371ee057d95ea0fa5",
48
48
  ".joycraft/runtime/artifacts/server.mjs": "0c787812ffbea22c3edb7cb7281e95f54e44da4361f57ac9906487e7b5e6f8e9",
49
49
  ".joycraft/runtime/cleanup.mjs": "9a10dfd27c12f807c71f407352f1526fdb9b4632c523a965952f65d1b7af158c",
@@ -62,7 +62,7 @@
62
62
  ".joycraft/runtime/redact.mjs": "cc8c0fe5e8d8fe78116ef126f6eee757a247739084e19c342bcf09a2b06524bc",
63
63
  ".joycraft/runtime/retro.mjs": "6f3664b0d50c12d4f2d8eef4b4d0d62897939d03e45860d4dcf35c0f5f92677c",
64
64
  ".joycraft/runtime/review-tools.json": "e0b0f5625654bba5f02d49710356aa1740fd42dd282eef6a29af361396915763",
65
- ".joycraft/runtime/review-tools.mjs": "6ca31e651dd10d2d04f2c138c1e1163b3e48b68ad1625d1d804bb8bd3e91e73e",
65
+ ".joycraft/runtime/review-tools.mjs": "15d426558a3884628147debb29136a20f746c3f184c52d6474ad59c222e5d8d5",
66
66
  ".joycraft/runtime/scope.mjs": "e2cdd929596246bf24e18850698db440119badc7068a3c5beab03ded45abbd65",
67
67
  ".joycraft/runtime/status.mjs": "3c5bc62c2c0b440da37af950c28f9278c1f743ff4566d3b6c5685465075239af",
68
68
  ".joycraft/runtime/trace.mjs": "b7924f759b07991f4135698df9c32654631a325957f0f8de5c2ca1262c0a836a",
@@ -71,7 +71,7 @@
71
71
  ".joycraft/runtime/worktrees.mjs": "e5aaa0cfe14b42489c91ead11f12e8a016c468bf66acc07d4b8974e26878e957",
72
72
  ".joycraft/templates/README.md": "56a166d0729e8b6c3bcb098afb8145006259357087fd8b1f1f343d9a2b4d36e0",
73
73
  ".joycraft/templates/artifact.json": "fda5f7c32516d6ab094ee0e8506d84a1a0d6d4d0f49048b01aa392c619996f05",
74
- ".joycraft/templates/brief.md": "03479342500570aba9fb206beef6f6049fd180bec814dd8001987174aecfef25",
74
+ ".joycraft/templates/brief.md": "d9f08a0f77b39dca8fed0a9fa343d013c6730d297ab7111975d08fb3d529b0eb",
75
75
  ".joycraft/templates/decisions.md": "49e0c9b3efe51d1c2e87345fcefe23ef0579e524d50febef8ef43a35141c8002",
76
76
  ".joycraft/templates/joycraft.yaml": "32ec8e9987030485f2a29d9231b2b15c310470d2f1269550e56c4dde0133becf",
77
77
  ".joycraft/templates/project-context.md": "cf2455fef663e647962495175fa6a7a44301c4047eecff5811d9c91e21d9e266",