joycraft 1.1.2 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/dist/joycraft-release.json +1 -1
  2. package/package.json +3 -3
  3. package/payload/.agents/skills/joycraft-decompose/SKILL.md +5 -1
  4. package/payload/.agents/skills/joycraft-entry/SKILL.md +16 -0
  5. package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -0
  6. package/payload/.agents/skills/joycraft-session-end/SKILL.md +1 -1
  7. package/payload/.agents/skills/joycraft-testing/SKILL.md +7 -5
  8. package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +4 -3
  9. package/payload/.agents/skills/joycraft-verify/SKILL.md +1 -1
  10. package/payload/.claude/agents/joycraft-reviewer.md +7 -2
  11. package/payload/.joycraft/contracts/types.d.ts +22 -0
  12. package/payload/.joycraft/references/archive.md +4 -2
  13. package/payload/.joycraft/references/completion.md +55 -2
  14. package/payload/.joycraft/references/dispatch.md +12 -0
  15. package/payload/.joycraft/references/setup.md +36 -12
  16. package/payload/.joycraft/references/testing.md +14 -7
  17. package/payload/.joycraft/references/update.md +8 -0
  18. package/payload/.joycraft/references/workflow.md +3 -2
  19. package/payload/.joycraft/runtime/archive.mjs +19 -4
  20. package/payload/.joycraft/runtime/completion.mjs +210 -10
  21. package/payload/.joycraft/runtime/dispatch-preflight.mjs +16 -3
  22. package/payload/.joycraft/runtime/evidence.mjs +4 -0
  23. package/payload/.joycraft/runtime/identity.mjs +11 -0
  24. package/payload/.joycraft/runtime/review-tools.json +110 -30
  25. package/payload/.joycraft/runtime/review-tools.mjs +650 -126
  26. package/payload/.joycraft/runtime/status.mjs +1 -1
  27. package/payload/.joycraft/runtime/worktrees.mjs +1 -1
  28. package/payload/PIN +27 -27
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "releaseVersion": "1.1.2",
3
+ "releaseVersion": "1.2.0",
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.1.2",
3
+ "version": "1.2.0",
4
4
  "description": "Install and update Joycraft, a skill bundle and runtime for agent-led software work, in any project",
5
5
  "type": "module",
6
6
  "bin": {
@@ -13,8 +13,8 @@
13
13
  "payload"
14
14
  ],
15
15
  "joycraft": {
16
- "release": "1.1.2",
17
- "summary": "After install, your agent builds Joycraft's context map with you and keeps it current; init, update and doctor report an unwired project; cleanup follows doc-cleanup; the update prompt lists every release since yours.",
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.",
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. A check that only a deployed
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,6 +70,22 @@ 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
+ **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
+
73
89
  **Ask answerable questions in an artifact.** When the user must choose between
74
90
  options, record each choice as a brief decision and render the open decisions
75
91
  with the decision artifact (`.joycraft/references/artifacts.md`). Do not list
@@ -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 tools and commands in the `Review loop` section of
29
- `AGENTS.md` (also in the worker packet as `reviewLoop`); a tool it marks skipped
30
- or missing leaves that UI claim UNVERIFIED.
31
- Render and inspect the relevant route, state and viewport.
32
- Perform the interactions the claim needs and observe their outcomes. Fix observed
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 permitted
23
- browser tools; record the route, state, viewport, interactions and observed
24
- outcomes. If blocked, record UNVERIFIED and the reason; respect denials without
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; take the render with the tools and start command in the packet's `reviewLoop` (the `Review loop` section of `AGENTS.md`), and mark a claim whose tool is skipped or missing `UNVERIFIED`. Mark unavailable inspection, a failing result, or an unresolved concern as `UNVERIFIED` or `FAIL` truthfully.
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. Record only
38
- what you observed; mark anything unobserved UNVERIFIED. Keep the final message
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.
@@ -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 or an
37
- explicit `ownerAcceptance` receipt. A normal accepted report must retain its
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
@@ -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 `ownerAcceptance`) 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
+ `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 unavailable work as `UNVERIFIED`, failures as `FAIL`, and limits explicitly.
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
 
@@ -172,24 +172,48 @@ not ignore. When it prints `No packages found`, ask the user which folders hold
172
172
  the apps and pass them as `--packages <dir,dir>` to `plan`, `install` and
173
173
  `record`.
174
174
 
175
- Show the table and ask its one question. Only after the user's yes in this
176
- conversation, run `review-tools.mjs install --root . --yes` (add
177
- `--tools <ids>` for a per-tool choice); it adds project-local tools with the
178
- project's own package manager and lockfile. Never run a system install, `sudo`,
179
- a license acceptance or a sign-in: give the user the printed steps. Then record
180
- the choice, with `--skip <ids>` for declined tools:
175
+ Show the table: what the plan found per package. Ask the user to confirm it or
176
+ name a tool the plan missed, together with its one question. For a gap, say
177
+ plainly that automated review of that package needs a tool that can show the
178
+ work. Recommend one from the hint list (`review-tools.json`), with its
179
+ trade-offs: size, what it can show, cost and licence. Say you are happy to
180
+ research other options. Explain what the install runs and where, then wait for
181
+ the user's yes in this conversation before you run
182
+ `review-tools.mjs install --root . --yes` (add `--tools <ids>` for a per-tool
183
+ choice or a hint the user picked). It adds project-local tools with the
184
+ project's own package manager and lockfile. It also runs a user-scope CLI
185
+ install (`npm install -g`, `brew install`) when the hint marks no `sudo`,
186
+ licence or sign-in. Never run `sudo`, a licence acceptance or a sign-in: give
187
+ the user the printed `steps`. Then record the choice:
181
188
 
182
189
  ```sh
183
- node .joycraft/runtime/review-tools.mjs record --root . --skip <ids>
190
+ node .joycraft/runtime/review-tools.mjs record --root . [--choose <package>=<tool>] [--command <package>=<command>] [--skip <tool>|<package>:<tool>|<package>] [--host <name> --host-tools <observed host tools>]
184
191
  ```
185
192
 
186
- This writes or replaces only the `## Review loop` section of `AGENTS.md`: each
187
- tool, the command that starts the app and the command that takes the evidence.
188
- Worker packets carry that section. For a skipped UI tool, say in one line that
189
- its UI claims stay `UNVERIFIED`. With no network, the probes still run; offer
190
- the install later. For a CI-only project, record the CI job as the evidence
193
+ `--choose` records the tool the user picked for a package (a hint id, or a
194
+ found script with its `--command`); `'apps/*'=<tool>` records one shared harness
195
+ for those packages. `--skip <tool>` skips that missing tool in every package;
196
+ `--skip apps/lab:<tool>` or `--skip apps/lab` skips only that package. Repeat
197
+ `--command` per value. This writes or replaces only the `## Review loop` section
198
+ of `AGENTS.md`: one row per package with its tool, what it can show, the command
199
+ that starts the app and the command that takes the evidence. Recording again
200
+ keeps earlier choices and skips for packages the call does not name. Host tools
201
+ go to the git-ignored `.joycraft/local/review-loop.json`, never `AGENTS.md`.
202
+ Worker packets carry both. A skipped package's row says it is not reviewed
203
+ (user skipped). With no network, the probes still run; offer the install later. For a CI-only project, record the CI job as the evidence
191
204
  source when the user picks it.
192
205
 
206
+ **Change a tool.** Talk about the review loop only here: at install, at
207
+ setup and upgrade when the plan reports a change, and when the user asks to
208
+ try, switch, add or remove a tool ("try Maestro for the iOS app"). For a
209
+ request, confirm or research the tool, install it as above, and re-record only
210
+ that package with `--choose <package>=<tool>` (or `--skip` to remove one);
211
+ other rows stay. When the plan's `Changed since the recorded Review loop` names
212
+ a newly detected tool, offer to switch that package to it. When it reports
213
+ `recorded with v1; re-record to keep it`, confirm the table with the user and run
214
+ record again, repeating any `--choose` or `--skip` the table shows; a v1 record
215
+ does not carry them over. An unchanged project asks nothing.
216
+
193
217
  `review-tools.json` also lists `optIn` tools that detection never plans. Offer
194
218
  one only when it fits the project. Example: Doc Detective, for docs that are
195
219
  step-by-step procedures. Say what it does not cover and that it is AGPL-3.0 with a
@@ -94,20 +94,27 @@ an accepted reference only when that reference is part of the requirement or is
94
94
  available and relevant to the comparison. This does not create a universal
95
95
  before/after gate.
96
96
 
97
+ Take visual evidence with the package's recorded tool from the packet's
98
+ `reviewLoop` (shared `section` plus `local` host tools), within its `canShow`.
97
99
  An empty `visual.interactions` list is appropriate for a static appearance-only
98
- claim. For an interactive requirement, the reviewer must require the relevant
99
- actions and outcomes; the validator cannot infer them from a criterion id. A
100
+ claim or a tool whose `canShow` has no `interact`. A limit the user agreed to is
101
+ not UNVERIFIED: the reviewer reports how it checked and the parent agent judges
102
+ what is left. For an interactive requirement whose tool can interact, the
103
+ reviewer must require the relevant actions and outcomes; the validator cannot
104
+ infer them from a criterion id. A
100
105
  disabled control or error state can itself be an observed result; explain it.
101
106
 
102
107
  When an inspection finds a scoped defect: retain the observation, fix it, render
103
108
  again, repeat affected interactions and inspect the result. If the fix changes a
104
109
  bound input, obtain a new subject and fresh affected observations before seeking
105
110
  completion. Keep the final flow concise and link prior diagnostics rather than
106
- copying a transcript. An unavailable browser, inaccessible route or blocked tool
107
- is a limit and UNVERIFIED check, not permission to bypass access controls or
108
- declare visual PASS. Do not wrap, relay, or otherwise route around a denied
109
- command; ask the host for the legitimate correction. Continue independent work
110
- that remains possible.
111
+ copying a transcript. A recorded tool that stopped working (a browser that
112
+ will not launch) is a tool break: an UNVERIFIED check with `cause: 'tool-break'`,
113
+ not an agreed limit. A route the app does not serve can be an app defect and a
114
+ FAIL. A command the host denies is not a tool break. None of these permits
115
+ bypassing access controls or declaring visual PASS.
116
+ Do not wrap, relay, or otherwise route around a denied command; ask the host for
117
+ the legitimate correction. Continue independent work that remains possible.
111
118
 
112
119
  ## Where checks run
113
120
 
@@ -29,6 +29,14 @@ Use the version from `latest`:
29
29
  apply a migration without the user's yes.
30
30
  3. Run `npx joycraft@<latest> doctor .`.
31
31
  4. Tell the user in plain words what is different now.
32
+ 5. Run the review-loop plan
33
+ ([review loop tools](setup.md#review-loop-tools)). When it prints
34
+ `Review loop unchanged.`, say nothing about it. When it reports a newly
35
+ detected tool, offer to switch that package to it and re-record only that
36
+ package with `--choose`.
37
+ When it reports `recorded with v1; re-record to keep it`, confirm the table with the
38
+ user and run record again, repeating any `--choose` or `--skip` the table shows; a
39
+ v1 record does not carry them over.
32
40
 
33
41
  If the update fails, run `npx joycraft@<latest> update . --recover`, tell the user
34
42
  that the files are back as they were, and continue your work.
@@ -68,8 +68,9 @@ outcomes, viewport, route/state and limits. A screenshot or static render is
68
68
  enough for an appearance-only choice only when it is actually inspected; it cannot
69
69
  prove that the answer was saved. Ask concise visual-detail questions before making
70
70
  a pixel-sensitive choice when the available render leaves them material. Check
71
- both file state and reload. If tools are unavailable or denied, mark required
72
- visual work UNVERIFIED and continue disjoint work. Never bypass a denial with
71
+ both file state and reload. If a recorded tool breaks or is denied, mark required
72
+ visual work UNVERIFIED and continue disjoint work; a limit the user agreed to is
73
+ not UNVERIFIED. Never bypass a denial with
73
74
  another route.
74
75
 
75
76
  ## Commitment and queue
@@ -4,7 +4,7 @@ import path from 'node:path';
4
4
  import { pathToFileURL } from 'node:url';
5
5
  import { boundQueueForSubject, briefDecisionRecords, canonical, isObject, isSha256, localPath, nonempty, normalizedQueueForSubject, parseJson, readLocal, readQueue, relativePath, requireValue, scopedRequirementForSubject, sha256, specStatus, subjectIdentity, validateIndependentReview } from './identity.mjs';
6
6
  import { validateEvidence } from './evidence.mjs';
7
- import { validateOwnerAcceptance } from './completion.mjs';
7
+ import { validateOwnerAcceptance, validateWaiver } from './completion.mjs';
8
8
  import { readConfig, workPaths } from './config.mjs';
9
9
 
10
10
  const featureName = value => {
@@ -262,7 +262,22 @@ const validTimestamp = value => typeof value === 'string' && nonempty(value) &&
262
262
  function historicalDecision(root, queuePath, state, reconciliation) {
263
263
  const accepted = state.spec.acceptedReport;
264
264
  const owner = state.spec.ownerAcceptance;
265
- requireValue(!(accepted !== undefined && owner !== undefined), `Spec ${state.spec.id} has both acceptedReport and ownerAcceptance`);
265
+ const waiver = state.spec.waiver;
266
+ requireValue([accepted, owner, waiver].filter(item => item !== undefined).length <= 1, `Spec ${state.spec.id} has more than one of acceptedReport, ownerAcceptance and waiver`);
267
+ if (waiver !== undefined) {
268
+ // The brief may evolve after completion; the waiver bytes and record stay bound.
269
+ requireValue(isObject(waiver) && isSha256(waiver.sha256), `Spec ${state.spec.id} has a malformed waiver`);
270
+ const waiverPath = relativePath(waiver.path);
271
+ const waiverBytes = readLocal(root, waiverPath);
272
+ requireValue(sha256(waiverBytes) === waiver.sha256, `Feature waiver is missing or changed: ${waiverPath}`);
273
+ const record = parseJson(waiverBytes, waiverPath);
274
+ validateWaiver({ root, waiver: record, waiverPath, state, checkSource: false });
275
+ const limitations = [`waived by the user: "${record.instruction}"`];
276
+ if (waiver.review === undefined) return { kind: 'feature-waiver', path: waiverPath, sha256: waiver.sha256, report: null, covers: record.covers, receipts: [], limitations };
277
+ const report = historicalReport(root, queuePath, state, waiver.review, { ownerAccepted: true, reconciliation });
278
+ requireValue(report.verdict === 'UNVERIFIED', `Waived report must stay UNVERIFIED: ${report.path}`);
279
+ return { kind: 'feature-waiver', path: waiverPath, sha256: waiver.sha256, report: { path: report.path, sha256: report.sha256, verdict: report.verdict }, covers: record.covers, receipts: report.receipts, limitations, ...(report.requirementHistory ? { requirementHistory: report.requirementHistory } : {}) };
280
+ }
266
281
  if (accepted !== undefined) {
267
282
  const report = historicalReport(root, queuePath, state, accepted, { reconciliation });
268
283
  return { kind: 'accepted-report', path: report.path, sha256: report.sha256, report: { path: report.path, sha256: report.sha256, verdict: report.verdict }, receipts: report.receipts, limitations: [], ...(report.requirementHistory ? { requirementHistory: report.requirementHistory } : {}) };
@@ -305,7 +320,7 @@ function existingArchive(root, feature) {
305
320
  if (['queue-scope', 'queue-status', 'spec-status'].includes(record.normalization) || record.reconciliationEntry !== undefined) {
306
321
  requireValue(manifest.reconciliation && record.reconciliationSha256 === manifest.reconciliation.sha256 && Number.isInteger(record.reconciliationEntry), `Reconciled replay has no matching paper trail: ${archivedPath}`);
307
322
  const entry = manifest.reconciliation.record.entries[record.reconciliationEntry];
308
- requireValue(entry && entry.path === record.path && entry.normalization === record.normalization && entry.acceptedSha256 === record.acceptedSha256 && (entry.acceptedCommit === undefined || entry.acceptedCommit === record.acceptedCommit) && manifest.evidence.some(decision => decision.report.path === entry.report.path && decision.report.sha256 === entry.report.sha256 && decision.requirementHistory?.some(item => canonical(item) === canonical(record))) && manifest.files.some(item => ['moved', 'copied'].includes(item.operation) && item.originalPath === entry.path && item.sha256 === entry.currentSha256), `Reconciled replay differs from its paper trail: ${archivedPath}`);
323
+ requireValue(entry && entry.path === record.path && entry.normalization === record.normalization && entry.acceptedSha256 === record.acceptedSha256 && (entry.acceptedCommit === undefined || entry.acceptedCommit === record.acceptedCommit) && manifest.evidence.some(decision => decision.report?.path === entry.report.path && decision.report?.sha256 === entry.report.sha256 && decision.requirementHistory?.some(item => canonical(item) === canonical(record))) && manifest.files.some(item => ['moved', 'copied'].includes(item.operation) && item.originalPath === entry.path && item.sha256 === entry.currentSha256), `Reconciled replay differs from its paper trail: ${archivedPath}`);
309
324
  }
310
325
  requireValue(archivedPath === restoredPath(destination, record) && sha256(requirementProjection(bytes, record)) === record.acceptedSha256, `Restored requirement does not match acceptance: ${archivedPath}`);
311
326
  }
@@ -354,7 +369,7 @@ export function previewArchiveFeature({ root = process.cwd(), feature, phase, at
354
369
  if (reconciliation) requireValue(reconciliation.used.size === reconciliation.record.entries.length, 'Archive reconciliation contains unused or stale entries');
355
370
  const copies = new Map();
356
371
  for (const decision of evidence) {
357
- for (const evidencePath of [decision.path, decision.report.path, ...decision.receipts.map(receipt => receipt.path)]) {
372
+ for (const evidencePath of [decision.path, decision.report?.path, ...decision.receipts.map(receipt => receipt.path)].filter(Boolean)) {
358
373
  if (!evidencePath.startsWith(`${source}/`)) copies.set(evidencePath, fileDigest(root, evidencePath));
359
374
  }
360
375
  }